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