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_XEmbedPersist_idl__
24#define __com_sun_star_embed_XEmbedPersist_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_embed_XStorage_idl__
31#include <com/sun/star/embed/XStorage.idl>
32#endif
33
34#ifndef __com_sun_star_embed_XCommonEmbedPersist_idl__
35#include <com/sun/star/embed/XCommonEmbedPersist.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_embed_WrongStateException_idl__
43#include <com/sun/star/embed/WrongStateException.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_beans_PropertyValue_idl__
51#include <com/sun/star/beans/PropertyValue.idl>
52#endif
53
54//============================================================================
55
56 module com {  module sun {  module star {  module embed {
57
58//============================================================================
59/** specifies an implementation for embedded object persistence.
60	<p>
61	The idea is that any usable embedded object should be initialized
62	with an entry in the parent storage that will be used as persistent
63	representation.
64	</p>
65 */
66published interface XEmbedPersist: XCommonEmbedPersist
67{
68	//------------------------------------------------------------------------
69    /** provides object with a parent storage and a name for object's entry.
70
71		<p>
72		An entry with the specified name should be created/opened inside
73		provided storage. It can be a storage or a stream. For example,
74		OOo API will refer to ole storages only by streams, but the object
75		implementation will use storage based on this stream.
76		</p>
77
78		<p>
79		Factory does this call to initialize the embedded object.
80		The linked object can be initialized by factory in different way
81		( internally ).
82		</p>
83
84		<p>
85		It is also possible to switch object persistent representation through
86		this call. Actually this is the way, this call can be used by user
87		( since initialization is done by factory ).
88		</p>
89
90		@param xStorage
91			a parent storage the entry should be created in
92
93		@param sEntName
94			a name for the entry
95
96		@param nEntryConnectionMode
97			a mode in which the object should be initialized from entry
98			can take values from EntryInitModes constant set
99
100        @param aMediaArgs
101            optional parameters for the embedded document persistence
102			initialization, see also
103			<type scope="com::sun::star::document">MediaDescriptor</type>
104
105        @param aObjectArgs
106            optional parameters for the object persistence initialization,
107            see also
108			<type scope="com::sun::star::embed">EmbeddedObjectDescriptor</type>
109
110		@throws ::com::sun::star::lang::IllegalArgumentException
111			one of arguments is illegal
112
113        @throws com::sun::star::embed::WrongStateException
114			the object is in wrong state
115
116        @throws com::sun::star::io::IOException
117			in case of io problems during opening\creation
118
119        @throws com::sun::star::uno::Exception
120			in case of other problems
121	 */
122	void setPersistentEntry(
123			[in] ::com::sun::star::embed::XStorage xStorage,
124			[in] string sEntName,
125			[in] long nEntryConnectionMode,
126			[in] sequence< ::com::sun::star::beans::PropertyValue > aMediaArgs,
127			[in] sequence< ::com::sun::star::beans::PropertyValue > aObjectArgs )
128		raises( ::com::sun::star::lang::IllegalArgumentException,
129				::com::sun::star::embed::WrongStateException,
130				::com::sun::star::io::IOException,
131				::com::sun::star::uno::Exception );
132
133	//------------------------------------------------------------------------
134    /** lets the object store itself to an entry in destination storage,
135		the own persistence entry is not changed.
136
137		@param xStorage
138			a parent storage the entry should be created inside
139
140		@param sEntName
141			a name for the entry
142
143        @param aMediaArgs
144            optional parameters for document saving, see also
145			<type scope="com::sun::star::document">MediaDescriptor</type>
146
147        @param aObjectArgs
148            optional parameters for the object saving, see also
149			<type scope="com::sun::star::embed">EmbeddedObjectDescriptor</type>
150
151		@throws ::com::sun::star::lang::IllegalArgumentException
152			one of arguments is illegal
153
154        @throws com::sun::star::embed::WrongStateException
155			the object is in wrong state
156
157        @throws com::sun::star::io::IOException
158			in case of io problems during storing
159
160        @throws com::sun::star::uno::Exception
161			in case of other problems
162	 */
163	void storeToEntry(
164			[in] ::com::sun::star::embed::XStorage xStorage,
165			[in] string sEntName,
166			[in] sequence< ::com::sun::star::beans::PropertyValue > aMediaArgs,
167			[in] sequence< ::com::sun::star::beans::PropertyValue > aObjectArgs )
168		raises( ::com::sun::star::lang::IllegalArgumentException,
169				::com::sun::star::embed::WrongStateException,
170				::com::sun::star::io::IOException,
171				::com::sun::star::uno::Exception );
172
173	//------------------------------------------------------------------------
174    /** lets the object store itself to an entry in destination storage and
175		prepare to use the new entry for own persistence.
176
177		<p>
178		The object should be stored to the new entry, after that the entry
179		should be remembered by the object. After the storing process is
180		finished the <method>XEmbedPersist::saveCompleted</method> method
181		can be used to specify whether the object should use the new entry or
182		the old one. The object persistence can not be used until
183		<method>XEmbedPersist::saveCompleted</method> is called.
184		So this state can be treated as "HandsOff" state.
185		<p>
186
187		@param xStorage
188			a parent storage the entry should be created in
189
190		@param sEntName
191			a name for the entry
192
193        @param aMediaArgs
194            optional parameters for document saving, see also
195			<type scope="com::sun::star::document">MediaDescriptor</type>
196
197        @param aObjectArgs
198            optional parameters for the object saving, see also
199			<type scope="com::sun::star::embed">EmbeddedObjectDescriptor</type>
200
201		@throws ::com::sun::star::lang::IllegalArgumentException
202			one of arguments is illegal
203
204        @throws com::sun::star::embed::WrongStateException
205			the object is in wrong state
206
207        @throws com::sun::star::io::IOException
208			in case of io problems during storing
209
210        @throws com::sun::star::uno::Exception
211			in case of other problems
212	 */
213	void storeAsEntry(
214			[in] ::com::sun::star::embed::XStorage xStorage,
215			[in] string sEntName,
216			[in] sequence< ::com::sun::star::beans::PropertyValue > aMediaArgs,
217			[in] sequence< ::com::sun::star::beans::PropertyValue > aObjectArgs )
218		raises( ::com::sun::star::lang::IllegalArgumentException,
219				::com::sun::star::embed::WrongStateException,
220				::com::sun::star::io::IOException,
221				::com::sun::star::uno::Exception );
222
223
224	//------------------------------------------------------------------------
225    /** specifies whether the object should use an old storage or a new one
226		after "save as" operation.
227
228		@param bUseNew
229			<TRUE/> the new storage should be used
230			<FALSE/> the old one
231
232        @throws com::sun::star::embed::WrongStateException
233			the object is in wrong state
234
235        @throws com::sun::star::uno::Exception
236			in case of other problems
237	 */
238
239	void saveCompleted( [in] boolean bUseNew )
240		raises( ::com::sun::star::embed::WrongStateException,
241				::com::sun::star::uno::Exception );
242
243	//------------------------------------------------------------------------
244    /** allows to detect if the object has entry.
245
246        @returns
247            <TRUE/> if the object has own entry set
248            <FALSE/> otherwise
249	 */
250	boolean hasEntry()
251		raises( ::com::sun::star::embed::WrongStateException );
252
253	//------------------------------------------------------------------------
254    /** allows to retrieve the current object entry name.
255
256        @returns
257			the object entry name if any
258
259        @throws com::sun::star::embed::WrongStateException
260			the object is in wrong state ( has no entry )
261	 */
262	string getEntryName()
263		raises( ::com::sun::star::embed::WrongStateException );
264};
265
266//============================================================================
267
268}; }; }; };
269
270#endif
271
272