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