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_XTypeDetection_idl__
24#define __com_sun_star_document_XTypeDetection_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30#ifndef __com_sun_star_beans_PropertyValue_idl__
31#include <com/sun/star/beans/PropertyValue.idl>
32#endif
33
34//============================================================================
35
36module com { module sun { module star { module document {
37
38//============================================================================
39/** support "flat" and "deep" type detection of a given document
40
41    <p>
42    A "flat" detection means specifying the document format by using
43    the URL and some configuration data only. That will perform but produce
44    may invalid results if e.g., the extension of the document is wrong.
45    A "deep" detection means looking into the document stream to be right
46    which format it supports. Of course that includes a "flat" detection before.
47    The combination of both ones should produce stable results everytime.
48    </p>
49
50    @see TypeDetection
51 */
52published interface XTypeDetection: com::sun::star::uno::XInterface
53{
54	//-------------------------------------------------------------------------
55    /** make a "flat" detection by using the URL of the document
56
57		<p>
58        It use given URL in combination with the internal configuration of well known
59        types only to specify the format of given document.
60		</p>
61
62        @param URL
63            specify the document by name
64
65        @returns
66            an internal type name which represent the detected format
67            <br>
68            or an empty value for unknown ones
69	 */
70    string queryTypeByURL( [in] string URL );
71
72	//-------------------------------------------------------------------------
73    /** make a "deep" detection or optional a "flat" detection by using a
74        <type>MediaDescriptor</type>
75
76		<p>
77        Instead of <member>XTypeDetection::queryTypeByURL()</member> this function
78        use a <type>MediaDescriptor</type> to specify the document for detection.
79        Such descriptor hold different informations about the document.
80        He will be passed to any part of made detection process and every part
81        can change it to actualize it.
82        The property <member>MediaDescriptor::URL</member> should be set on
83        this descriptor as minimum. It specifies the location of the document.
84        If this parameter is missing another one is required: <member>MediaDescriptor::InputStream</member>.
85        This can be usefull to prevent operaton against multiple opening of the stream
86        and perform the operation. If this stream isn't already included the detection
87        will open it (if allowed!) and add it to the descriptor so it will be available for
88        all following parts.
89        A combination of both parameters can be usefull to perform the operation
90        and make results more stable; but only one of them is required.
91        Of course its possible to specify more document properties (e.g.
92        <member>MediaDescriptor::ReadOnly</member>).
93        <br>
94        As an additional feature it's possible to suppress "deep" detection by using argument
95        <var>AllowDeep</var>.
96		</p>
97
98        @param Descriptor
99            means the <type>MediaDescriptor</type> which specify the ressource for detection
100
101        @param AllowDeep
102            if it is set to <TRUE/> a "deep" detection will be follow a "flat" detection
103            <br>
104            if it is set to <FALSE/> a "flat" detection will be made only
105
106        @returns
107            an internal type name which represent the detected format
108            <br>
109            or an empty value for unknown ones
110	 */
111    string queryTypeByDescriptor(
112        [inout] sequence< com::sun::star::beans::PropertyValue > Descriptor,
113        [in] boolean AllowDeep );
114};
115
116//============================================================================
117
118}; }; }; };
119
120#endif
121