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

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