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