1*b1cdbd2cSJim Jagielski/************************************************************** 2*b1cdbd2cSJim Jagielski * 3*b1cdbd2cSJim Jagielski * Licensed to the Apache Software Foundation (ASF) under one 4*b1cdbd2cSJim Jagielski * or more contributor license agreements. See the NOTICE file 5*b1cdbd2cSJim Jagielski * distributed with this work for additional information 6*b1cdbd2cSJim Jagielski * regarding copyright ownership. The ASF licenses this file 7*b1cdbd2cSJim Jagielski * to you under the Apache License, Version 2.0 (the 8*b1cdbd2cSJim Jagielski * "License"); you may not use this file except in compliance 9*b1cdbd2cSJim Jagielski * with the License. You may obtain a copy of the License at 10*b1cdbd2cSJim Jagielski * 11*b1cdbd2cSJim Jagielski * http://www.apache.org/licenses/LICENSE-2.0 12*b1cdbd2cSJim Jagielski * 13*b1cdbd2cSJim Jagielski * Unless required by applicable law or agreed to in writing, 14*b1cdbd2cSJim Jagielski * software distributed under the License is distributed on an 15*b1cdbd2cSJim Jagielski * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16*b1cdbd2cSJim Jagielski * KIND, either express or implied. See the License for the 17*b1cdbd2cSJim Jagielski * specific language governing permissions and limitations 18*b1cdbd2cSJim Jagielski * under the License. 19*b1cdbd2cSJim Jagielski * 20*b1cdbd2cSJim Jagielski *************************************************************/ 21*b1cdbd2cSJim Jagielski 22*b1cdbd2cSJim Jagielski 23*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_embed_XEmbedPersist_idl__ 24*b1cdbd2cSJim Jagielski#define __com_sun_star_embed_XEmbedPersist_idl__ 25*b1cdbd2cSJim Jagielski 26*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_uno_XInterface_idl__ 27*b1cdbd2cSJim Jagielski#include <com/sun/star/uno/XInterface.idl> 28*b1cdbd2cSJim Jagielski#endif 29*b1cdbd2cSJim Jagielski 30*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_embed_XStorage_idl__ 31*b1cdbd2cSJim Jagielski#include <com/sun/star/embed/XStorage.idl> 32*b1cdbd2cSJim Jagielski#endif 33*b1cdbd2cSJim Jagielski 34*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_embed_XCommonEmbedPersist_idl__ 35*b1cdbd2cSJim Jagielski#include <com/sun/star/embed/XCommonEmbedPersist.idl> 36*b1cdbd2cSJim Jagielski#endif 37*b1cdbd2cSJim Jagielski 38*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_io_IOException_idl__ 39*b1cdbd2cSJim Jagielski#include <com/sun/star/io/IOException.idl> 40*b1cdbd2cSJim Jagielski#endif 41*b1cdbd2cSJim Jagielski 42*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_embed_WrongStateException_idl__ 43*b1cdbd2cSJim Jagielski#include <com/sun/star/embed/WrongStateException.idl> 44*b1cdbd2cSJim Jagielski#endif 45*b1cdbd2cSJim Jagielski 46*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ 47*b1cdbd2cSJim Jagielski#include <com/sun/star/lang/IllegalArgumentException.idl> 48*b1cdbd2cSJim Jagielski#endif 49*b1cdbd2cSJim Jagielski 50*b1cdbd2cSJim Jagielski#ifndef __com_sun_star_beans_PropertyValue_idl__ 51*b1cdbd2cSJim Jagielski#include <com/sun/star/beans/PropertyValue.idl> 52*b1cdbd2cSJim Jagielski#endif 53*b1cdbd2cSJim Jagielski 54*b1cdbd2cSJim Jagielski//============================================================================ 55*b1cdbd2cSJim Jagielski 56*b1cdbd2cSJim Jagielski module com { module sun { module star { module embed { 57*b1cdbd2cSJim Jagielski 58*b1cdbd2cSJim Jagielski//============================================================================ 59*b1cdbd2cSJim Jagielski/** specifies an implementation for embedded object persistence. 60*b1cdbd2cSJim Jagielski <p> 61*b1cdbd2cSJim Jagielski The idea is that any usable embedded object should be initialized 62*b1cdbd2cSJim Jagielski with an entry in the parent storage that will be used as persistent 63*b1cdbd2cSJim Jagielski representation. 64*b1cdbd2cSJim Jagielski </p> 65*b1cdbd2cSJim Jagielski */ 66*b1cdbd2cSJim Jagielskipublished interface XEmbedPersist: XCommonEmbedPersist 67*b1cdbd2cSJim Jagielski{ 68*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------ 69*b1cdbd2cSJim Jagielski /** provides object with a parent storage and a name for object's entry. 70*b1cdbd2cSJim Jagielski 71*b1cdbd2cSJim Jagielski <p> 72*b1cdbd2cSJim Jagielski An entry with the specified name should be created/opened inside 73*b1cdbd2cSJim Jagielski provided storage. It can be a storage or a stream. For example, 74*b1cdbd2cSJim Jagielski OOo API will refer to ole storages only by streams, but the object 75*b1cdbd2cSJim Jagielski implementation will use storage based on this stream. 76*b1cdbd2cSJim Jagielski </p> 77*b1cdbd2cSJim Jagielski 78*b1cdbd2cSJim Jagielski <p> 79*b1cdbd2cSJim Jagielski Factory does this call to initialize the embedded object. 80*b1cdbd2cSJim Jagielski The linked object can be initialized by factory in different way 81*b1cdbd2cSJim Jagielski ( internally ). 82*b1cdbd2cSJim Jagielski </p> 83*b1cdbd2cSJim Jagielski 84*b1cdbd2cSJim Jagielski <p> 85*b1cdbd2cSJim Jagielski It is also possible to switch object persistent representation through 86*b1cdbd2cSJim Jagielski this call. Actually this is the way, this call can be used by user 87*b1cdbd2cSJim Jagielski ( since initialization is done by factory ). 88*b1cdbd2cSJim Jagielski </p> 89*b1cdbd2cSJim Jagielski 90*b1cdbd2cSJim Jagielski @param xStorage 91*b1cdbd2cSJim Jagielski a parent storage the entry should be created in 92*b1cdbd2cSJim Jagielski 93*b1cdbd2cSJim Jagielski @param sEntName 94*b1cdbd2cSJim Jagielski a name for the entry 95*b1cdbd2cSJim Jagielski 96*b1cdbd2cSJim Jagielski @param nEntryConnectionMode 97*b1cdbd2cSJim Jagielski a mode in which the object should be initialized from entry 98*b1cdbd2cSJim Jagielski can take values from EntryInitModes constant set 99*b1cdbd2cSJim Jagielski 100*b1cdbd2cSJim Jagielski @param aMediaArgs 101*b1cdbd2cSJim Jagielski optional parameters for the embedded document persistence 102*b1cdbd2cSJim Jagielski initialization, see also 103*b1cdbd2cSJim Jagielski <type scope="com::sun::star::document">MediaDescriptor</type> 104*b1cdbd2cSJim Jagielski 105*b1cdbd2cSJim Jagielski @param aObjectArgs 106*b1cdbd2cSJim Jagielski optional parameters for the object persistence initialization, 107*b1cdbd2cSJim Jagielski see also 108*b1cdbd2cSJim Jagielski <type scope="com::sun::star::embed">EmbeddedObjectDescriptor</type> 109*b1cdbd2cSJim Jagielski 110*b1cdbd2cSJim Jagielski @thrown ::com::sun::star::lang::IllegalArgumentException 111*b1cdbd2cSJim Jagielski one of arguments is illegal 112*b1cdbd2cSJim Jagielski 113*b1cdbd2cSJim Jagielski @throws com::sun::star::embed::WrongStateException 114*b1cdbd2cSJim Jagielski the object is in wrong state 115*b1cdbd2cSJim Jagielski 116*b1cdbd2cSJim Jagielski @throws com::sun::star::io::IOException 117*b1cdbd2cSJim Jagielski in case of io problems during opening\creation 118*b1cdbd2cSJim Jagielski 119*b1cdbd2cSJim Jagielski @throws com::sun::star::uno::Exception 120*b1cdbd2cSJim Jagielski in case of other problems 121*b1cdbd2cSJim Jagielski */ 122*b1cdbd2cSJim Jagielski void setPersistentEntry( 123*b1cdbd2cSJim Jagielski [in] ::com::sun::star::embed::XStorage xStorage, 124*b1cdbd2cSJim Jagielski [in] string sEntName, 125*b1cdbd2cSJim Jagielski [in] long nEntryConnectionMode, 126*b1cdbd2cSJim Jagielski [in] sequence< ::com::sun::star::beans::PropertyValue > aMediaArgs, 127*b1cdbd2cSJim Jagielski [in] sequence< ::com::sun::star::beans::PropertyValue > aObjectArgs ) 128*b1cdbd2cSJim Jagielski raises( ::com::sun::star::lang::IllegalArgumentException, 129*b1cdbd2cSJim Jagielski ::com::sun::star::embed::WrongStateException, 130*b1cdbd2cSJim Jagielski ::com::sun::star::io::IOException, 131*b1cdbd2cSJim Jagielski ::com::sun::star::uno::Exception ); 132*b1cdbd2cSJim Jagielski 133*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------ 134*b1cdbd2cSJim Jagielski /** lets the object store itself to an entry in destination storage, 135*b1cdbd2cSJim Jagielski the own persistence entry is not changed. 136*b1cdbd2cSJim Jagielski 137*b1cdbd2cSJim Jagielski @param xStorage 138*b1cdbd2cSJim Jagielski a parent storage the entry should be created inside 139*b1cdbd2cSJim Jagielski 140*b1cdbd2cSJim Jagielski @param sEntName 141*b1cdbd2cSJim Jagielski a name for the entry 142*b1cdbd2cSJim Jagielski 143*b1cdbd2cSJim Jagielski @param aMediaArgs 144*b1cdbd2cSJim Jagielski optional parameters for document saving, see also 145*b1cdbd2cSJim Jagielski <type scope="com::sun::star::document">MediaDescriptor</type> 146*b1cdbd2cSJim Jagielski 147*b1cdbd2cSJim Jagielski @param aObjectArgs 148*b1cdbd2cSJim Jagielski optional parameters for the object saving, see also 149*b1cdbd2cSJim Jagielski <type scope="com::sun::star::embed">EmbeddedObjectDescriptor</type> 150*b1cdbd2cSJim Jagielski 151*b1cdbd2cSJim Jagielski @thrown ::com::sun::star::lang::IllegalArgumentException 152*b1cdbd2cSJim Jagielski one of arguments is illegal 153*b1cdbd2cSJim Jagielski 154*b1cdbd2cSJim Jagielski @throws com::sun::star::embed::WrongStateException 155*b1cdbd2cSJim Jagielski the object is in wrong state 156*b1cdbd2cSJim Jagielski 157*b1cdbd2cSJim Jagielski @throws com::sun::star::io::IOException 158*b1cdbd2cSJim Jagielski in case of io problems during storing 159*b1cdbd2cSJim Jagielski 160*b1cdbd2cSJim Jagielski @throws com::sun::star::uno::Exception 161*b1cdbd2cSJim Jagielski in case of other problems 162*b1cdbd2cSJim Jagielski */ 163*b1cdbd2cSJim Jagielski void storeToEntry( 164*b1cdbd2cSJim Jagielski [in] ::com::sun::star::embed::XStorage xStorage, 165*b1cdbd2cSJim Jagielski [in] string sEntName, 166*b1cdbd2cSJim Jagielski [in] sequence< ::com::sun::star::beans::PropertyValue > aMediaArgs, 167*b1cdbd2cSJim Jagielski [in] sequence< ::com::sun::star::beans::PropertyValue > aObjectArgs ) 168*b1cdbd2cSJim Jagielski raises( ::com::sun::star::lang::IllegalArgumentException, 169*b1cdbd2cSJim Jagielski ::com::sun::star::embed::WrongStateException, 170*b1cdbd2cSJim Jagielski ::com::sun::star::io::IOException, 171*b1cdbd2cSJim Jagielski ::com::sun::star::uno::Exception ); 172*b1cdbd2cSJim Jagielski 173*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------ 174*b1cdbd2cSJim Jagielski /** lets the object store itself to an entry in destination storage and 175*b1cdbd2cSJim Jagielski prepare to use the new entry for own persistence. 176*b1cdbd2cSJim Jagielski 177*b1cdbd2cSJim Jagielski <p> 178*b1cdbd2cSJim Jagielski The object should be stored to the new entry, after that the entry 179*b1cdbd2cSJim Jagielski should be remembered by the object. After the storing process is 180*b1cdbd2cSJim Jagielski finished the <method>XEmbedPersist::saveCompleted</method> method 181*b1cdbd2cSJim Jagielski can be used to specify whether the object should use the new entry or 182*b1cdbd2cSJim Jagielski the old one. The object persistence can not be used until 183*b1cdbd2cSJim Jagielski <method>XEmbedPersist::saveCompleted</method> is called. 184*b1cdbd2cSJim Jagielski So this state can be treated as "HandsOff" state. 185*b1cdbd2cSJim Jagielski <p> 186*b1cdbd2cSJim Jagielski 187*b1cdbd2cSJim Jagielski @param xStorage 188*b1cdbd2cSJim Jagielski a parent storage the entry should be created in 189*b1cdbd2cSJim Jagielski 190*b1cdbd2cSJim Jagielski @param sEntName 191*b1cdbd2cSJim Jagielski a name for the entry 192*b1cdbd2cSJim Jagielski 193*b1cdbd2cSJim Jagielski @param aMediaArgs 194*b1cdbd2cSJim Jagielski optional parameters for document saving, see also 195*b1cdbd2cSJim Jagielski <type scope="com::sun::star::document">MediaDescriptor</type> 196*b1cdbd2cSJim Jagielski 197*b1cdbd2cSJim Jagielski @param aObjectArgs 198*b1cdbd2cSJim Jagielski optional parameters for the object saving, see also 199*b1cdbd2cSJim Jagielski <type scope="com::sun::star::embed">EmbeddedObjectDescriptor</type> 200*b1cdbd2cSJim Jagielski 201*b1cdbd2cSJim Jagielski @thrown ::com::sun::star::lang::IllegalArgumentException 202*b1cdbd2cSJim Jagielski one of arguments is illegal 203*b1cdbd2cSJim Jagielski 204*b1cdbd2cSJim Jagielski @throws com::sun::star::embed::WrongStateException 205*b1cdbd2cSJim Jagielski the object is in wrong state 206*b1cdbd2cSJim Jagielski 207*b1cdbd2cSJim Jagielski @throws com::sun::star::io::IOException 208*b1cdbd2cSJim Jagielski in case of io problems during storing 209*b1cdbd2cSJim Jagielski 210*b1cdbd2cSJim Jagielski @throws com::sun::star::uno::Exception 211*b1cdbd2cSJim Jagielski in case of other problems 212*b1cdbd2cSJim Jagielski */ 213*b1cdbd2cSJim Jagielski void storeAsEntry( 214*b1cdbd2cSJim Jagielski [in] ::com::sun::star::embed::XStorage xStorage, 215*b1cdbd2cSJim Jagielski [in] string sEntName, 216*b1cdbd2cSJim Jagielski [in] sequence< ::com::sun::star::beans::PropertyValue > aMediaArgs, 217*b1cdbd2cSJim Jagielski [in] sequence< ::com::sun::star::beans::PropertyValue > aObjectArgs ) 218*b1cdbd2cSJim Jagielski raises( ::com::sun::star::lang::IllegalArgumentException, 219*b1cdbd2cSJim Jagielski ::com::sun::star::embed::WrongStateException, 220*b1cdbd2cSJim Jagielski ::com::sun::star::io::IOException, 221*b1cdbd2cSJim Jagielski ::com::sun::star::uno::Exception ); 222*b1cdbd2cSJim Jagielski 223*b1cdbd2cSJim Jagielski 224*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------ 225*b1cdbd2cSJim Jagielski /** specifies whether the object should use an old storage or a new one 226*b1cdbd2cSJim Jagielski after "save as" operation. 227*b1cdbd2cSJim Jagielski 228*b1cdbd2cSJim Jagielski @param bUseNew 229*b1cdbd2cSJim Jagielski <TRUE/> the new storage should be used 230*b1cdbd2cSJim Jagielski <FALSE/> the old one 231*b1cdbd2cSJim Jagielski 232*b1cdbd2cSJim Jagielski @throws com::sun::star::embed::WrongStateException 233*b1cdbd2cSJim Jagielski the object is in wrong state 234*b1cdbd2cSJim Jagielski 235*b1cdbd2cSJim Jagielski @throws com::sun::star::uno::Exception 236*b1cdbd2cSJim Jagielski in case of other problems 237*b1cdbd2cSJim Jagielski */ 238*b1cdbd2cSJim Jagielski 239*b1cdbd2cSJim Jagielski void saveCompleted( [in] boolean bUseNew ) 240*b1cdbd2cSJim Jagielski raises( ::com::sun::star::embed::WrongStateException, 241*b1cdbd2cSJim Jagielski ::com::sun::star::uno::Exception ); 242*b1cdbd2cSJim Jagielski 243*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------ 244*b1cdbd2cSJim Jagielski /** allows to detect if the object has entry. 245*b1cdbd2cSJim Jagielski 246*b1cdbd2cSJim Jagielski @returns 247*b1cdbd2cSJim Jagielski <TRUE/> if the object has own entry set 248*b1cdbd2cSJim Jagielski <FALSE/> otherwise 249*b1cdbd2cSJim Jagielski */ 250*b1cdbd2cSJim Jagielski boolean hasEntry() 251*b1cdbd2cSJim Jagielski raises( ::com::sun::star::embed::WrongStateException ); 252*b1cdbd2cSJim Jagielski 253*b1cdbd2cSJim Jagielski //------------------------------------------------------------------------ 254*b1cdbd2cSJim Jagielski /** allows to retrieve the current object entry name. 255*b1cdbd2cSJim Jagielski 256*b1cdbd2cSJim Jagielski @returns 257*b1cdbd2cSJim Jagielski the object entry name if any 258*b1cdbd2cSJim Jagielski 259*b1cdbd2cSJim Jagielski @throws com::sun::star::embed::WrongStateException 260*b1cdbd2cSJim Jagielski the object is in wrong state ( has no entry ) 261*b1cdbd2cSJim Jagielski */ 262*b1cdbd2cSJim Jagielski string getEntryName() 263*b1cdbd2cSJim Jagielski raises( ::com::sun::star::embed::WrongStateException ); 264*b1cdbd2cSJim Jagielski}; 265*b1cdbd2cSJim Jagielski 266*b1cdbd2cSJim Jagielski//============================================================================ 267*b1cdbd2cSJim Jagielski 268*b1cdbd2cSJim Jagielski}; }; }; }; 269*b1cdbd2cSJim Jagielski 270*b1cdbd2cSJim Jagielski#endif 271*b1cdbd2cSJim Jagielski 272