1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_document_XDocumentProperties_idl__
24#define __com_sun_star_document_XDocumentProperties_idl__
25
26#ifndef __com_sun_star_beans_PropertyValue_idl__
27#include <com/sun/star/beans/PropertyValue.idl>
28#endif
29
30#ifndef __com_sun_star_util_DateTime_idl__
31#include <com/sun/star/util/DateTime.idl>
32#endif
33
34#ifndef __com_sun_star_lang_Locale_idl__
35#include <com/sun/star/lang/Locale.idl>
36#endif
37
38#ifndef __com_sun_star_beans_NamedValue_idl__
39#include <com/sun/star/beans/NamedValue.idl>
40#endif
41
42#ifndef __com_sun_star_embed_XStorage_idl__
43#include <com/sun/star/embed/XStorage.idl>
44#endif
45
46#ifndef __com_sun_star_io_IOException_idl__
47#include <com/sun/star/io/IOException.idl>
48#endif
49
50#ifndef __com_sun_star_io_WrongFormatException_idl__
51#include <com/sun/star/io/WrongFormatException.idl>
52#endif
53
54#ifndef __com_sun_star_beans_XPropertySet_idl__
55#include <com/sun/star/beans/XPropertySet.idl>
56#endif
57
58#ifndef __com_sun_star_beans_XPropertyContainer_idl__
59#include <com/sun/star/beans/XPropertyContainer.idl>
60#endif
61
62
63//=============================================================================
64
65module com {   module sun {   module star {   module document {
66
67//=============================================================================
68/** provides document-specific information such as the author, creation date,
69    and user-defined fields.
70
71    <p>
72    This interface manages access to document meta-data properties.
73    Such properties may be set from the outside via the setter methods
74    (e.g. when importing arbitrary document formats that support
75    document properties), or imported from an ODF package via the methods
76    <member>loadFromStorage</member> and <member>loadFromMedium</member>.
77    The properties may also be stored via the methods
78    <member>storeToStorage</member> and <member>storeToMedium</member>.
79    </p>
80
81    @since OOo 3.0
82
83    @see XDocumentPropertiesSupplier
84            for getting access to an instance from a loaded document
85    @see DocumentProperties     for a service that implements this interface
86 */
87published interface XDocumentProperties
88{
89    //-------------------------------------------------------------------------
90    /** contains the initial author of the document.
91     */
92
93    [attribute] string Author;
94
95    //-------------------------------------------------------------------------
96    /** identifies which application was used to create or last modify the
97        document.
98        <p>
99        The generating application will set this attribute when it creates a
100        new document or it saves a document. When a document is loaded that
101        itself contains such an attribute it will be preserved until the
102        document is saved again.
103        </p>
104     */
105
106    [attribute] string Generator;
107
108    //-------------------------------------------------------------------------
109    /** contains the date and time when the document was created.
110     */
111
112    [attribute] com::sun::star::util::DateTime CreationDate;
113
114    //-------------------------------------------------------------------------
115    /** contains the title of the document.
116     */
117
118    [attribute] string Title;
119
120    //-------------------------------------------------------------------------
121    /** contains the subject of the document.
122     */
123
124    [attribute] string Subject;
125
126    //-------------------------------------------------------------------------
127    /** contains a multi-line comment describing the document.
128        <p>
129        Line delimiters can be UNIX, Macintosh or DOS style.
130        </p>
131     */
132
133    [attribute] string Description;
134
135    //-------------------------------------------------------------------------
136    /** contains a list of keywords for the document.
137     */
138
139    [attribute] sequence< string > Keywords;
140
141    //-------------------------------------------------------------------------
142    /** contains the default language of the document.
143     */
144
145    [attribute] com::sun::star::lang::Locale Language;
146
147    //-------------------------------------------------------------------------
148    /** contains the name of the person who most recently stored the document.
149     */
150
151    [attribute] string ModifiedBy;
152
153    //-------------------------------------------------------------------------
154    /** contains the date and time of the last time the document was stored.
155        <p>
156        If the document has never been stored, contains a default value.
157        </p>
158     */
159
160    [attribute] com::sun::star::util::DateTime ModificationDate;
161
162    //-------------------------------------------------------------------------
163    /** contains the name of the person who most recently printed the document.
164     */
165
166    [attribute] string PrintedBy;
167
168    //-------------------------------------------------------------------------
169    /** contains the date and time when the document was last printed.
170        <p>
171        If the document has never been printed, contains a default value.
172        </p>
173     */
174
175    [attribute] com::sun::star::util::DateTime PrintDate;
176
177    //-------------------------------------------------------------------------
178    /** contains the name of the template from which the document was created.
179        <p>
180        The value is an empty <atom>string</atom> if the document was not
181        created from a template or if it was detached from the template.
182        </p>
183     */
184
185    [attribute] string TemplateName;
186
187    //-------------------------------------------------------------------------
188    /** contains the URL of the template from which the document was created.
189        <p>
190        The value is an empty <atom>string</atom> if the document was not
191        created from a template or if it was detached from the template.
192        </p>
193     */
194
195    [attribute] string TemplateURL;
196
197    //-------------------------------------------------------------------------
198    /** contains the date and time of when the document
199        was created or updated from the template.
200     */
201
202    [attribute] com::sun::star::util::DateTime TemplateDate;
203
204    //-------------------------------------------------------------------------
205    /** contains the URL to load automatically at a
206        specified time after the document is loaded into a desktop frame.
207        <p>
208        An empty URL is valid and describes a case where the document shall be
209        reloaded from its original loction after some time described by the
210        attribute <member>AutoloadSecs</member>.
211        An empty <atom>string</atom> together with an
212        <member>AutoloadSecs</member> value of 0
213        describes a case where no autoload is specified.
214        </p>
215
216        @see AutoloadSecs
217     */
218
219    [attribute] string AutoloadURL;
220
221    //-------------------------------------------------------------------------
222    /** contains the number of seconds after which a specified
223        URL is to be loaded after the document is loaded into a desktop
224        frame.
225        <p>
226        A value of 0 is valid and describes a redirection.
227        A value of 0 together with an empty <atom>string</atom> as
228        <member>AutoloadURL</member>
229        describes a case where no autoload is specified.
230        </p>
231
232        @throws com::sun::star::lang::IllegalArgumentException
233            if argument is negative
234
235        @see AutoloadURL
236     */
237
238    [attribute] long AutoloadSecs {
239            set raises ( com::sun::star::lang::IllegalArgumentException );
240    };
241
242    //-------------------------------------------------------------------------
243    /** contains the name of the default frame into which
244        links should be loaded if no target is specified.
245        <p>
246        This applies to the autoload feature too, but to others as well.
247        </p>
248     */
249
250    [attribute] string DefaultTarget;
251
252    //-------------------------------------------------------------------------
253    /** contains some statistics about the document.
254        <p>
255        The contained statistics may be specific to the type of the document.
256        </p>
257     */
258
259    [attribute]
260         sequence< com::sun::star::beans::NamedValue > DocumentStatistics;
261
262    //-------------------------------------------------------------------------
263    /** describes how often the document was edited and saved.
264        <p>
265        </p>
266
267        @throws com::sun::star::lang::IllegalArgumentException
268            if argument is negative
269     */
270
271    [attribute] short EditingCycles {
272            set raises ( com::sun::star::lang::IllegalArgumentException );
273    };
274
275    //-------------------------------------------------------------------------
276    /** contains the net time of editing the document (in seconds).
277        <p>
278        </p>
279
280        @throws com::sun::star::lang::IllegalArgumentException
281            if argument is negative
282     */
283
284    [attribute] long EditingDuration {
285            set raises ( com::sun::star::lang::IllegalArgumentException );
286    };
287
288    //-------------------------------------------------------------------------
289    /** resets all attributes that could identify the user.
290        <p>
291        Clears the document properties, such that it apperars the document
292        has just been created.
293        This is a convenience method which resets several attributes at once,
294        as follows:
295        <ul>
296        <li><member>Author</member> is set to the given parameter.</li>
297        <li><member>CreationDate</member> is set to the current date and time.
298        </li>
299        <li><member>ModifiedBy</member> is cleared.</li>
300        <li><member>ModificationDate</member> is cleared.</li>
301        <li><member>PrintedBy</member> is cleared.</li>
302        <li><member>PrintDate</member> is cleared.</li>
303        <li><member>EditingDuration</member> is cleared.</li>
304        <li><member>EditingCycles</member> is set to 1.</li>
305        </ul>
306
307        @param Author
308            the new value of the <member>Author</member> attribute.
309        </p>
310     */
311    void resetUserData( [in] string Author );
312
313    //-------------------------------------------------------------------------
314    /** provides access to a container for user-defined properties.
315        <p>
316        The returned object also implements the interface
317        <type>com::sun::star::beans::XPropertySet</type>.
318        </p>
319        @returns    a container that provides access to user-defined properties
320     */
321
322    com::sun::star::beans::XPropertyContainer getUserDefinedProperties();
323
324    //-------------------------------------------------------------------------
325    /** loads document properties from an ODF package.
326        <p>
327        This method is used for accessing an ODF package that is owned by
328        someone else, e.g., a document.
329        </p>
330
331        @param Storage
332            the <type>com::sun::star::embed::Storage</type> representing the
333            ODF package
334
335        @param Medium
336            the <type>com::sun::star::document::MediaDescriptor</type>
337            representing the source
338            <p>
339            This is unfortunately necessary in order to properly resolve
340            relative URLs in the meta-data.
341            </p>
342
343        @throws com::sun::star::lang::IllegalArgumentException
344                 if argument is <NULL/>
345        @throws com::sun::star::io::WrongFormatException
346                 if parsing the XML document fails
347        @throws com::sun::star::lang::WrappedTargetException
348                 if thrown when trying to open a stream in the given storage
349        @throws com::sun::star::io::IOException
350                 if thrown when trying to open a stream in the given storage
351     */
352
353    void loadFromStorage( [in] com::sun::star::embed::XStorage Storage,
354                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
355        raises( com::sun::star::lang::IllegalArgumentException,
356                com::sun::star::io::WrongFormatException,
357                com::sun::star::lang::WrappedTargetException,
358                com::sun::star::io::IOException );
359
360    //-------------------------------------------------------------------------
361    /** loads document properties from an ODF package or an OLE container.
362
363        @param URL
364            the URL of the source document
365            <p>
366            The URL could be part of the Medium parameter, but because often
367            no other parameters except the URL are needed, providing it
368            separately was added for convenience.
369            </p>
370
371        @param Medium
372            the <type>com::sun::star::document::MediaDescriptor</type>
373            representing the source
374
375        @throws com::sun::star::io::WrongFormatException
376                 if parsing the XML document fails
377        @throws com::sun::star::lang::WrappedTargetException
378                 if thrown when trying to open a stream in the given storage
379        @throws com::sun::star::io::IOException
380                 if thrown when trying to open a stream in the given storage
381     */
382
383    void loadFromMedium( [in] string URL,
384                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
385        raises( com::sun::star::io::WrongFormatException,
386                com::sun::star::lang::WrappedTargetException,
387                com::sun::star::io::IOException );
388
389    //-------------------------------------------------------------------------
390    /** stores document properties to an ODF package.
391        <p>
392        This method is used for accessing an ODF package that is owned by
393        someone else, e.g., a document.
394        Note that the implementation may choose to store the meta-data
395        in either OOo or ODF format, depending on the MediaType property
396        of the given <type>Storage</type> argument.
397        </p>
398
399        @param Storage
400            the <type>com::sun::star::embed::Storage</type> representing the
401            ODF package
402
403        @param Medium
404            the <type>com::sun::star::document::MediaDescriptor</type>
405            representing the source
406            <p>
407            This is unfortunately necessary in order to properly resolve
408            relative URLs in the meta-data.
409            </p>
410
411        @throws com::sun::star::lang::IllegalArgumentException
412                 if argument is <NULL/>
413        @throws com::sun::star::lang::WrappedTargetException
414                 if thrown when trying to open a stream in the given storage
415        @throws com::sun::star::io::IOException
416                 if thrown when writing to the storage
417     */
418
419    void storeToStorage( [in] com::sun::star::embed::XStorage Storage,
420                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
421        raises( com::sun::star::lang::IllegalArgumentException,
422                com::sun::star::lang::WrappedTargetException,
423                com::sun::star::io::IOException );
424
425    //-------------------------------------------------------------------------
426    /** stores document properties to an ODF package or an OLE container.
427
428        @param URL
429            the URL of the target document
430            <p>
431            The URL could be part of the Medium parameter, but because often
432            no other parameters except the URL are needed, providing it
433            separately was added for convenience.
434            </p>
435
436        @param Medium
437            the <type>com::sun::star::document::MediaDescriptor</type>
438            representing the target
439
440        @throws com::sun::star::lang::WrappedTargetException
441                 if thrown when trying to open a stream in the given storage
442        @throws com::sun::star::io::IOException
443                 if thrown when writing to the storage
444     */
445
446    void storeToMedium( [in] string URL,
447                [in] sequence < com::sun::star::beans::PropertyValue > Medium )
448        raises( com::sun::star::lang::WrappedTargetException,
449                com::sun::star::io::IOException );
450};
451
452//=============================================================================
453
454}; }; }; };
455
456#endif
457