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