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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_ucb_PackageFolderContent_idl__
  20 #define __com_sun_star_ucb_PackageFolderContent_idl__
  21
  22 #include <com/sun/star/lang/XComponent.idl>
  23 #include <com/sun/star/ucb/XContent.idl>
  24 #include <com/sun/star/ucb/XCommandProcessor.idl>
  25 #include <com/sun/star/ucb/XCommandProcessor2.idl>
  26 #include <com/sun/star/beans/XPropertiesChangeNotifier.idl>
  27 #include <com/sun/star/beans/XPropertyContainer.idl>
  28 #include <com/sun/star/beans/XPropertySetInfoChangeNotifier.idl>
  29 #include <com/sun/star/ucb/XCommandInfoChangeNotifier.idl>
  30 #include <com/sun/star/container/XChild.idl>
  31 #include <com/sun/star/ucb/XContentCreator.idl>
  32
  33
  34 module com { module sun { module star { module ucb {
  35
  36 /** A PCP Folder is a container for other PCP Folders and PCP Streams.
  37
  38     @see com::sun::star::ucb::PackageContentProvider
  39     @see com::sun::star::ucb::PackageStreamContent
  40 */
  41 published service PackageFolderContent
  42 {
  43     /** This interface is implemented according to the specification of
  44         service Content.
  45      */
  46     interface com::sun::star::lang::XComponent;
  47
  48     /** This interface is implemented according to the specification of
  49         service Content.
  50      */
  51     interface com::sun::star::ucb::XContent;
  52
  53     /** This interface is implemented according to the specification of
  54         service Content.
  55
  56         <p>
  57
  58         <b>Supported Commands</b>
  59         <ul>
  60         <li>
  61         getCommandInfo
  62         </li>
  63         <li>
  64         getPropertySetInfo
  65         </li>
  66         <li>
  67         getPropertyValues
  68         </li>
  69         <li>
  70         setPropertyValues
  71         </li>
  72         <li>
  73         insert ( makes a newly created folder persistent )
  74         </li>
  75         <li>
  76         delete
  77         </li>
  78         <li>
  79         open
  80         </li>
  81         <li>
  82         transfer ( only transfers from PCP Folders/PCP Streams to other
  83         PCP folders. It does not handle contents with a URL scheme other
  84         then the PCP-URL-scheme. )
  85         </li>
  86         <li>
  87         flush ( a command introduced by the PCP Folder. It takes a
  88         void-argument and returns void. This command is used to write unsaved
  89         changes to the underlying package file. Note that the current
  90         implementation of PCP contents never flushes automatically! Operations
  91         which require a flush to get persistent, are:
  92         "setPropertyValues( < any_non_read_only_property > ) ", "delete",
  93         "insert" )
  94         </li>
  95         </ul>
  96
  97         <b>Supported Properties</b>
  98         <ul>
  99         <li>
 100         string ContentType ( read-only, always "application/vnd.sun.star.pkg-folder" )
 101         </li>
 102         <li>
 103         boolean IsDocument ( read-only, always false )
 104         </li>
 105         <li>
 106         boolean IsFolder ( read-only, always true )
 107         </li>
 108         <li>
 109         string MediaType
 110         </li>
 111         <li>
 112         string Title
 113         </li>
 114         </ul>
 115
 116         </p>
 117      */
 118     interface com::sun::star::ucb::XCommandProcessor;
 119
 120     /** is an enhanced version of XCommandProcessor that has an
 121         additional method for releasing command identifiers obtained via
 122         XCommandProcessor::createCommandIdentifier() to avoid
 123         resource leaks. For a detailed description of the problem refer to
 124         XCommandProcessor2::releaseCommandIdentifier().
 125
 126         <p>Where many existing Content implementations do not
 127         (yet), every new implementation should support this interface.
 128      */
 129     [optional] interface com::sun::star::ucb::XCommandProcessor2;
 130
 131     /** This interface is implemented according to the specification of
 132         service Content.
 133      */
 134     interface com::sun::star::beans::XPropertiesChangeNotifier;
 135
 136     /** This interface is implemented according to the specification of
 137         service Content.
 138      */
 139     interface com::sun::star::beans::XPropertyContainer;
 140
 141     /** This interface is implemented according to the specification of
 142         service Content.
 143      */
 144     interface com::sun::star::beans::XPropertySetInfoChangeNotifier;
 145
 146     /** This interface is implemented according to the specification of
 147         service Content.
 148      */
 149     interface com::sun::star::ucb::XCommandInfoChangeNotifier;
 150
 151     /** This interface is implemented according to the specification of
 152         service Content.
 153      */
 154     interface com::sun::star::container::XChild;
 155
 156     /** This interface is implemented according to the specification of
 157         service Content.
 158
 159         <p>
 160
 161         A PCP Folder can create other PCP Folders and PCP Streams. To create
 162         a new child of a PCP Folder:
 163
 164         <ol>
 165         <li>
 166         Let the parent folder create a new content by calling
 167         XContentCreator::createNewContent() on it. The content
 168         type to use for new folders is "application/vnd.sun.star.pkg-folder".
 169         To create a new PCP Stream, use the type
 170         "application/vnd.sun.star.pkg-stream".
 171         </li>
 172         <li>
 173         Set a title at the new folder / stream. ( Let the new child execute
 174         the command "setPropertyValues", which sets at least the property
 175         "Title" to a non-empty value ).
 176         </li>
 177         <li>
 178         Let the new child ( not the parent! ) execute the command "insert".
 179         This will commit the creation process. For streams, you need to supply
 180         the implementation of an
 181         com::sun::star::io::XInputStream with the command's
 182         parameters, that provides access to the stream data.
 183         </li>
 184         </ol>
 185
 186         </p>
 187
 188         <p>
 189         Another, more convenient way for creating streams is simply to assemble
 190         the URL for the new content ( last part of the path will become the
 191         title of the new stream ) and to obtain a Content object for that URL
 192         from the UCB. Then let the content execute the command "insert". The
 193         command will fail, if you set the command's parameter
 194         InsertCommandArgument::ReplaceExisting"
 195         to false and there is already a stream with the title given by the
 196         content's URL.
 197
 198         </p>
 199      */
 200     interface com::sun::star::ucb::XContentCreator;
 201 };
 202
 203
 204 }; }; }; };
 205
 206 #endif
 207
 208 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */