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