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 @thrown ::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 @thrown ::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 @thrown ::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