offapi/com/sun/star/embed/XEmbedPersist.idl

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