/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */


module com { module sun { module star { module document {

/** support "flat" and "deep" type detection of a given document

    <p>
    A "flat" detection means specifying the document format by using
    the URL and some configuration data only. That will perform but produce
    may invalid results if e.g., the extension of the document is wrong.
    A "deep" detection means looking into the document stream to be right
    which format it supports. Of course that includes a "flat" detection before.
    The combination of both ones should produce stable results every time.
    </p>

    @see TypeDetection
 */
published interface XTypeDetection: com::sun::star::uno::XInterface
{
    /** make a "flat" detection by using the URL of the document

        <p>
        It use given URL in combination with the internal configuration of well known
        types only to specify the format of given document.
        </p>

        @param URL
            specify the document by name

        @returns
            an internal type name which represent the detected format
            <br>
            or an empty value for unknown ones
     */
    string queryTypeByURL( [in] string URL );

    /** make a "deep" detection or optional a "flat" detection by using a
        MediaDescriptor

        <p>
        Instead of XTypeDetection::queryTypeByURL() this function
        use a MediaDescriptor to specify the document for detection.
        Such descriptor hold different information about the document.
        He will be passed to any part of made detection process and every part
        can change it to actualize it.
        The property MediaDescriptor::URL should be set on
        this descriptor as minimum. It specifies the location of the document.
        If this parameter is missing another one is required: MediaDescriptor::InputStream.
        This can be useful to prevent operation against multiple opening of the stream
        and perform the operation. If this stream isn't already included the detection
        will open it (if allowed!) and add it to the descriptor so it will be available for
        all following parts.
        A combination of both parameters can be useful to perform the operation
        and make results more stable; but only one of them is required.
        Of course its possible to specify more document properties (e.g.
        MediaDescriptor::ReadOnly).
        <br>
        As an additional feature it's possible to suppress "deep" detection by using argument
        <var>AllowDeep</var>.
        </p>

        @param Descriptor
            means the MediaDescriptor which specify the resource for detection

        @param AllowDeep
            if it is set to `TRUE` a "deep" detection will be follow a "flat" detection
            <br>
            if it is set to `FALSE` a "flat" detection will be made only

        @returns
            an internal type name which represent the detected format
            <br>
            or an empty value for unknown ones
     */
    string queryTypeByDescriptor(
        [inout] sequence< com::sun::star::beans::PropertyValue > Descriptor,
        [in] boolean AllowDeep );
};


}; }; }; };

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
