offapi/com/sun/star/frame/XStorable.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: XStorable.idl,v $
  10  * $Revision: 1.14 $
  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_frame_XStorable_idl__
  31 #define __com_sun_star_frame_XStorable_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_io_IOException_idl__
  38 #include <com/sun/star/io/IOException.idl>
  39 #endif
  40
  41 #ifndef __com_sun_star_beans_PropertyValue_idl__
  42 #include <com/sun/star/beans/PropertyValue.idl>
  43 #endif
  44
  45
  46 //=============================================================================
  47
  48  module com {  module sun {  module star {  module frame {
  49
  50 //=============================================================================
  51 /** offers a simple way to store a component to an URL.
  52
  53     <p>
  54     It is usually only useful for two cases:
  55     </p>
  56     <ol>
  57         <li>
  58             Large components which are wrapped up in UNO interfaces
  59             and for which distinct filters are not available separately as
  60             components.
  61         </li>
  62         <li>
  63             Very small components for which only one or very few hard
  64             coded file format filters make sense or even exist.
  65         </li>
  66     </ol>
  67  */
  68 published interface XStorable: com::sun::star::uno::XInterface
  69 {
  70     //-------------------------------------------------------------------------
  71     /** The object may know the location because it was loaded from there,
  72         or because it is stored there.
  73
  74         @returns
  75             <TRUE/> if the object knows a location where it is persistent
  76             <FALSE/> otherwise
  77      */
  78     boolean hasLocation();
  79
  80     //-------------------------------------------------------------------------
  81     /** After <member>XStorable::storeAsURL()</member> it returns the
  82         URL the object was stored to.
  83
  84         @returns
  85             the URL of the resource which is represented by this object.
  86      */
  87     string getLocation();
  88
  89     //-------------------------------------------------------------------------
  90     /** It is not possible to call <member>XStorable::store()</member> successfully
  91         when the data store is read-only.
  92
  93         @returns
  94             <TRUE/> if the data store is readonly or opened readonly
  95             <FALSE/> otherwise
  96      */
  97     boolean isReadonly();
  98
  99     //-------------------------------------------------------------------------
 100     /** stores the data to the URL from which it was loaded.
 101
 102         <p>Only objects which know their locations can be stored.</p>
 103
 104         @throws com::sun::star::io::IOException
 105             if an IO error occured during save operation
 106             (may the location is unknown)
 107
 108         @see XStorable::storeAsURL
 109         @see XStorable::storeToURL
 110      */
 111     void store()
 112             raises( com::sun::star::io::IOException );
 113
 114     //-------------------------------------------------------------------------
 115     /** stores the object's persistent data to a URL and
 116         makes this URL the new location of the object.
 117
 118         <p>This is the normal behavior for UI's "save-as" feature.</p>
 119
 120         <p>The change of the location makes it necessary to store the document in
 121         a format that the object can load. For this reason the implementation of
 122         <member>XStorable::storeAsURL()</member> will throw an exception if a pure
 123         export filter is used, it will accept only combined import/export filters.
 124         For such filters the method <member>XStorable::storeToURL()</member>
 125         must be used that does not change the location of the object.</p>
 126
 127         @param sURL
 128             specifies the new location of this component
 129
 130         @param lArguments
 131             optional parameters for saving
 132             (see <type scope="com::sun::star::document">MediaDescriptor</type> for further details)
 133
 134         @throws com::sun::star::io::IOException
 135             if an IO error occured during save operation
 136             (may the location is unknown)
 137
 138         @see XStorable::store
 139         @see XStorable::storeToURL
 140         @see com::sun::star::document::MediaDescriptor
 141      */
 142     void storeAsURL(
 143         [in] string sURL,
 144         [in] sequence<com::sun::star::beans::PropertyValue> lArguments )
 145         raises( com::sun::star::io::IOException );
 146
 147     //-------------------------------------------------------------------------
 148     /** stores the object's persistent data to a URL and
 149         continues to be a representation of the old URL.
 150
 151         <p>This is the normal behavior for UI's export feature.</p>
 152
 153         <p>This method accepts all kinds of export filters, not only combined
 154         import/export filters because it implements an exporting capability, not a
 155         persistence capability.</p>
 156
 157         @throws com::sun::star::io::IOException
 158             if an IO error occured during save operation
 159             (may the location is unknown)
 160
 161         @param lArguments
 162             optional parameters for saving
 163             (see <type scope="com::sun::star::document">MediaDescriptor</type> for further details)
 164
 165         @see XStorable::store
 166         @see XStorable::storeAsURL
 167         @see com::sun::star::document::MediaDescriptor
 168      */
 169     void storeToURL(
 170         [in] string sURL,
 171         [in] sequence<com::sun::star::beans::PropertyValue> lArguments )
 172         raises( com::sun::star::io::IOException );
 173 };
 174
 175 //=============================================================================
 176
 177 }; }; }; };
 178
 179 #endif