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