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 OOo 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 OOo 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 OOo 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 OOo 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