offapi/com/sun/star/embed/Storage.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef __com_sun_star_embed_Storage_idl__
  29 #define __com_sun_star_embed_Storage_idl__
  30
  31 #ifndef __com_sun_star_embed_BaseStorage_idl__
  32 #include <com/sun/star/embed/BaseStorage.idl>
  33 #endif
  34
  35 #ifndef __com_sun_star_embed_XEncryptionProtectedSource_idl__
  36 #include <com/sun/star/embed/XEncryptionProtectedSource.idl>
  37 #endif
  38
  39 #ifndef __com_sun_star_embed_XTransactedObject_idl__
  40 #include <com/sun/star/embed/XTransactedObject.idl>
  41 #endif
  42
  43 #ifndef __com_sun_star_embed_XTransactionBroadcaster_idl__
  44 #include <com/sun/star/embed/XTransactionBroadcaster.idl>
  45 #endif
  46
  47 #ifndef __com_sun_star_util_XModifiable_idl__
  48 #include <com/sun/star/util/XModifiable.idl>
  49 #endif
  50
  51 #ifndef __com_sun_star_container_XNameAccess_idl__
  52 #include <com/sun/star/container/XNameAccess.idl>
  53 #endif
  54
  55 #ifndef __com_sun_star_lang_XComponent_idl__
  56 #include <com/sun/star/lang/XComponent.idl>
  57 #endif
  58
  59 #ifndef __com_sun_star_beans_XPropertySet_idl__
  60 #include <com/sun/star/beans/XPropertySet.idl>
  61 #endif
  62
  63
  64 //============================================================================
  65
  66  module com {  module sun {  module star {  module embed {
  67
  68 //============================================================================
  69 /** This is a service that allows to get access to a package using storage
  70     hierarchy.
  71
  72     <p>
  73     A root storage should be retrieved by using <type>StorageFactory</type>
  74     service. Substorages are created through <type>XStorage</type> interface
  75     of a parent storage.
  76     </p>
  77  */
  78 published service Storage
  79 {
  80     // -----------------------------------------------------------------------
  81     /** This service describes the base functionality of storages.
  82
  83         <p>
  84         Please see below the description of additional requirements for the
  85         package storage implementation.
  86         </p>
  87
  88         <dl>
  89             <dt>interface <type scope="com::sun::star::lang">XComponent</type>
  90             </dt>
  91             <dd>
  92                 <p>
  93                 A root storage is created by <type>StorageFactory</type>
  94                 and is controlled by refcounting. In case refcounting
  95                 is decreased to zero the storage will be disposed
  96                 automatically. It is still strongly recommended that
  97                 a root storage is disposed explicitly since in garbage
  98                 collector based languages the refcounting can be
  99                 decreased too late and resources locked by the storage
 100                 will not be freed until then.
 101                 </p>
 102
 103                 <p>
 104                 A substorage is created by <type>XStorage</type>
 105                 interface of storage. Each time a substorage is opened
 106                 it is locked ( in case it is opened in readonly mode
 107                 it is locked for writing, in case it is opened in
 108                 read-write mode it is locked for reading and writing )
 109                 until it is disposed.  The lifetime of substorage is
 110                 also controlled by refcounting but because of mentioned
 111                 garbage collection specific it is strongly recommended
 112                 to dispose substorages explicitly.
 113                 </p>
 114
 115                 <p>
 116                 In case a storage object is disposed all the elements
 117                 ( substorages and substreams ) retrieved from the
 118                 object are disposed. If the storage was opened in
 119                 read-write mode all noncommited changes will be lost.
 120                 </p>
 121             </dd>
 122             <dt>interface <type>XStorage</type></dt>
 123             <dd>
 124                 <dl>
 125                     <dt><method>XStorage::openStreamElement</method></dt>
 126                     <dd>
 127                         <p>
 128                         This method returns <type>StorageStream</type>
 129                         service implementation.
 130                         </p>
 131
 132                         <p>
 133                         If the child stream is an encrypted one a corect
 134                         common storage password should be set through
 135                         <type>XEncryptionProtectedSource</type> interface to
 136                         this storage or to a one of storages in parent
 137                         hierarchy. In case the password is not set or is a
 138                         wrong one an exception will be thrown.
 139                         </p>
 140                     </dd>
 141
 142                     <dt><method>XStorage::openEncryptedStreamElement</method></dt>
 143                     <dd>
 144                         This method allows to specify reading password for the
 145                         stream explicitly. The password will be used to read
 146                         the stream. It is possible to specify a new password
 147                         for stream storing through
 148                         <type>XEncryptionProtectedSource</type> interface. In
 149                         case a new password is not specified an old one will
 150                         be used for storing.
 151                     </dd>
 152
 153                     <dt><method>XStorage::openStorageElement</method></dt>
 154                     <dd>
 155                         This method returns <type>Storage</type> service
 156                         implementation.
 157                     </dd>
 158
 159                     <dt><method>XStorage::cloneStreamElement</method></dt>
 160                     <dd>
 161                         <p>
 162                         This method returns <type>StorageStream</type> service
 163                         implementation.
 164                         </p>
 165
 166                         <p>
 167                         The latest flashed version of the stream will be used.
 168                         The stream can be flashed explicitly by
 169                         <method scope="com::sun::star::io">XOutputStream::flush</method>
 170                         call.
 171                         </p>
 172
 173                         <p>
 174                         A storage flashes on commit all the child streams it
 175                         owns. So in case after the stream is changed neither
 176                         the storage was commited nor the stream was flushed
 177                         explicitly, the changes will not appear in the new
 178                         created stream. This method allows to retrieve copy of
 179                         a child stream even in case it is already opened for
 180                         writing.
 181                         </p>
 182
 183                         <p>
 184                         If the child stream is an encrypted one a corect
 185                         common storage password should be set through
 186                         <type>XEncryptionProtectedSource</type> interface to
 187                         this storage or to a one of storages in parent
 188                         hierarchy. In case the password is not set or is a
 189                         wrong one an exception will be thrown.
 190                         </p>
 191                     </dd>
 192
 193                     <dt><method>XStorage::cloneEncryptedStreamElement</method></dt>
 194                     <dd>
 195                         <p>
 196                         This method returns <type>StorageStream</type> service
 197                         implementation.
 198                         </p>
 199
 200                         <p>
 201                         The latest flashed version of the stream will be used.
 202                         The stream can be flashed explicitly by
 203                         <method scope="com::sun::star::io">XOutputStream::flush</method>
 204                         call.
 205                         </p>
 206
 207                         <p>
 208                         A storage flashes on commit all the child streams it
 209                         owns. So in case after the stream is changed neither
 210                         the storage was commited nor the stream was flushed
 211                         explicitly, the changes will not appear in the new
 212                         created stream. This method allows to retrieve copy of
 213                         a child stream even in case it is already opened for
 214                         writing.
 215                         </p>
 216                     </dd>
 217
 218                     <dt><method>XStorage::copyLastCommitTo</method></dt>
 219                     <dd>
 220                         This method gets <type>Storage</type> service
 221                         implementation and fills it in with the latest
 222                         commited version of this storage. So in case the
 223                         storage was not commited after it was changed, the
 224                         changes will not appear in the new created storage.
 225                     </dd>
 226
 227                     <dt><method>XStorage::copyStorageElementLastCommitTo</method></dt>
 228                     <dd>
 229                         <p>
 230                         This method gets <type>Storage</type> service
 231                         implementation and fills it in with the contents of
 232                         the requested substorage. The latest commited version
 233                         of child storage will be used. So in case the child
 234                         storage was not commited after it was changed, the
 235                         changes will not appear in the new created storage.
 236                         </p>
 237
 238                         <p>
 239                         This method allows to retrieve copy of a child storage
 240                         even in case it is already opened for writing.
 241                         </p>
 242                     </dd>
 243
 244                     <dt><method>XStorage::removeStorageElement</method></dt>
 245                     <dd>
 246                         If the element is opened the removing will fail.
 247                     </dd>
 248                 </dl>
 249             </dd>
 250             <dt>property URL</dt>
 251             <dd>
 252                 If the storage is created based on url this property allows
 253                 to retrieve it.
 254             </dd>
 255         </dl>
 256
 257      */
 258     service BaseStorage;
 259
 260     // -----------------------------------------------------------------------
 261     /** allows to commit or revert changes that were done for the storage.
 262
 263         <p>
 264         If a storage is commited all changes made to it will be integrated to
 265         it's parent storage. This is recursive process, so the last commited
 266         storage should be the root one. For the package based storages commit
 267         of a root storage also means flashing to the related medium. If
 268         a storage is not commited, no changes for it or it's child elements
 269         will be stored.
 270         </p>
 271      */
 272     interface ::com::sun::star::embed::XTransactedObject;
 273
 274     // -----------------------------------------------------------------------
 275     /** allows to track storage's transaction state.
 276      */
 277     interface ::com::sun::star::embed::XTransactionBroadcaster;
 278
 279     // -----------------------------------------------------------------------
 280     /** allows to set password to a root storage.
 281
 282         <p>
 283         This interface can be supported by a storage to allow to set
 284         a common storage password. This password is used as default password
 285         to decrypt all encrypted streams and to encrypt streams that are
 286         marked to use common storage password on storing.
 287         Specifying of the password for a storage allows to use it for the
 288         whole subtree. Of course substorage can allow to overwrite the common
 289         storage password for own subtree.
 290         </p>
 291      */
 292     [optional]
 293     interface ::com::sun::star::embed::XEncryptionProtectedSource;
 294
 295     // -----------------------------------------------------------------------
 296     /** allows to get and set the media type of the storage.
 297      */
 298     [property] string MediaType;
 299
 300     // -----------------------------------------------------------------------
 301     /** allows to get and set the version of the format related to the
 302         MediaType.
 303      */
 304     [property,optional] string Version;
 305
 306     // -----------------------------------------------------------------------
 307     /** allows to detect whether mediatype is detected by using fallback
 308         approach.
 309
 310         <p>
 311         Can be set to true if the mediatype can not be detected in standard
 312         way, but there is a fallback solution allows to do it.
 313         </p>
 314
 315         <p>
 316         Usually means that the document validity is questionable, although
 317         the package itself is not corrupted. The decision about document
 318         validity in this case is in application hands. It is up to user of
 319         the storage to deside whether he accepts the fallback approach for
 320         an implementation of this service, outputs a warning or an error.
 321         </p>
 322      */
 323     [property, readonly] boolean MediaTypeFallbackIsUsed;
 324
 325     // -----------------------------------------------------------------------
 326     /** allows to detect whether the storage is a root one.
 327      */
 328     [property, readonly] boolean IsRoot;
 329
 330     // -----------------------------------------------------------------------
 331     /** allows to detect whether storage is open in "repair package" mode or
 332         not.
 333      */
 334     [property, optional, readonly] boolean RepairPackage;
 335
 336     // -----------------------------------------------------------------------
 337     /** allows to detect if the storage contains encrypted entries.
 338
 339         <p>
 340         In case it is set to <TRUE/> the storage itself and/or a tree of
 341         substorages contain encrypted streams. Usually in case this property
 342         is supported the implementation supports
 343         <type>XEncryptionProtectedSource</type> interface.
 344         </p>
 345      */
 346     [property, optional, readonly] boolean HasEncryptedEntries;
 347
 348     // -----------------------------------------------------------------------
 349     /** allows to detect if the storage contains nonencrypted entries.
 350
 351         <p>
 352         In case it is set to <TRUE/> the storage itself and/or a tree of
 353         substorages contains nonencrypted streams. Usually in case this
 354         property is supported the implementation supports
 355         <type>XEncryptionProtectedSource</type> interface.
 356         </p>
 357      */
 358     [property, optional, readonly] boolean HasNonEncryptedEntries;
 359
 360 };
 361
 362 //============================================================================
 363
 364 }; }; }; };
 365
 366 #endif
 367