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