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 */ 78published 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#endif 366 367