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