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

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