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