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
  20
  21 module com { module sun { module star { module ucb {
  22
  23 /** A PCP Folder is a container for other PCP Folders and PCP Streams.
  24
  25     @see com::sun::star::ucb::PackageContentProvider
  26     @see com::sun::star::ucb::PackageStreamContent
  27 */
  28 published service PackageFolderContent
  29 {
  30     /** This interface is implemented according to the specification of
  31         service Content.
  32      */
  33     interface com::sun::star::lang::XComponent;
  34
  35     /** This interface is implemented according to the specification of
  36         service Content.
  37      */
  38     interface com::sun::star::ucb::XContent;
  39
  40     /** This interface is implemented according to the specification of
  41         service Content.
  42
  43         <p>
  44
  45         <b>Supported Commands</b>
  46         <ul>
  47         <li>
  48         getCommandInfo
  49         </li>
  50         <li>
  51         getPropertySetInfo
  52         </li>
  53         <li>
  54         getPropertyValues
  55         </li>
  56         <li>
  57         setPropertyValues
  58         </li>
  59         <li>
  60         insert ( makes a newly created folder persistent )
  61         </li>
  62         <li>
  63         delete
  64         </li>
  65         <li>
  66         open
  67         </li>
  68         <li>
  69         transfer ( only transfers from PCP Folders/PCP Streams to other
  70         PCP folders. It does not handle contents with a URL scheme other
  71         then the PCP-URL-scheme. )
  72         </li>
  73         <li>
  74         flush ( a command introduced by the PCP Folder. It takes a
  75         void-argument and returns void. This command is used to write unsaved
  76         changes to the underlying package file. Note that the current
  77         implementation of PCP contents never flushes automatically! Operations
  78         which require a flush to get persistent, are:
  79         "setPropertyValues( < any_non_read_only_property > ) ", "delete",
  80         "insert" )
  81         </li>
  82         </ul>
  83
  84         <b>Supported Properties</b>
  85         <ul>
  86         <li>
  87         string ContentType ( read-only, always "application/vnd.sun.star.pkg-folder" )
  88         </li>
  89         <li>
  90         boolean IsDocument ( read-only, always false )
  91         </li>
  92         <li>
  93         boolean IsFolder ( read-only, always true )
  94         </li>
  95         <li>
  96         string MediaType
  97         </li>
  98         <li>
  99         string Title
 100         </li>
 101         </ul>
 102
 103         </p>
 104      */
 105     interface com::sun::star::ucb::XCommandProcessor;
 106
 107     /** is an enhanced version of XCommandProcessor that has an
 108         additional method for releasing command identifiers obtained via
 109         XCommandProcessor::createCommandIdentifier() to avoid
 110         resource leaks. For a detailed description of the problem refer to
 111         XCommandProcessor2::releaseCommandIdentifier().
 112
 113         <p>Where many existing Content implementations do not
 114         (yet), every new implementation should support this interface.
 115      */
 116     [optional] interface com::sun::star::ucb::XCommandProcessor2;
 117
 118     /** This interface is implemented according to the specification of
 119         service Content.
 120      */
 121     interface com::sun::star::beans::XPropertiesChangeNotifier;
 122
 123     /** This interface is implemented according to the specification of
 124         service Content.
 125      */
 126     interface com::sun::star::beans::XPropertyContainer;
 127
 128     /** This interface is implemented according to the specification of
 129         service Content.
 130      */
 131     interface com::sun::star::beans::XPropertySetInfoChangeNotifier;
 132
 133     /** This interface is implemented according to the specification of
 134         service Content.
 135      */
 136     interface com::sun::star::ucb::XCommandInfoChangeNotifier;
 137
 138     /** This interface is implemented according to the specification of
 139         service Content.
 140      */
 141     interface com::sun::star::container::XChild;
 142
 143     /** This interface is implemented according to the specification of
 144         service Content.
 145
 146         <p>
 147
 148         A PCP Folder can create other PCP Folders and PCP Streams. To create
 149         a new child of a PCP Folder:
 150
 151         <ol>
 152         <li>
 153         Let the parent folder create a new content by calling
 154         XContentCreator::createNewContent() on it. The content
 155         type to use for new folders is "application/vnd.sun.star.pkg-folder".
 156         To create a new PCP Stream, use the type
 157         "application/vnd.sun.star.pkg-stream".
 158         </li>
 159         <li>
 160         Set a title at the new folder / stream. ( Let the new child execute
 161         the command "setPropertyValues", which sets at least the property
 162         "Title" to a non-empty value ).
 163         </li>
 164         <li>
 165         Let the new child ( not the parent! ) execute the command "insert".
 166         This will commit the creation process. For streams, you need to supply
 167         the implementation of an
 168         com::sun::star::io::XInputStream with the command's
 169         parameters, that provides access to the stream data.
 170         </li>
 171         </ol>
 172
 173         </p>
 174
 175         <p>
 176         Another, more convenient way for creating streams is simply to assemble
 177         the URL for the new content ( last part of the path will become the
 178         title of the new stream ) and to obtain a Content object for that URL
 179         from the UCB. Then let the content execute the command "insert". The
 180         command will fail, if you set the command's parameter
 181         InsertCommandArgument::ReplaceExisting"
 182         to false and there is already a stream with the title given by the
 183         content's URL.
 184
 185         </p>
 186      */
 187     interface com::sun::star::ucb::XContentCreator;
 188 };
 189
 190
 191 }; }; }; };
 192
 193 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */