xref: /aoo41x/main/offapi/com/sun/star/embed/XStorage.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#ifndef __com_sun_star_embed_XStorage_idl__
28#define __com_sun_star_embed_XStorage_idl__
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33
34#ifndef __com_sun_star_io_XStream_idl__
35#include <com/sun/star/io/XStream.idl>
36#endif
37
38#ifndef __com_sun_star_io_XInputStream_idl__
39#include <com/sun/star/io/XInputStream.idl>
40#endif
41
42#ifndef __com_sun_star_io_IOException_idl__
43#include <com/sun/star/io/IOException.idl>
44#endif
45
46#ifndef __com_sun_star_lang_XComponent_idl__
47#include <com/sun/star/lang/XComponent.idl>
48#endif
49
50#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
51#include <com/sun/star/lang/IllegalArgumentException.idl>
52#endif
53
54#ifndef __com_sun_star_embed_StorageWrappedTargetException_idl__
55#include <com/sun/star/embed/StorageWrappedTargetException.idl>
56#endif
57
58#ifndef __com_sun_star_embed_InvalidStorageException_idl__
59#include <com/sun/star/embed/InvalidStorageException.idl>
60#endif
61
62#ifndef __com_sun_star_packages_WrongPasswordException_idl__
63#include <com/sun/star/packages/WrongPasswordException.idl>
64#endif
65
66#ifndef __com_sun_star_container_XNameAccess_idl__
67#include <com/sun/star/container/XNameAccess.idl>
68#endif
69
70#ifndef __com_sun_star_container_NoSuchElementException_idl__
71#include <com/sun/star/container/NoSuchElementException.idl>
72#endif
73
74#ifndef __com_sun_star_container_ElementExistException_idl__
75#include <com/sun/star/container/ElementExistException.idl>
76#endif
77
78#ifndef __com_sun_star_packages_NoEncryptionException_idl__
79#include <com/sun/star/packages/NoEncryptionException.idl>
80#endif
81
82#ifndef __com_sun_star_packages_NoRawFormatException_idl__
83#include <com/sun/star/packages/NoRawFormatException.idl>
84#endif
85
86
87//============================================================================
88
89 module com {  module sun {  module star {  module embed {
90
91//============================================================================
92/** This interface represents main storage functionality.
93 */
94published interface XStorage
95{
96	// INTERFACES
97	//
98	// -----------------------------------------------------------------------
99	/** allows to get list of child elements and to check if an element with a
100		specified name exists in a storage.
101
102		<p>
103		It is also possible to use this interface to get read access to
104		a child element by
105		<method scope="com::sun::star::container">XNameAccess::getByName</method>
106		call. But the recommended way is to use <type>XStorage</type>
107		interface for this purpose.
108		</p>
109	 */
110	interface ::com::sun::star::container::XNameAccess;
111
112	// -----------------------------------------------------------------------
113	/** allows to controll and track lifetime of the storage.
114
115		<p>
116		In case a storage is disposed any call to it's methods should result
117		in <type scope="com::sun::star::lang">DisposedException</type>.
118		</p>
119	 */
120	interface ::com::sun::star::lang::XComponent;
121
122
123	// METHODS
124	//
125	// -----------------------------------------------------------------------
126	/** allows to copy current storage to another one
127
128		<p>
129		The destination storage contents are overwritten.
130		After the successful copying the target storage is automatically
131		commited if it implements transacted access.
132		</p>
133
134		@param xDest
135			a destination storage this storage must be copied to.
136
137		@throws ::com::sun::star::embed::InvalidStorageException
138			this storage is in invalid state for any reason
139
140		@throws ::com::sun::star::lang::IllegalArgumentException
141			an illegal argument is provided
142
143		@throws ::com::sun::star::io::IOException
144			in case of io errors during copying
145
146		@throws ::com::sun::star::embed::StorageWrappedTargetException
147			wraps other exception acquired during copying
148	 */
149	void copyToStorage( [in] XStorage xDest )
150		raises( ::com::sun::star::embed::InvalidStorageException,
151				::com::sun::star::lang::IllegalArgumentException,
152				::com::sun::star::io::IOException,
153				::com::sun::star::embed::StorageWrappedTargetException );
154
155	// -----------------------------------------------------------------------
156	/** allows to get access to a child stream of the storage.
157
158		<p>
159		In case the stream is open in readonly mode the
160		<method scope="com::sun::star::io">XStream::getOutputStream</method>
161		method will return an empty reference.
162		</p>
163
164		@param sStreamName
165			the name of the substream that should be open
166
167		@param nOpenMode
168			a mode the stream should be open in,
169			can be a combination of <type>ElementModes</type> values
170
171		@throws ::com::sun::star::embed::InvalidStorageException
172			this storage is in invalid state for any reason
173
174		@throws ::com::sun::star::lang::IllegalArgumentException
175			one of provided arguments is illegal
176
177		@throws ::com::sun::star::packages::WrongPasswordException
178			the provided password is wrong
179
180		@throws ::com::sun::star::io::IOException
181			in case of io errors during stream opening
182
183		@throws ::com::sun::star::embed::StorageWrappedTargetException
184			wraps other exceptions
185	 */
186    ::com::sun::star::io::XStream  openStreamElement(
187			[in] string sStreamName,
188			[in] long nOpenMode )
189		raises( ::com::sun::star::embed::InvalidStorageException,
190				::com::sun::star::lang::IllegalArgumentException,
191				::com::sun::star::packages::WrongPasswordException,
192				::com::sun::star::io::IOException,
193				::com::sun::star::embed::StorageWrappedTargetException );
194
195	// -----------------------------------------------------------------------
196	/** allows to get access to a child encrypted stream with password.
197
198		<p>
199		If storage does not allow any encryption this method will always throw
200		<type scope="com::sun::star::packages">NoEncryptionException</type>.
201		</p>
202
203		<p>
204		In case the stream is open in readonly mode the
205		<method scope="com::sun::star::io">XStream::getOutputStream</method>
206		method will return an empty reference.
207		</p>
208
209		@param sStreamName
210			the name of the substream that should be open
211
212		@param nOpenMode
213			a mode the stream should be open in,
214			can be a combination of <type>ElementModes</type> values
215
216		@param sPassword
217			this parameter allowes to specify a reading password for the
218			stream, the password must be a correct one, otherwise an
219			exception will be thrown
220
221		@throws ::com::sun::star::embed::InvalidStorageException
222			this storage is in invalid state for any reason
223
224		@throws ::com::sun::star::lang::IllegalArgumentException
225			one of provided arguments is illegal
226
227		@throws ::com::sun::star::packages::NoEncryptionException
228			the stream is not encrypted
229
230		@throws ::com::sun::star::packages::WrongPasswordException
231			the provided password is wrong
232
233		@throws ::com::sun::star::io::IOException
234			in case of io errors during stream opening
235
236		@throws ::com::sun::star::embed::StorageWrappedTargetException
237			wraps other exceptions
238	 */
239    ::com::sun::star::io::XStream  openEncryptedStreamElement(
240			[in] string sStreamName,
241			[in] long nOpenMode,
242			[in] string sPassword )
243		raises( ::com::sun::star::embed::InvalidStorageException,
244				::com::sun::star::lang::IllegalArgumentException,
245				::com::sun::star::packages::NoEncryptionException,
246				::com::sun::star::packages::WrongPasswordException,
247				::com::sun::star::io::IOException,
248				::com::sun::star::embed::StorageWrappedTargetException );
249
250	// -----------------------------------------------------------------------
251	/** allows to get access to a child storage.
252
253		<p>
254		The opened substorage must support specified in 'nOpenMode' access
255		modes. It can support 'read' mode in addition. But any child element
256		can support one of those modes only in case this mode is supported by
257		parent storage.
258		</p>
259
260		@param sStorName
261			the name of the storage that should be open
262
263		@param nOpenMode
264			a mode the storage should be open in
265
266		@throws ::com::sun::star::embed::InvalidStorageException
267			this storage is in invalid state for any reason
268
269		@throws ::com::sun::star::lang::IllegalArgumentException
270			one of provided arguments is illegal
271
272		@throws ::com::sun::star::io::IOException
273			in case of io errors during stream opening
274
275		@throws ::com::sun::star::embed::StorageWrappedTargetException
276			wraps other exceptions
277
278	 */
279    XStorage openStorageElement( [in] string sStorName,
280								 [in] long nOpenMode )
281		raises( ::com::sun::star::embed::InvalidStorageException,
282				::com::sun::star::lang::IllegalArgumentException,
283				::com::sun::star::io::IOException,
284				::com::sun::star::embed::StorageWrappedTargetException );
285
286	// -----------------------------------------------------------------------
287	/** allows to get readonly copy of a child stream of the storage.
288
289		<p>
290		The stream is open in readonly mode so the
291		<method scope="com::sun::star::io">XStream::getOutputStream</method>
292		method will return an empty reference.
293		</p>
294
295		@param sStreamName
296			the name of the substream that should be copied
297
298		@throws ::com::sun::star::embed::InvalidStorageException
299			this storage is in invalid state for any reason
300
301		@throws ::com::sun::star::lang::IllegalArgumentException
302			one of provided arguments is illegal
303
304		@throws ::com::sun::star::packages::WrongPasswordException
305			the provided password is wrong
306
307		@throws ::com::sun::star::io::IOException
308			in case of io errors during stream opening
309
310		@throws ::com::sun::star::embed::StorageWrappedTargetException
311			wraps other exceptions
312	 */
313    ::com::sun::star::io::XStream cloneStreamElement( [in] string sStreamName )
314		raises( ::com::sun::star::embed::InvalidStorageException,
315				::com::sun::star::lang::IllegalArgumentException,
316				::com::sun::star::packages::WrongPasswordException,
317				::com::sun::star::io::IOException,
318				::com::sun::star::embed::StorageWrappedTargetException );
319
320	// -----------------------------------------------------------------------
321	/** allows to get readonly copy of a child encrypted stream with password.
322
323		<p>
324		If storage does not allow any encryption this method will always throw
325		<type scope="com::sun::star::packages">NoEncryptionException</type>.
326		</p>
327
328		<p>
329		The stream is open in readonly mode so the
330		<method scope="com::sun::star::io">XStream::getOutputStream</method>
331		method will return an empty reference.
332		</p>
333
334		<p>
335		This method allows to specify reading password for the child stream
336		explicitly.
337		</p>
338
339		@param sStreamName
340			the name of the substream that should be copied
341
342		@param sPassword
343			this parameter allowes to specify a reading password for the
344			stream, the password must be a correct one, otherwise an
345			exception will be thrown
346
347		@throws ::com::sun::star::embed::InvalidStorageException
348			this storage is in invalid state for any reason
349
350		@throws ::com::sun::star::lang::IllegalArgumentException
351			one of provided arguments is illegal
352
353		@throws ::com::sun::star::packages::NoEncryptionException
354			the stream is not encrypted
355
356		@throws ::com::sun::star::packages::WrongPasswordException
357			the provided password is wrong
358
359		@throws ::com::sun::star::io::IOException
360			in case of io errors during stream opening
361
362		@throws ::com::sun::star::embed::StorageWrappedTargetException
363			wraps other exceptions
364	 */
365    ::com::sun::star::io::XStream cloneEncryptedStreamElement(
366			[in] string sStreamName,
367			[in] string sPassword )
368		raises( ::com::sun::star::embed::InvalidStorageException,
369				::com::sun::star::lang::IllegalArgumentException,
370				::com::sun::star::packages::NoEncryptionException,
371				::com::sun::star::packages::WrongPasswordException,
372				::com::sun::star::io::IOException,
373				::com::sun::star::embed::StorageWrappedTargetException );
374
375	// -----------------------------------------------------------------------
376	/** allows to get copy of this storage at the state of it's last commit.
377
378		<p>
379		This method makes sence only for services implementations that allow
380		transaction in the storage.
381		</p>
382
383		@param xStorage
384			the target storage that will be filled in with copy.
385
386		@throws ::com::sun::star::embed::InvalidStorageException
387			this storage is in invalid state for any reason
388
389		@throws ::com::sun::star::lang::IllegalArgumentException
390			one of provided arguments is illegal
391
392		@throws ::com::sun::star::io::IOException
393			in case of io errors during copying
394
395		@throws ::com::sun::star::embed::StorageWrappedTargetException
396			wraps other exceptions
397
398	 */
399    void copyLastCommitTo( [in] XStorage xTargetStorage )
400		raises( ::com::sun::star::embed::InvalidStorageException,
401				::com::sun::star::lang::IllegalArgumentException,
402				::com::sun::star::io::IOException,
403				::com::sun::star::embed::StorageWrappedTargetException );
404
405	// -----------------------------------------------------------------------
406	/** allows to get copy of a child storage at the state of it's last commit.
407
408		<p>
409		This method makes sence only for services implementations that allow
410		transaction in the storage.
411		</p>
412
413		@param sStorName
414			the name of the storage that should be copied
415
416		@param xStorage
417			the target storage that will be filled in with copy
418
419		@throws ::com::sun::star::embed::InvalidStorageException
420			this storage is in invalid state for any reason
421
422		@throws ::com::sun::star::lang::IllegalArgumentException
423			one of provided arguments is illegal
424
425		@throws ::com::sun::star::io::IOException
426			in case of io errors during copying
427
428		@throws ::com::sun::star::embed::StorageWrappedTargetException
429			wraps other exceptions
430
431	 */
432    void copyStorageElementLastCommitTo(
433			[in] string sStorName,
434			[in] XStorage xTargetStorage )
435		raises( ::com::sun::star::embed::InvalidStorageException,
436				::com::sun::star::lang::IllegalArgumentException,
437				::com::sun::star::io::IOException,
438				::com::sun::star::embed::StorageWrappedTargetException );
439
440	// -----------------------------------------------------------------------
441	/** allows to check if an element is a child stream with specified name.
442
443		<p>
444		In case there is no child element with such name an exception will be
445		thrown.
446		</p>
447
448		@param sElementName
449			the name of the element to check
450
451		@returns
452			<TRUE/> in case the element is a stream
453			<FALSE/> - the element is a storage
454
455		@throws ::com::sun::star::container::NoSuchElementException
456			there is no element with such name
457
458		@throws ::com::sun::star::lang::IllegalArgumentException
459			an illegal argument is provided
460
461		@throws ::com::sun::star::embed::InvalidStorageException
462			this storage is in invalid state for any reason
463
464	 */
465    boolean isStreamElement( [in] string sElementName )
466		raises( ::com::sun::star::container::NoSuchElementException,
467				::com::sun::star::lang::IllegalArgumentException,
468				::com::sun::star::embed::InvalidStorageException );
469
470
471	// -----------------------------------------------------------------------
472	/** allows to check if an element is a child storage with specified name.
473
474		<p>
475		In case there is no child element with such name an exception will be
476		thrown.
477		</p>
478
479		@param sElementName
480			the name of the element to check
481
482		@returns
483			<TRUE/> in case the element is a storage
484			<FALSE/> - the element is a stream
485
486		@throws ::com::sun::star::container::NoSuchElementException
487			there is no element with such name
488
489		@throws ::com::sun::star::lang::IllegalArgumentException
490			an illegal argument is provided
491
492		@throws ::com::sun::star::embed::InvalidStorageException
493			this storage is in invalid state for any reason
494
495	 */
496    boolean isStorageElement( [in] string sElementName )
497		raises( ::com::sun::star::container::NoSuchElementException,
498				::com::sun::star::lang::IllegalArgumentException,
499				::com::sun::star::embed::InvalidStorageException );
500
501	// -----------------------------------------------------------------------
502	/** removes an element from a storage.
503
504		@param sElementName
505			the name of the element to remove
506
507		@throws ::com::sun::star::embed::InvalidStorageException
508			this storage is in invalid state for eny reason
509
510		@throws ::com::sun::star::lang::IllegalArgumentException
511			an illegal argument is provided
512
513		@throws ::com::sun::star::container::NoSuchElementException
514			there is no element with such name
515
516		@throws ::com::sun::star::io::IOException
517			in case of io errors during removing
518
519		@throws ::com::sun::star::embed::StorageWrappedTargetException
520			wraps other exceptions
521
522	 */
523    void removeElement( [in] string sElementName )
524		raises( ::com::sun::star::embed::InvalidStorageException,
525				::com::sun::star::lang::IllegalArgumentException,
526				::com::sun::star::container::NoSuchElementException,
527				::com::sun::star::io::IOException,
528				::com::sun::star::embed::StorageWrappedTargetException );
529
530	// -----------------------------------------------------------------------
531	/** renames an element in a storage.
532
533		@param sElementName
534			the old name of the element to rename
535
536		@param sNewName
537			the new name of the element to rename
538
539		@throws ::com::sun::star::embed::InvalidStorageException
540			this storage is in invalid state for eny reason
541
542		@throws ::com::sun::star::lang::IllegalArgumentException
543			an illegal argument is provided
544
545		@throws ::com::sun::star::container::NoSuchElementException
546			there is no element with old name in this storage
547
548		@throws ::com::sun::star::container::ElementExistException
549			an element with new name already exists in this storage
550
551		@throws ::com::sun::star::io::IOException
552			in case of io errors during renaming
553
554		@throws ::com::sun::star::embed::StorageWrappedTargetException
555			wraps other exceptions
556
557	 */
558    void renameElement( [in] string sElementName, [in] string sNewName )
559		raises( ::com::sun::star::embed::InvalidStorageException,
560				::com::sun::star::lang::IllegalArgumentException,
561				::com::sun::star::container::NoSuchElementException,
562				::com::sun::star::container::ElementExistException,
563				::com::sun::star::io::IOException,
564				::com::sun::star::embed::StorageWrappedTargetException );
565
566	// -----------------------------------------------------------------------
567	/** allows to copy an entry from one storage to another.
568
569		<p>
570		If target element supports transacted mode it must be commited by this
571		method after successful copying.
572		</p>
573
574		@param sElementName
575			the name of the element in this storage
576
577		@param xDest
578			a destination storage
579
580		@param sNewName
581			the name of the result element in destination storage
582
583		@throws ::com::sun::star::embed::InvalidStorageException
584			this storage is in invalid state for eny reason
585
586		@throws ::com::sun::star::container::NoSuchElementException
587			there is no specified source element in this storage
588
589		@throws ::com::sun::star::container::ElementExistException
590			an element with specified destination name already exists in destination storage
591
592		@throws ::com::sun::star::io::IOException
593			in case of io errors during copying
594
595		@throws ::com::sun::star::embed::StorageWrappedTargetException
596			wraps other exceptions
597
598	 */
599    void copyElementTo(
600			[in] string sElementName,
601			[in] XStorage xDest,
602			[in] string sNewName )
603		raises( ::com::sun::star::embed::InvalidStorageException,
604				::com::sun::star::lang::IllegalArgumentException,
605				::com::sun::star::container::NoSuchElementException,
606				::com::sun::star::container::ElementExistException,
607				::com::sun::star::io::IOException,
608				::com::sun::star::embed::StorageWrappedTargetException );
609
610	// -----------------------------------------------------------------------
611	/** allows to move an entry from one storage to another.
612
613		<p>
614		If target element supports transacted mode it must be commited by this
615		method after successful moving.
616		</p>
617
618		@param sElementName
619			the name of the element in this storage
620
621		@param xDest
622			a destination storage
623
624		@param sNewName
625			the name of the result element in destination storage
626
627		@throws ::com::sun::star::embed::InvalidStorageException
628			this storage is in invalid state for eny reason
629
630		@throws ::com::sun::star::container::NoSuchElementException
631			there is no specified source element in this storage
632
633		@throws ::com::sun::star::container::ElementExistException
634			an element with specified destination name already exists in destination storage
635
636		@throws ::com::sun::star::io::IOException
637			in case of io errors during moving
638
639		@throws ::com::sun::star::embed::StorageWrappedTargetException
640			wraps other exceptions
641
642	 */
643    void moveElementTo(
644			[in] string sElementName,
645			[in] XStorage xDest,
646			[in] string sNewName )
647		raises( ::com::sun::star::embed::InvalidStorageException,
648				::com::sun::star::lang::IllegalArgumentException,
649				::com::sun::star::container::NoSuchElementException,
650				::com::sun::star::container::ElementExistException,
651				::com::sun::star::io::IOException,
652				::com::sun::star::embed::StorageWrappedTargetException );
653
654};
655
656//============================================================================
657
658}; }; }; };
659
660#endif
661
662