offapi/com/sun/star/document/XDocumentProperties.idl

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