offapi/com/sun/star/ucb/XContentProviderManager.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21
  22 module com { module sun { module star { module ucb {
  23
  24 /** makes it possible to query/register/deregister content providers.
  25
  26     @version  1.0
  27     @see      XContentProvider
  28 */
  29 published interface XContentProviderManager: com::sun::star::uno::XInterface
  30 {
  31     /** registers a content provider for a specific URL template.
  32
  33         @see XContentIdentifier
  34
  35         @param Provider
  36         the content provider to register.
  37
  38         <p>This may be `NULL`, in which case a later
  39         XContentProvider::queryContent() with an
  40         XContentIdentifier that matches the <var>Scheme</var>
  41         will simply return `NULL`. These "dummy" content providers are useful
  42         in combination with other content providers that are registered on a
  43         wildcard URL template: For example, imagine that you want to route all
  44         http URLs to a HTTP content provider, but want to block all URLs for
  45         the server <code>www.dont.go</code>. One solution would be to register
  46         the HTTP content provider on the <var>Scheme</var> <code>http</code>,
  47         and to register a "dummy" (i.e., `NULL`) content provider on the
  48         <var>Scheme</var> <code>"http://www.dont.go"([/?#].*)?</code>.
  49
  50         @param Scheme
  51         the URL scheme for the provided contents. More generally, this may not
  52         only be a URL scheme, but a URL template.
  53
  54         <p>A URL template is a regular expression (represented as a string) that
  55         specifies a subset of the set of all possible URLs (this subset
  56         consists of exactly those URLs that match the regular expression).  The
  57         language to denote the regular expressions is initially quite limited,
  58         but it may be extended in the future:
  59
  60         <p><ul>
  61         <li><code>regexp = scheme / simple / translation</code></li>
  62         <li><code>scheme = ALPHA *(ALPHA / DIGIT / "+" / "-" / ".")</code></li>
  63         <li><code>simple = simple-prefix / simple-authority / simple-domain</code></li>
  64         <li><code>translation = trans-prefix / trans-authority / trans-domain</code></li>
  65         <li><code>simple-prefix = [string] ".*"</code></li>
  66         <li><code>trans-prefix = [string] "(.*)->" [string] "\1"</code></li>
  67         <li><code>simple-authority = [string] "([/?#].*)?"</code></li>
  68         <li><code>trans-authority = [string] "(([/?#].*)?)->" string "\1"</code></li>
  69         <li><code>simple-domain = [string] "[^/?#]*" string "([/?#].*)?"</code></li>
  70         <li><code>trans-domain = [string] "([^/?#]*" string "([/?#].*)?)->" string "\1"</code></li>
  71         <li><code>string = DQUOTE 1*(schar / sescape) DQUOTE  ; DQUOTE is "</code></li>
  72         <li><code>schar = &lt any UTF-16 character except " or \></code></li>
  73         <li><code>sescape = "\" (DQUOTE / "\")</code></li>
  74         </ul>
  75
  76         <p>A <code>&lt;scheme&gt:</code> matches any URL of exactly the given
  77         scheme (ignoring case), keeping the extension from URL schemes to URL
  78         templates backwards compatible.  The <code>&lt;simple&gt:</code>
  79         regexps match any URL starting with a given string literal, followed
  80         by arbitrary characters (<code>&lt;simple-prefix&gt:</code>), or
  81         by arbitrary characters that start with one of '/', '?', or '#', if any
  82         (<code>&lt;simple-authority&gt:</code>), or by arbitrary characters not
  83         including any of '/', '?', or '#', followed by a given string literal,
  84         followed by arbitrary characters that start with one of '/', '?', or
  85         '#', if any. The comparison of string literals is done ignoring the
  86         case of ASCII letters.  The <code>&lt;translation&gt:</code> regexps
  87         match the same URLs as their <code>&lt;simple&gt:</code> counterparts,
  88         but they also describe how a (local) URL is mapped to another (remote)
  89         URL.  This mapping is only relevant for methods of the
  90         RemoteAccessContentProvider's
  91           XParameterizedContentProvider interface; in all other
  92         cases, <code>&lt;translation&gt:</code> regexps have the same semantics
  93         as their <code>&lt;simple&gt:</code> counterparts.
  94
  95         @param ReplaceExisting
  96         `TRUE`: replace the provider possibly registered for the given URL
  97         template. The replaced provider will not be deregistered automatically!
  98         If the superseding provider gets deregistered, the superseded one will
  99         become active again.
 100         <p>`FALSE`: do not register, if another provider is already registered
 101         for the given URL template.
 102
 103         @returns
 104         the replaced content provider, if there was one.
 105     */
 106     com::sun::star::ucb::XContentProvider registerContentProvider(
 107                 [in] com::sun::star::ucb::XContentProvider Provider,
 108                 [in] string Scheme,
 109                 [in] boolean ReplaceExisting )
 110         raises( com::sun::star::ucb::DuplicateProviderException );
 111
 112     /** deregisters a content provider.
 113
 114         @param Provider
 115         a content provider to deregister.
 116
 117         @param Scheme
 118         the URL scheme for the provided contents. More generally, this
 119         may not only be a URL scheme, but a URL template (see
 120         registerContentProvider() for a discussion of URL
 121         templates).
 122     */
 123     void deregisterContentProvider(
 124                 [in] com::sun::star::ucb::XContentProvider Provider,
 125                  [in] string Scheme );
 126
 127     /** returns a list of information on all registered content providers.
 128
 129         @returns
 130         a list information on content providers.
 131     */
 132     sequence<com::sun::star::ucb::ContentProviderInfo> queryContentProviders();
 133
 134     /** returns the currently active content provider for a content
 135         identifier.
 136
 137         @param Identifier
 138         a content identifier (i.e., a URL).
 139
 140         @returns
 141         a content provider, or null.
 142     */
 143     com::sun::star::ucb::XContentProvider queryContentProvider(
 144                 [in] string Identifier );
 145 };
 146
 147
 148 }; }; }; };
 149
 150 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */