xref: /aoo41x/main/offapi/com/sun/star/embed/Storage.idl (revision cdf0e10c)
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