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

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