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_MediaDescriptor_idl__ 24#define __com_sun_star_document_MediaDescriptor_idl__ 25 26#ifndef __com_sun_star_io_XOutputStream_idl__ 27#include <com/sun/star/io/XOutputStream.idl> 28#endif 29 30#ifndef __com_sun_star_io_XInputStream_idl__ 31#include <com/sun/star/io/XInputStream.idl> 32#endif 33 34#ifndef __com_sun_star_awt_Rectangle_idl__ 35#include <com/sun/star/awt/Rectangle.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_util_URL_idl__ 43#include <com/sun/star/util/URL.idl> 44#endif 45 46#ifndef __com_sun_star_task_XInteractionHandler_idl__ 47#include <com/sun/star/task/XInteractionHandler.idl> 48#endif 49 50#ifndef __com_sun_star_task_XStatusIndicator_idl__ 51#include <com/sun/star/task/XStatusIndicator.idl> 52#endif 53 54#ifndef __com_sun_star_frame_XFrame_idl__ 55#include <com/sun/star/frame/XFrame.idl> 56#endif 57 58//============================================================================= 59 60module com { module sun { module star { module document { 61 62//============================================================================= 63/** describes properties of a document, regarding the relationship 64 between the loaded document and the resource the document is 65 loaded from / stored to. 66 67 <p> 68 This service may be represented by a 69 <type scope="com::sun::star::beans" dim="[]">PropertyValue</type>. 70 Such descriptors will be passed to different functions, included into possible 71 load/save proccesses. Every member of such process can use this descriptor 72 and may change it if to actualize the informations about the document. 73 So this descriptor should be used as an in/out parameter. 74 </p> 75 76 <p> 77 Note:<br> 78 It's not allowed to hold member of this descriptor by references longer the they 79 will be used (especialy a possible stream). It's allowed to use it directly 80 or by copying it only. 81 </p> 82 83 @see com::sun::star::beans::PropertyValue 84 */ 85published service MediaDescriptor 86{ 87 //------------------------------------------------------------------------- 88 /** May be set by filters or detection services if user has choosen to 89 abort loading/saving, e.g. while entering a password. 90 */ 91 [optional,property] boolean Aborted; 92 93 //------------------------------------------------------------------------- 94 /** document is a template 95 96 <p> 97 Loading a component of type "template" creates a new untitled document 98 by default, but setting the "AsTemplate" property to <FALSE/> loads the 99 template document for editing. Setting "AsTemplate" to <TRUE/> creates a 100 new untitled document out of the loaded document, even if it has not 101 a "template" type. 102 </p> 103 */ 104 [optional,property] boolean AsTemplate; 105 106 //------------------------------------------------------------------------- 107 /** the author of the document 108 109 <p> 110 Only for storing versions in components supporting versioning: 111 author of version. 112 </p> 113 */ 114 [optional,property] string Author; 115 116 //------------------------------------------------------------------------- 117 /** identifier of used character set 118 119 <p> 120 Defines the character set for document formats that contain single 121 byte characters (if necessary). 122 </p> 123 */ 124 [optional,property] string CharacterSet; 125 126 //------------------------------------------------------------------------- 127 /** description of document 128 129 <p> 130 Only for storing versions in components supporting versioning: 131 comment (description) for stored version. 132 </p> 133 */ 134 [optional,property] string Comment; 135 136 //------------------------------------------------------------------------- 137 /** pack specific properties of caller 138 139 <p> 140 This is a parameter that can be used for any properties specific 141 for a special component type. Format of that depends from real 142 type of adressed component. 143 </p> 144 145 <p> 146 For extensibility, it is recommended to use values of type 147 sequence<com.sun.star.beans.NamedValue> with this property. 148 </p> 149 */ 150 [optional,property] any ComponentData; 151 152 //------------------------------------------------------------------------- 153 /** The base URL of the document to be used to resolve relative links. 154 */ 155 [optional,property] string DocumentBaseURL; 156 157 //------------------------------------------------------------------------- 158 /** document title 159 160 <p> 161 This parameter can be used to specify a title for a document. 162 </p> 163 */ 164 [optional,property] string DocumentTitle; 165 166 //------------------------------------------------------------------------- 167 /** encryption information for encryption/decryption of documents 168 169 <p> 170 It contains the necessary information for encryption/decryption of 171 a component (if necessary). 172 If neither password nor encryption data is specified, loading of 173 a password protected document will fail, storing will be done without 174 encryption. If both are provided, the encryption data is used 175 ( if the filter supports it ). 176 </p> 177 <p> 178 The encryption data is generated based on the password. 179 </p> 180 */ 181 [optional,property] sequence< ::com::sun::star::beans::NamedValue > EncryptionData; 182 183 //------------------------------------------------------------------------- 184 /** same as <member>MediaDescriptor::URL</member> 185 186 <p> 187 It will be supported for compatibility reasons only. 188 </p> 189 190 @deprecated 191 */ 192 [optional,property] string FileName; 193 194 //------------------------------------------------------------------------- 195 /** internal filter name 196 197 <p> 198 Name of a filter that should be used for loading or storing the component. 199 Names must match the names of the <type>TypeDetection</type> configuration, 200 invalid names are ignored. If a name is specified on loading, 201 it still will be verified by a filter detection, but in case of doubt 202 it will be preferred. 203 </p> 204 */ 205 [optional,property] string FilterName; 206 207 //------------------------------------------------------------------------- 208 /** same as <member>MediaDescriptor::FilterOptions</member> 209 210 <p> 211 It will be supported for compatibility reasons only. 212 </p> 213 214 @deprecated 215 */ 216 [optional,property] string FilterFlags; 217 218 //------------------------------------------------------------------------- 219 /** additional properties for filter 220 221 <p> 222 Some filters need additional parameters; use only together with property 223 <member>MediaDescriptor::FilterName</member>. Details must be documented 224 by the filter. This is an old format for some filters. If a string is not 225 enough, filters can use the property <member>MediaDescriptor::FilterData</member>. 226 </p> 227 */ 228 [optional,property] string FilterOptions; 229 230 //------------------------------------------------------------------------- 231 /** additional properties for filter 232 233 <p> 234 This is a parameter that can be used for any properties specific 235 for a special filter type. It should be used if 236 <member>MediaDescriptor::FilterOptions</member> isn't enough. 237 </p> 238 */ 239 [optional,property] any FilterData; 240 241 //------------------------------------------------------------------------- 242 /** load document invisible 243 244 <p> 245 Defines if the loaded component is made visible. If this property is not 246 specified, the component is made visible by default. 247 </p> 248 */ 249 [optional,property] boolean Hidden; 250 251 //------------------------------------------------------------------------- 252 /** The hierarchical path to the embedded document from topmost container. 253 */ 254 [optional,property] string HierarchicalDocumentName; 255 256 //------------------------------------------------------------------------- 257 /** a stream to receive the document data. 258 259 <p> 260 If used when storing a document: writing must be done using this stream. 261 If no stream is provided, the loader will create a stream by itself using 262 the other properties. It is not allowed to keep a reference to this 263 OutputStream after storing the component. 264 </p> 265 */ 266 [optional,property] com::sun::star::io::XOutputStream OutputStream; 267 268 //------------------------------------------------------------------------- 269 /** content of document 270 271 <p> 272 If used when loading a document: reading must be done using this stream. 273 If no stream is provided, the loader will create a stream by itself using 274 the other properties. It is not allowed to keep a reference to this 275 InputStream after loading the component, and it would be useless, because 276 in general an InputStream is usable for readong only once, except when it 277 also implements the <type scope="com::sun::star::io">XSeekable</type> interface. 278 </p> 279 */ 280 [optional,property] com::sun::star::io::XInputStream InputStream; 281 282 //------------------------------------------------------------------------- 283 /** handle exceptional situations 284 285 <p> 286 Object implementing the <type scope="com::sun::star::task">InteractionHandler</type> 287 service that is used to handle exceptional situations where proceeding with the task 288 is impossible without additional information or impossible at all. 289 The implemented api provides a default implementation for it that can handle many situations. 290 If no InteractionHandler is set, a suitable exception is thrown. 291 It is not allowed to keep a reference to this object, even not in the loaded 292 or stored components' copy of the MediaDescriptor provided by its arguments attribute. 293 </p> 294 */ 295 [optional,property] com::sun::star::task::XInteractionHandler InteractionHandler; 296 297 //------------------------------------------------------------------------- 298 /** jump to a marked position after loading 299 300 <p> 301 This is the same as the text behind a '#' in a http URL. But 302 this syntax with a '#' is not specified in most URL schemas. 303 </p> 304 */ 305 [optional,property] string JumpMark; 306 307 //------------------------------------------------------------------------- 308 /** specify mime type of content 309 310 <p> 311 Type of the medium to load, that must match to one of the types defined 312 in the <type>TypeDetection</type> configuration (otherwise it's ignored). 313 This bypasses the type detection of the <type scope="com::sun::star::frame">Desktop</type> environment, 314 so passing a wrong MediaType will cause failure of loading. 315 </p> 316 */ 317 [optional,property] string MediaType; 318 319 //------------------------------------------------------------------------- 320 /** please use the corresponding parameters of this descriptor instead 321 322 <p> 323 String that summarizes some flags for loading. The string contains capital 324 letters for the flags:<br> 325 <table border=1> 326 <tr> 327 <td><strong>flag</strong></td> 328 <td><strong>value</strong></td> 329 <td><strong>replacement</strong></td> 330 </tr> 331 <tr> 332 <td><em>ReadOnly</em></td> 333 <td>R</td> 334 <td><member>MediaDescriptor::ReadOnly</member></td> 335 </tr> 336 <tr> 337 <td><em>Preview</em></td> 338 <td>B</td> 339 <td><member>MediaDescriptor::Preview</member></td> 340 </tr> 341 <tr> 342 <td><em>AsTemplate</em></td> 343 <td>T</td> 344 <td><member>MediaDescriptor::AsTemplate</member></td> 345 </tr> 346 <tr> 347 <td><em>Hidden</em></td> 348 <td>H</td> 349 <td><member>MediaDescriptor::Hidden</member></td> 350 </tr> 351 </table> 352 </p> 353 354 @deprecated 355 */ 356 [optional,property] string OpenFlags; 357 358 //------------------------------------------------------------------------- 359 /** opens a new view for an already loaded document 360 361 <p> 362 Setting this to <TRUE/> forces the component to create a new window on loading 363 in any case. If the component supports multiple views, a second view is 364 opened, if not, the component is loaded one more time. Otherwise the behavior 365 depends on the default window handling of the <type scope="com::sun::star::frame">Desktop</type> environment. 366 </p> 367 */ 368 [optional,property] boolean OpenNewView; 369 370 371 //------------------------------------------------------------------------- 372 /** overwrite any existing file 373 374 <p> 375 For storing only: overwrite any existing file, default is <FALSE/>, 376 so an error occurs if the target file already exists. 377 </p> 378 */ 379 [optional,property] boolean Overwrite; 380 381 //------------------------------------------------------------------------- 382 /** pasword for loading storing documents 383 384 <p> 385 It contains a password for loading or storing a component (if necessary). 386 If neither password nor encryption data is specified, loading of 387 a password protected document will fail, storing will be done without 388 encryption. If both are provided, the encryption data is used 389 ( if the filter supports it ). 390 </p> 391 */ 392 [optional,property] string Password; 393 394 //------------------------------------------------------------------------- 395 /** contains the data for HTTP post method as a sequence of bytes. 396 397 <p> 398 Data to send to a location described by the media descriptor to get 399 a result in return that will be loaded as a component 400 (usually in webforms). Default is: no PostData. 401 </p> 402 */ 403 [optional,property] sequence< byte > PostData; 404 405 //------------------------------------------------------------------------- 406 /** use <member>MediaDescriptor::PostData</member> instead of this 407 408 <p> 409 Same as PostData, but the data is transferred as a string 410 (just for compatibility). 411 </p> 412 413 @deprecated 414 */ 415 [optional,property] string PostString; 416 417 //------------------------------------------------------------------------- 418 /** show preview 419 420 <p> 421 Setting this to <TRUE/> tells the a loaded component that it is loaded as 422 a preview, so it can optimize loading and viewing for this special purpose. 423 Default is <FALSE/>. 424 </p> 425 */ 426 [optional,property] boolean Preview; 427 428 //------------------------------------------------------------------------- 429 /** open document readonly 430 431 <p> 432 Tells whether a document should be loaded in a (logical) readonly or in 433 read/write mode. If opening in the desired mode is impossible, an error occurs. 434 By default the loaded content decides what to do: if its UCB content supports 435 a "readonly" property, the logical open mode depends on that, otherwise 436 it will be read/write. This is only a UI related property, opening a 437 document in read only mode will not prevent the component from being 438 modified by API calls, but all modifying functionality in the UI will 439 be disabled or removed. 440 </p> 441 */ 442 [optional,property] boolean ReadOnly; 443 444 //------------------------------------------------------------------------- 445 /** start presentation from a document 446 447 <p> 448 Tells the component loading the document that a presentation that is in the 449 document is to be started right away. 450 </p> 451 */ 452 [optional,property] boolean StartPresentation; 453 454 //------------------------------------------------------------------------- 455 /** name of document referrer 456 457 <p> 458 A URL describing the environment of the request; f.e. a referrer may be a 459 URL of a document, if a hyperlink inside this document is clicked to load 460 another document. The referrer may be evaluated by the addressed UCB content 461 or the loaded document. Without a referrer the processing of URLs that 462 needs security checks will be denied, f.e. "macro:" URLs. 463 <br> 464 Don't be confused about the wrong spelling; is kept for compatibility reasons. 465 </p> 466 */ 467 [optional,property] string Referer; 468 469 //------------------------------------------------------------------------- 470 /** let the document be opened in repair mode 471 472 <p> 473 For loading of corrupted zip packages: Setting this to <TRUE/> let the document 474 be opened in repair mode, so as much as possible information will be retrieved. 475 </p> 476 477 @since OpenOffice 1.1.2 478 */ 479 [optional,property] boolean RepairPackage; 480 481 //------------------------------------------------------------------------- 482 /** can be used for status informations 483 484 <p> 485 Object implementing the <type scope="com::sun::star::task">XStatusIndicator</type> 486 interface that can be used to give status information (text or progress) for the task. 487 The office provides a default implementation for it. It is not allowed to keep 488 a reference to this object, even not in the loaded or stored components' 489 copy of the MediaDescriptor provided by its arguments attribute. 490 </p> 491 */ 492 [optional,property] com::sun::star::task::XStatusIndicator StatusIndicator; 493 494 //------------------------------------------------------------------------- 495 /** allows to specify the URL that is used next time SaveAs dialog is opened 496 497 <p> 498 If the parameter is specified, the URL will be used by SaveAs dialog 499 next time as target folder. 500 </p> 501 */ 502 [optional,property] string SuggestedSaveAsDir; 503 504 //------------------------------------------------------------------------- 505 /** allows to specify the suggested file name that is used next time SaveAs 506 dialog is opened 507 508 <p> 509 If the parameter is specified, the file name will be suggested by 510 SaveAs dialog next time. 511 </p> 512 */ 513 [optional,property] string SuggestedSaveAsName; 514 515 //------------------------------------------------------------------------- 516 /** name of the template instead of the URL 517 518 <p> 519 The logical name of a template to load. Together with the <member>MediaDescriptor::TemplateRegion</member> 520 property it can be used instead of the URL of the template. Use always in conjunction with 521 <member>MediaDescriptor::TemplateRegionName</member>. 522 </p> 523 */ 524 [optional,property] string TemplateName; 525 526 //------------------------------------------------------------------------- 527 /** name of the template instead of the URL 528 529 <p> 530 The logical name of a template to load. Together with the <member>MediaDescriptor::TemplateRegion</member> 531 property it can be used instead of the URL of the template. Use always in conjunction with 532 <member>MediaDescriptor::TemplateRegionName</member>. 533 </p> 534 */ 535 [optional,property] string TemplateRegionName; 536 537 //------------------------------------------------------------------------- 538 /** regulate using of compressing 539 540 <p> 541 For storing: Setting this to <TRUE/> means, don't use a zip file to save 542 the document, use a folder instead (only usable for UCB contents, that 543 support folders). Default is <FALSE/>. 544 </p> 545 */ 546 [optional,property] boolean Unpacked; 547 548 //------------------------------------------------------------------------- 549 /** URL of the document 550 551 <p> 552 The location of the component in URL syntax. It must be the full qualified URL and 553 must include f.e. an optional <member>MediaDescriptor::JumpMark</member> too. 554 </p> 555 */ 556 [optional,property] string URL; 557 558 //------------------------------------------------------------------------- 559 /** storage version 560 561 <p> 562 For components supporting versioning: the number of the version to be 563 loaded or saved. Default is zero and means: no version is created or 564 loaded, the "main" document is processed. 565 </p> 566 */ 567 [optional,property] short Version; 568 569 //------------------------------------------------------------------------- 570 /** set special view state 571 <p> 572 Data to set a special view state after loading. The type depends on 573 the component and is usually retrieved from a <type scope="com::sun::star::frame">Controller</type> 574 object by its <type scope="com::sun::star::frame">XController</type> 575 interface. Default is: no view data. 576 </p> 577 */ 578 [optional,property] any ViewData; 579 580 //------------------------------------------------------------------------- 581 /** id of the initial view 582 583 <p> 584 For components supporting different views: a number to define the view 585 that should be constructed after loading. Default is: zero, and this 586 should be treated by the component as the default view. 587 </p> 588 */ 589 [optional,property] short ViewId; 590 591 //------------------------------------------------------------------------- 592 /** should the macro be executed. 593 the value should be one from <type scope="com::sun::star::document">MacroExecMode</type> 594 constant list. 595 596 @since OpenOffice 1.1.2 597 */ 598 [optional,property] short MacroExecutionMode; 599 600 //------------------------------------------------------------------------- 601 /** can the document be updated depending from links. 602 the value should be one from <type scope="com::sun::star::document">UpdateDocMode</type> 603 constant list. 604 605 @since OpenOffice 1.1.2 606 */ 607 [optional,property] short UpdateDocMode; 608 609 //------------------------------------------------------------------------- 610 /** specifies the name of the view controller to create when loading a document 611 612 <p>If this property is used when loading a document into a frame, then it 613 specifies the name of the view controller to create. That is, the property 614 is passed to the document's <member scope="com::sun::star::frame">XModel2::createViewController</member> 615 method.<br/> 616 If the loaded document does not support the <code>XModel2</code> interface, 617 the property is ignored.</p> 618 619 @see ::com::sun::star::frame::XModel2::createViewController 620 @see ::com::sun::star::frame::XController2::ViewControllerName 621 622 @since OpenOffice 3.0 623 */ 624 [optional,property] string ViewControllerName; 625 //------------------------------------------------------------------------- 626 627 /** specifies the frame containing the document. May be empty. 628 */ 629 [optional,property] com::sun::star::frame::XFrame Frame; 630}; 631 632//============================================================================= 633 634}; }; }; }; 635 636#endif 637