offapi/com/sun/star/ucb/PackageFolderContent.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: PackageFolderContent.idl,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_ucb_PackageFolderContent_idl__
  31 #define __com_sun_star_ucb_PackageFolderContent_idl__
  32
  33 #ifndef __com_sun_star_lang_XComponent_idl__
  34 #include <com/sun/star/lang/XComponent.idl>
  35 #endif
  36
  37 #ifndef __com_sun_star_ucb_XContent_idl__
  38 #include <com/sun/star/ucb/XContent.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_ucb_XCommandProcessor_idl__
  42 #include <com/sun/star/ucb/XCommandProcessor.idl>
  43 #endif
  44
  45 #ifndef __com_sun_star_ucb_XCommandProcessor2_idl__
  46 #include <com/sun/star/ucb/XCommandProcessor2.idl>
  47 #endif
  48
  49 #ifndef __com_sun_star_beans_XPropertiesChangeNotifier_idl__
  50 #include <com/sun/star/beans/XPropertiesChangeNotifier.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_beans_XPropertyContainer_idl__
  54 #include <com/sun/star/beans/XPropertyContainer.idl>
  55 #endif
  56
  57 #ifndef __com_sun_star_beans_XPropertySetInfoChangeNotifier_idl__
  58 #include <com/sun/star/beans/XPropertySetInfoChangeNotifier.idl>
  59 #endif
  60
  61 #ifndef __com_sun_star_ucb_XCommandInfoChangeNotifier_idl__
  62 #include <com/sun/star/ucb/XCommandInfoChangeNotifier.idl>
  63 #endif
  64
  65 #ifndef __com_sun_star_container_XChild_idl__
  66 #include <com/sun/star/container/XChild.idl>
  67 #endif
  68
  69 #ifndef __com_sun_star_ucb_XContentCreator_idl__
  70 #include <com/sun/star/ucb/XContentCreator.idl>
  71 #endif
  72
  73 //=============================================================================
  74
  75 module com { module sun { module star { module ucb {
  76
  77 //=============================================================================
  78 /** A PCP Folder is a container for other PCP Folders and PCP Streams.
  79
  80     @see com::sun::star::ucb::PackageContentProvider
  81     @see com::sun::star::ucb::PackageStreamContent
  82 */
  83 published service PackageFolderContent
  84 {
  85     //-------------------------------------------------------------------------
  86     /** This interface is implemented according to the specification of
  87         service <type>Content</type>.
  88      */
  89     interface com::sun::star::lang::XComponent;
  90
  91     //-------------------------------------------------------------------------
  92     /** This interface is implemented according to the specification of
  93         service <type>Content</type>.
  94      */
  95     interface com::sun::star::ucb::XContent;
  96
  97     //-------------------------------------------------------------------------
  98     /** This interface is implemented according to the specification of
  99         service <type>Content</type>.
 100
 101         <p>
 102
 103         <b>Supported Commands</b>
 104         <ul>
 105         <li>
 106         getCommandInfo
 107         </li>
 108         <li>
 109         getPropertySetInfo
 110         </li>
 111         <li>
 112         getPropertyValues
 113         </li>
 114         <li>
 115         setPropertyValues
 116         </li>
 117         <li>
 118         insert ( makes a newly created folder persistent )
 119         </li>
 120         <li>
 121         delete
 122         </li>
 123         <li>
 124         open
 125         </li>
 126         <li>
 127         transfer ( only transfers from PCP Folders/PCP Streams to other
 128         PCP folders. It does not handle contents with a URL scheme other
 129         then the PCP-URL-scheme. )
 130         </li>
 131         <li>
 132         flush ( a command introduced by the PCP Folder. It takes a
 133         void-argument and returns void. This command is used to write unsaved
 134         changes to the underlying package file. Note that the current
 135         implementation of PCP contents never flushes automatically! Operations
 136         which require a flush to get persistent, are:
 137         "setPropertyValues( < any_non_read_only_property > ) ", "delete",
 138         "insert" )
 139         </li>
 140         </ul>
 141
 142         <b>Supported Properties</b>
 143         <ul>
 144         <li>
 145         string ContentType ( read-only, always "application/vnd.sun.star.pkg-folder" )
 146         </li>
 147         <li>
 148         boolean IsDocument ( read-only, always false )
 149         </li>
 150         <li>
 151         boolean IsFolder ( read-only, always true )
 152         </li>
 153         <li>
 154         string MediaType
 155         </li>
 156         <li>
 157         string Title
 158         </li>
 159         </ul>
 160
 161         </p>
 162      */
 163     interface com::sun::star::ucb::XCommandProcessor;
 164
 165     //-------------------------------------------------------------------------
 166     /** is an enhanced version of <type>XCommandProcessor</type> that has an
 167         additional method for releasing command identifiers obtained via
 168         <member>XCommandProcessor::createCommandIdentifier</member> to avoid
 169         resource leaks. For a detailed description of the problem refer to
 170         <member>XCommandProcessor2::releaseCommandIdentifier</member>.
 171
 172         <p>Where many existing <type>Content</type> implementations do not
 173         (yet), every new implementation should support this interface.
 174      */
 175     [optional] interface com::sun::star::ucb::XCommandProcessor2;
 176
 177     //-------------------------------------------------------------------------
 178     /** This interface is implemented according to the specification of
 179         service <type>Content</type>.
 180      */
 181     interface com::sun::star::beans::XPropertiesChangeNotifier;
 182
 183     //-------------------------------------------------------------------------
 184     /** This interface is implemented according to the specification of
 185         service <type>Content</type>.
 186      */
 187     interface com::sun::star::beans::XPropertyContainer;
 188
 189     //-------------------------------------------------------------------------
 190     /** This interface is implemented according to the specification of
 191         service <type>Content</type>.
 192      */
 193     interface com::sun::star::beans::XPropertySetInfoChangeNotifier;
 194
 195     //-------------------------------------------------------------------------
 196     /** This interface is implemented according to the specification of
 197         service <type>Content</type>.
 198      */
 199     interface com::sun::star::ucb::XCommandInfoChangeNotifier;
 200
 201     //-------------------------------------------------------------------------
 202     /** This interface is implemented according to the specification of
 203         service <type>Content</type>.
 204      */
 205     interface com::sun::star::container::XChild;
 206
 207     //-------------------------------------------------------------------------
 208     /** This interface is implemented according to the specification of
 209         service <type>Content</type>.
 210
 211         <p>
 212
 213         A PCP Folder can create other PCP Folders and PCP Streams. To create
 214         a new child of a PCP Folder:
 215
 216         <ol>
 217         <li>
 218         Let the parent folder create a new content by calling
 219         <member>XContentCreator::createNewContent</member> on it. The content
 220         type to use for new folders is "application/vnd.sun.star.pkg-folder".
 221         To create a new PCP Stream, use the type
 222         "application/vnd.sun.star.pkg-stream".
 223         </li>
 224         <li>
 225         Set a title at the new folder / stream. ( Let the new child execute
 226         the command "setPropertyValues", which sets at least the property
 227         "Title" to a non-empty value ).
 228         </li>
 229         <li>
 230         Let the new child ( not the parent! ) execute the command "insert".
 231         This will commit the creation process. For streams, you need to supply
 232         the implementation of an
 233         <type scope="com::sun::star::io">XInputStream</type> with the command's
 234         parameters, that provides access to the stream data.
 235         </li>
 236         </ol>
 237
 238         </p>
 239
 240         <p>
 241         Another, more convenient way for creating streams is simply to assemble
 242         the URL for the new content ( last part of the path will become the
 243         title of the new stream ) and to obtain a Content object for that URL
 244         from the UCB. Then let the content execute the command "insert". The
 245         command will fail, if you set the command's parameter
 246         <member>InsertCommandArgument::ReplaceExisting"</member>
 247         to false and there is already a stream with the title given by the
 248         content's URL.
 249
 250         </p>
 251      */
 252     interface com::sun::star::ucb::XContentCreator;
 253 };
 254
 255 //=============================================================================
 256
 257 }; }; }; };
 258
 259 #endif