1/*************************************************************************
2* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3*
4* Copyright 2009 by Sun Microsystems, Inc.
5*
6* OpenOffice.org - a multi-platform office productivity suite
7*
8* This file is part of OpenOffice.org.
9*
10* OpenOffice.org is free software: you can redistribute it and/or modify
11* it under the terms of the GNU Lesser General Public License version 3
12* only, as published by the Free Software Foundation.
13*
14* OpenOffice.org is distributed in the hope that it will be useful,
15* but WITHOUT ANY WARRANTY; without even the implied warranty of
16* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17* GNU Lesser General Public License version 3 for more details
18* (a copy is included in the LICENSE file that accompanied this code).
19*
20* You should have received a copy of the GNU Lesser General Public License
21* version 3 along with OpenOffice.org.  If not, see
22* <http://www.openoffice.org/license.html>
23* for a copy of the LGPLv3 License.
24************************************************************************/
25
26#ifndef __offapcom_sun_star_document_XDocumentRecovery_idl__
27#define __offapcom_sun_star_document_XDocumentRecovery_idl__
28
29#include <com/sun/star/beans/PropertyValue.idl>
30#include <com/sun/star/io/IOException.idl>
31#include <com/sun/star/lang/WrappedTargetException.idl>
32
33//=============================================================================
34
35module com { module sun { module star { module document {
36
37//=============================================================================
38
39/** is the interface to be implemented by documents who wish to participate in
40    the document emergency-save / recovery process.
41 */
42interface XDocumentRecovery
43{
44    /** determines whether the document has been modified since the last call to <member>storeToRecoveryFile</member>.
45
46        <p>If <code>storeToRecoveryFile</code> has not been called before, this method returns whether the document
47        has been modified since it has been loaded respectively created.</p>
48
49        <p>When saving a session, either in case of a emergency (when OpenOffice.org crashed), or during a
50        periodic session save as configured by the user, <member>storeToRecoveryFile</member> is called for every
51        document where <code>wasModifiedSinceLastSave</code> returns <TRUE/>.</p>
52
53        <p>It's allowed to implement this method sloppy, by returning <TRUE/> in cases where it is not sure whether
54        the document actually has been modified. So, the most simple implementation could simply delegate this call
55        to <member scope="com::sun::star::util">XModifiable::isModified</member>. (Well, actually that's the
56        second simple implementation, the <em>most</em> simple one would, still egitimately, always return <TRUE/>.)</p>
57
58        <p>However, in such a case, the document might be saved more often than needed. In particular during the
59        periodic session save, this might become a problem when saving is expensive, for a single document
60        or the sum of all open documents.</p>
61    */
62    boolean wasModifiedSinceLastSave();
63
64    /** does an emergency save of the document
65
66        <p>A default implementation of this method could simply delegate this call to
67        <member scope="com::sun::star::frame">XStorable::storeToURL</member>.</p>
68
69        @param TargetLocation
70            specifies the URL of the location to which the document should be emergency-saved.
71
72        @param MediaDescriptor
73            contains additional arguments for the save process, for instance an StatusIndicator.
74
75        @see MediaDescriptor
76    */
77    void    storeToRecoveryFile(
78                [in] string TargetLocation,
79                [in] sequence< ::com::sun::star::beans::PropertyValue > MediaDescriptor
80            )
81            raises  (   ::com::sun::star::io::IOException,
82                        ::com::sun::star::lang::WrappedTargetException
83                    );
84
85    /** recovers the document after a previous emergency or session save.
86
87        <p>The document itself has previously been created, but <em>not</em> loaded
88        (via <member scope="com::sun::star::frame">XLoadable::load</member>) or initialized (via
89        <member scope="com::sun::star::frame">XLoadable::initNew</member>).</p>
90
91        <p>Upon successful return, the document must be fully initialized. In particular, the
92        caller is not responsible for calling <member scope="com::sun::star::frame">XModel::attachResource</member>.
93        Instead, the implementation is responsible to do so, if required.</p>
94
95        <p>A default implementation of this method could simply delegate this call to
96        <member scope="::com::sun::star::frame:">XLodable::load</member>, followed by
97        <member scope="com::sun::star::frame">XModel::attachResource</member>.</p>
98
99        @param SourceLocation
100            specifies the URL of the location to which the document was previously emergency-saved.
101
102        @param SalvagedFile
103            specifies the original URL of the file which had been emergency-saved. If this is empty,
104            then the file should be recovered from its original location.
105
106        @param MediaDescriptor
107            contains additional arguments for the load process, for instance an StatusIndicator.
108
109        @see MediaDescriptor
110    */
111    void    recoverFromFile(
112                [in] string SourceLocation,
113                [in] string SalvagedFile,
114                [in] sequence< ::com::sun::star::beans::PropertyValue > MediaDescriptor
115            )
116            raises  (   ::com::sun::star::io::IOException,
117                        ::com::sun::star::lang::WrappedTargetException
118                    );
119};
120
121//=============================================================================
122
123}; }; }; };
124
125//=============================================================================
126
127#endif
128