xref: /aoo41x/main/offapi/com/sun/star/frame/XStorable.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_frame_XStorable_idl__
24#define __com_sun_star_frame_XStorable_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_IOException_idl__
31#include <com/sun/star/io/IOException.idl>
32#endif
33
34#ifndef __com_sun_star_beans_PropertyValue_idl__
35#include <com/sun/star/beans/PropertyValue.idl>
36#endif
37
38
39//=============================================================================
40
41 module com {  module sun {  module star {  module frame {
42
43//=============================================================================
44/** offers a simple way to store a component to an URL.
45
46    <p>
47    It is usually only useful for two cases:
48	</p>
49	<ol>
50        <li>
51            Large components which are wrapped up in UNO interfaces
52            and for which distinct filters are not available separately as
53            components.
54        </li>
55        <li>
56            Very small components for which only one or very few hard
57            coded file format filters make sense or even exist.
58        </li>
59	</ol>
60 */
61published interface XStorable: com::sun::star::uno::XInterface
62{
63	//-------------------------------------------------------------------------
64    /** The object may know the location because it was loaded from there,
65        or because it is stored there.
66
67        @returns
68            <TRUE/> if the object knows a location where it is persistent
69            <FALSE/> otherwise
70	 */
71	boolean hasLocation();
72
73	//-------------------------------------------------------------------------
74    /** After <member>XStorable::storeAsURL()</member> it returns the
75        URL the object was stored to.
76
77        @returns
78            the URL of the resource which is represented by this object.
79	 */
80	string getLocation();
81
82	//-------------------------------------------------------------------------
83    /** It is not possible to call <member>XStorable::store()</member> successfully
84        when the data store is read-only.
85
86        @returns
87            <TRUE/> if the data store is readonly or opened readonly
88            <FALSE/> otherwise
89	 */
90	boolean isReadonly();
91
92	//-------------------------------------------------------------------------
93	/** stores the data to the URL from which it was loaded.
94
95		<p>Only objects which know their locations can be stored.</p>
96
97        @throws com::sun::star::io::IOException
98            if an IO error occured during save operation
99            (may the location is unknown)
100
101        @see XStorable::storeAsURL
102        @see XStorable::storeToURL
103	 */
104	void store()
105			raises( com::sun::star::io::IOException );
106
107	//-------------------------------------------------------------------------
108	/** stores the object's persistent data to a URL and
109        makes this URL the new location of the object.
110
111        <p>This is the normal behavior for UI's "save-as" feature.</p>
112
113        <p>The change of the location makes it necessary to store the document in
114        a format that the object can load. For this reason the implementation of
115        <member>XStorable::storeAsURL()</member> will throw an exception if a pure
116        export filter is used, it will accept only combined import/export filters.
117        For such filters the method <member>XStorable::storeToURL()</member>
118        must be used that does not change the location of the object.</p>
119
120        @param sURL
121            specifies the new location of this component
122
123        @param lArguments
124            optional parameters for saving
125            (see <type scope="com::sun::star::document">MediaDescriptor</type> for further details)
126
127        @throws com::sun::star::io::IOException
128            if an IO error occured during save operation
129            (may the location is unknown)
130
131        @see XStorable::store
132        @see XStorable::storeToURL
133        @see com::sun::star::document::MediaDescriptor
134	 */
135    void storeAsURL(
136        [in] string sURL,
137        [in] sequence<com::sun::star::beans::PropertyValue> lArguments )
138        raises( com::sun::star::io::IOException );
139
140	//-------------------------------------------------------------------------
141	/** stores the object's persistent data to a URL and
142		continues to be a representation of the old URL.
143
144        <p>This is the normal behavior for UI's export feature.</p>
145
146        <p>This method accepts all kinds of export filters, not only combined
147        import/export filters because it implements an exporting capability, not a
148        persistence capability.</p>
149
150        @throws com::sun::star::io::IOException
151            if an IO error occured during save operation
152            (may the location is unknown)
153
154        @param lArguments
155            optional parameters for saving
156            (see <type scope="com::sun::star::document">MediaDescriptor</type> for further details)
157
158        @see XStorable::store
159        @see XStorable::storeAsURL
160        @see com::sun::star::document::MediaDescriptor
161	 */
162    void storeToURL(
163        [in] string sURL,
164        [in] sequence<com::sun::star::beans::PropertyValue> lArguments )
165        raises( com::sun::star::io::IOException );
166};
167
168//=============================================================================
169
170}; }; }; };
171
172#endif
173