summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/document/XDocumentProperties.idl
blob: 5a4b1f5c221c94b187ef2d757c9298977b7aed93 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */
#ifndef __com_sun_star_document_XDocumentProperties_idl__
#define __com_sun_star_document_XDocumentProperties_idl__

#include <com/sun/star/beans/PropertyValue.idl>
#include <com/sun/star/util/DateTime.idl>
#include <com/sun/star/lang/Locale.idl>
#include <com/sun/star/beans/NamedValue.idl>
#include <com/sun/star/embed/XStorage.idl>
#include <com/sun/star/io/IOException.idl>
#include <com/sun/star/io/WrongFormatException.idl>
#include <com/sun/star/beans/XPropertySet.idl>
#include <com/sun/star/beans/XPropertyContainer.idl>



module com {   module sun {   module star {   module document {

/** provides document-specific information such as the author, creation date,
    and user-defined fields.

    <p>
    This interface manages access to document meta-data properties.
    Such properties may be set from the outside via the setter methods
    (e.g. when importing arbitrary document formats that support
    document properties), or imported from an ODF package via the methods
    loadFromStorage() and loadFromMedium().
    The properties may also be stored via the methods
    storeToStorage() and storeToMedium().
    </p>

    @since OOo 3.0

    @see XDocumentPropertiesSupplier
            for getting access to an instance from a loaded document
    @see DocumentProperties     for a service that implements this interface
 */
published interface XDocumentProperties
{
    /** contains the initial author of the document.
     */

    [attribute] string Author;

    /** identifies which application was used to create or last modify the
        document.
        <p>
        The generating application will set this attribute when it creates a
        new document or it saves a document. When a document is loaded that
        itself contains such an attribute it will be preserved until the
        document is saved again.
        </p>
     */

    [attribute] string Generator;

    /** contains the date and time when the document was created.
     */

    [attribute] com::sun::star::util::DateTime CreationDate;

    /** contains the title of the document.
     */

    [attribute] string Title;

    /** contains the subject of the document.
     */

    [attribute] string Subject;

    /** contains a multi-line comment describing the document.
        <p>
        Line delimiters can be UNIX, Macintosh or DOS style.
        </p>
     */

    [attribute] string Description;

    /** contains a list of keywords for the document.
     */

    [attribute] sequence< string > Keywords;

    /** contains the default language of the document.
     */

    [attribute] com::sun::star::lang::Locale Language;

    /** contains the name of the person who most recently stored the document.
     */

    [attribute] string ModifiedBy;

    /** contains the date and time of the last time the document was stored.
        <p>
        If the document has never been stored, contains a default value.
        </p>
     */

    [attribute] com::sun::star::util::DateTime ModificationDate;

    /** contains the name of the person who most recently printed the document.
     */

    [attribute] string PrintedBy;

    /** contains the date and time when the document was last printed.
        <p>
        If the document has never been printed, contains a default value.
        </p>
     */

    [attribute] com::sun::star::util::DateTime PrintDate;

    /** contains the name of the template from which the document was created.
        <p>
        The value is an empty `string` if the document was not
        created from a template or if it was detached from the template.
        </p>
     */

    [attribute] string TemplateName;

    /** contains the URL of the template from which the document was created.
        <p>
        The value is an empty `string` if the document was not
        created from a template or if it was detached from the template.
        </p>
     */

    [attribute] string TemplateURL;

    /** contains the date and time of when the document
        was created or updated from the template.
     */

    [attribute] com::sun::star::util::DateTime TemplateDate;

    /** contains the URL to load automatically at a
        specified time after the document is loaded into a desktop frame.
        <p>
        An empty URL is valid and describes a case where the document shall be
        reloaded from its original location after some time described by the
        attribute #AutoloadSecs.
        An empty `string` together with an
        #AutoloadSecs value of 0
        describes a case where no autoload is specified.
        </p>

        @see AutoloadSecs
     */

    [attribute] string AutoloadURL;

    /** contains the number of seconds after which a specified
        URL is to be loaded after the document is loaded into a desktop
        frame.
        <p>
        A value of 0 is valid and describes a redirection.
        A value of 0 together with an empty `string` as
        #AutoloadURL
        describes a case where no autoload is specified.
        </p>

        @throws com::sun::star::lang::IllegalArgumentException
            if argument is negative

        @see AutoloadURL
     */

    [attribute] long AutoloadSecs {
            set raises ( com::sun::star::lang::IllegalArgumentException );
    };

    /** contains the name of the default frame into which
        links should be loaded if no target is specified.
        <p>
        This applies to the autoload feature too, but to others as well.
        </p>
     */

    [attribute] string DefaultTarget;

    /** contains some statistics about the document.
        <p>
        The contained statistics may be specific to the type of the document.
        </p>
     */

    [attribute]
         sequence< com::sun::star::beans::NamedValue > DocumentStatistics;

    /** describes how often the document was edited and saved.
        <p>
        </p>

        @throws com::sun::star::lang::IllegalArgumentException
            if argument is negative
     */

    [attribute] short EditingCycles {
            set raises ( com::sun::star::lang::IllegalArgumentException );
    };

    /** contains the net time of editing the document (in seconds).
        <p>
        </p>

        @throws com::sun::star::lang::IllegalArgumentException
            if argument is negative
     */

    [attribute] long EditingDuration {
            set raises ( com::sun::star::lang::IllegalArgumentException );
    };

    /** resets all attributes that could identify the user.
        <p>
        Clears the document properties, such that it appears the document
        has just been created.
        This is a convenience method which resets several attributes at once,
        as follows:
        <ul>
        <li>#Author is set to the given parameter.</li>
        <li>#CreationDate is set to the current date and time.
        </li>
        <li>#ModifiedBy is cleared.</li>
        <li>#ModificationDate is cleared.</li>
        <li>#PrintedBy is cleared.</li>
        <li>#PrintDate is cleared.</li>
        <li>#EditingDuration is cleared.</li>
        <li>#EditingCycles is set to 1.</li>
        </ul>

        @param Author
            the new value of the #Author attribute.
        </p>
     */
    void resetUserData( [in] string Author );

    /** provides access to a container for user-defined properties.
        <p>
        The returned object also implements the interface
        com::sun::star::beans::XPropertySet.
        </p>
        @returns    a container that provides access to user-defined properties
     */

    com::sun::star::beans::XPropertyContainer getUserDefinedProperties();

    /** loads document properties from an ODF package.
        <p>
        This method is used for accessing an ODF package that is owned by
        someone else, e.g., a document.
        </p>

        @param Storage
            the com::sun::star::embed::Storage representing the
            ODF package

        @param Medium
            the com::sun::star::document::MediaDescriptor
            representing the source
            <p>
            This is unfortunately necessary in order to properly resolve
            relative URLs in the meta-data.
            </p>

        @throws com::sun::star::lang::IllegalArgumentException
                 if argument is `NULL`
        @throws com::sun::star::io::WrongFormatException
                 if parsing the XML document fails
        @throws com::sun::star::lang::WrappedTargetException
                 if thrown when trying to open a stream in the given storage
        @throws com::sun::star::io::IOException
                 if thrown when trying to open a stream in the given storage
     */

    void loadFromStorage( [in] com::sun::star::embed::XStorage Storage,
                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::io::WrongFormatException,
                com::sun::star::lang::WrappedTargetException,
                com::sun::star::io::IOException );

    /** loads document properties from an ODF package or an OLE container.

        @param URL
            the URL of the source document
            <p>
            The URL could be part of the Medium parameter, but because often
            no other parameters except the URL are needed, providing it
            separately was added for convenience.
            </p>

        @param Medium
            the com::sun::star::document::MediaDescriptor
            representing the source

        @throws com::sun::star::io::WrongFormatException
                 if parsing the XML document fails
        @throws com::sun::star::lang::WrappedTargetException
                 if thrown when trying to open a stream in the given storage
        @throws com::sun::star::io::IOException
                 if thrown when trying to open a stream in the given storage
     */

    void loadFromMedium( [in] string URL,
                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
        raises( com::sun::star::io::WrongFormatException,
                com::sun::star::lang::WrappedTargetException,
                com::sun::star::io::IOException );

    /** stores document properties to an ODF package.
        <p>
        This method is used for accessing an ODF package that is owned by
        someone else, e.g., a document.
        Note that the implementation may choose to store the meta-data
        in either OOo or ODF format, depending on the MediaType property
        of the given Storage argument.
        </p>

        @param Storage
            the com::sun::star::embed::Storage representing the
            ODF package

        @param Medium
            the com::sun::star::document::MediaDescriptor
            representing the source
            <p>
            This is unfortunately necessary in order to properly resolve
            relative URLs in the meta-data.
            </p>

        @throws com::sun::star::lang::IllegalArgumentException
                 if argument is `NULL`
        @throws com::sun::star::lang::WrappedTargetException
                 if thrown when trying to open a stream in the given storage
        @throws com::sun::star::io::IOException
                 if thrown when writing to the storage
     */

    void storeToStorage( [in] com::sun::star::embed::XStorage Storage,
                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
        raises( com::sun::star::lang::IllegalArgumentException,
                com::sun::star::lang::WrappedTargetException,
                com::sun::star::io::IOException );

    /** stores document properties to an ODF package or an OLE container.

        @param URL
            the URL of the target document
            <p>
            The URL could be part of the Medium parameter, but because often
            no other parameters except the URL are needed, providing it
            separately was added for convenience.
            </p>

        @param Medium
            the com::sun::star::document::MediaDescriptor
            representing the target

        @throws com::sun::star::lang::WrappedTargetException
                 if thrown when trying to open a stream in the given storage
        @throws com::sun::star::io::IOException
                 if thrown when writing to the storage
     */

    void storeToMedium( [in] string URL,
                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
        raises( com::sun::star::lang::WrappedTargetException,
                com::sun::star::io::IOException );
};


}; }; }; };

#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */