/* -*- 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 ucb {

/** makes it possible to query/register/deregister content providers.

    @version  1.0
    @see      XContentProvider
*/
published interface XContentProviderManager: com::sun::star::uno::XInterface
{
    /** registers a content provider for a specific URL template.

        @see XContentIdentifier

        @param Provider
        the content provider to register.

        <p>This may be `NULL`, in which case a later
        XContentProvider::queryContent() with an
        XContentIdentifier that matches the <var>Scheme</var>
        will simply return `NULL`. These "dummy" content providers are useful
        in combination with other content providers that are registered on a
        wildcard URL template: For example, imagine that you want to route all
        http URLs to a HTTP content provider, but want to block all URLs for
        the server <code>www.dont.go</code>. One solution would be to register
        the HTTP content provider on the <var>Scheme</var> <code>http</code>,
        and to register a "dummy" (i.e., `NULL`) content provider on the
        <var>Scheme</var> <code>"http://www.dont.go"([/?#].*)?</code>.

        @param Scheme
        the URL scheme for the provided contents. More generally, this may not
        only be a URL scheme, but a URL template.

        <p>A URL template is a regular expression (represented as a string) that
        specifies a subset of the set of all possible URLs (this subset
        consists of exactly those URLs that match the regular expression).  The
        language to denote the regular expressions is initially quite limited,
        but it may be extended in the future:

        <p><ul>
        <li><code>regexp = scheme / simple / translation</code></li>
        <li><code>scheme = ALPHA *(ALPHA / DIGIT / "+" / "-" / ".")</code></li>
        <li><code>simple = simple-prefix / simple-authority / simple-domain</code></li>
        <li><code>translation = trans-prefix / trans-authority / trans-domain</code></li>
        <li><code>simple-prefix = [string] ".*"</code></li>
        <li><code>trans-prefix = [string] "(.*)->" [string] "\1"</code></li>
        <li><code>simple-authority = [string] "([/?#].*)?"</code></li>
        <li><code>trans-authority = [string] "(([/?#].*)?)->" string "\1"</code></li>
        <li><code>simple-domain = [string] "[^/?#]*" string "([/?#].*)?"</code></li>
        <li><code>trans-domain = [string] "([^/?#]*" string "([/?#].*)?)->" string "\1"</code></li>
        <li><code>string = DQUOTE 1*(schar / sescape) DQUOTE  ; DQUOTE is "</code></li>
        <li><code>schar = &lt any UTF-16 character except " or \></code></li>
        <li><code>sescape = "\" (DQUOTE / "\")</code></li>
        </ul>

        <p>A <code>&lt;scheme&gt:</code> matches any URL of exactly the given
        scheme (ignoring case), keeping the extension from URL schemes to URL
        templates backwards compatible.  The <code>&lt;simple&gt:</code>
        regexps match any URL starting with a given string literal, followed
        by arbitrary characters (<code>&lt;simple-prefix&gt:</code>), or
        by arbitrary characters that start with one of '/', '?', or '#', if any
        (<code>&lt;simple-authority&gt:</code>), or by arbitrary characters not
        including any of '/', '?', or '#', followed by a given string literal,
        followed by arbitrary characters that start with one of '/', '?', or
        '#', if any. The comparison of string literals is done ignoring the
        case of ASCII letters.  The <code>&lt;translation&gt:</code> regexps
        match the same URLs as their <code>&lt;simple&gt:</code> counterparts,
        but they also describe how a (local) URL is mapped to another (remote)
        URL.  This mapping is only relevant for methods of the
        RemoteAccessContentProvider's
          XParameterizedContentProvider interface; in all other
        cases, <code>&lt;translation&gt:</code> regexps have the same semantics
        as their <code>&lt;simple&gt:</code> counterparts.

        @param ReplaceExisting
        `TRUE`: replace the provider possibly registered for the given URL
        template. The replaced provider will not be deregistered automatically!
        If the superseding provider gets deregistered, the superseded one will
        become active again.
        <p>`FALSE`: do not register, if another provider is already registered
        for the given URL template.

        @returns
        the replaced content provider, if there was one.
    */
    com::sun::star::ucb::XContentProvider registerContentProvider(
                [in] com::sun::star::ucb::XContentProvider Provider,
                [in] string Scheme,
                [in] boolean ReplaceExisting )
        raises( com::sun::star::ucb::DuplicateProviderException );

    /** deregisters a content provider.

        @param Provider
        a content provider to deregister.

        @param Scheme
        the URL scheme for the provided contents. More generally, this
        may not only be a URL scheme, but a URL template (see
        registerContentProvider() for a discussion of URL
        templates).
    */
    void deregisterContentProvider(
                [in] com::sun::star::ucb::XContentProvider Provider,
                 [in] string Scheme );

    /** returns a list of information on all registered content providers.

        @returns
        a list information on content providers.
    */
    sequence<com::sun::star::ucb::ContentProviderInfo> queryContentProviders();

    /** returns the currently active content provider for a content
        identifier.

        @param Identifier
        a content identifier (i.e., a URL).

        @returns
        a content provider, or null.
    */
    com::sun::star::ucb::XContentProvider queryContentProvider(
                [in] string Identifier );
};


}; }; }; };

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