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 #ifndef __com_sun_star_ucb_XContentProviderManager_idl__
  20 #define __com_sun_star_ucb_XContentProviderManager_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/ucb/XContentProvider.idl>
  24 #include <com/sun/star/ucb/DuplicateProviderException.idl>
  25 #include <com/sun/star/ucb/ContentProviderInfo.idl>
  26
  27
  28
  29 module com { module sun { module star { module ucb {
  30
  31 /** makes it possible to query/register/deregister content providers.
  32
  33     @version  1.0
  34     @author   Kai Sommerfeld
  35     @see      XContentProvider
  36 */
  37 published interface XContentProviderManager: com::sun::star::uno::XInterface
  38 {
  39     /** registers a content provider for a specific URL template.
  40
  41         @see XContentIdentifier
  42
  43         @param Provider
  44         the content provider to register.
  45
  46         <p>This may be `NULL`, in which case a later
  47         XContentProvider::queryContent() with an
  48         XContentIdentifier that matches the <var>Scheme</var>
  49         will simply return `NULL`. These "dummy" content providers are useful
  50         in combination with other content providers that are registered on a
  51         wildcard URL template: For example, imagine that you want to route all
  52         http URLs to a HTTP content provider, but want to block all URLs for
  53         the server <code>www.dont.go</code>. One solution would be to register
  54         the HTTP content provider on the <var>Scheme</var> <code>http</code>,
  55         and to register a "dummy" (i.e., `NULL`) content provider on the
  56         <var>Scheme</var> <code>"http://www.dont.go"([/?#].*)?</code>.
  57
  58         @param Scheme
  59         the URL scheme for the provided contents. More generally, this may not
  60         only be a URL scheme, but a URL template.
  61
  62         <p>A URL template is a regular expression (represented as a string) that
  63         specifies a subset of the set of all possible URLs (this subset
  64         consists of exactly those URLs that match the regular expression).  The
  65         language to denote the regular expressions is initially quite limited,
  66         but it may be extended in the future:
  67
  68         <p><ul>
  69         <li><code>regexp = scheme / simple / translation</code></li>
  70         <li><code>scheme = ALPHA *(ALPHA / DIGIT / "+" / "-" / ".")</code></li>
  71         <li><code>simple = simple-prefix / simple-authority / simple-domain</code></li>
  72         <li><code>translation = trans-prefix / trans-authority / trans-domain</code></li>
  73         <li><code>simple-prefix = [string] ".*"</code></li>
  74         <li><code>trans-prefix = [string] "(.*)->" [string] "\1"</code></li>
  75         <li><code>simple-authority = [string] "([/?#].*)?"</code></li>
  76         <li><code>trans-authority = [string] "(([/?#].*)?)->" string "\1"</code></li>
  77         <li><code>simple-domain = [string] "[^/?#]*" string "([/?#].*)?"</code></li>
  78         <li><code>trans-domain = [string] "([^/?#]*" string "([/?#].*)?)->" string "\1"</code></li>
  79         <li><code>string = DQUOTE 1*(schar / sescape) DQUOTE  ; DQUOTE is "</code></li>
  80         <li><code>schar = &lt any UTF-16 character except " or \></code></li>
  81         <li><code>sescape = "\" (DQUOTE / "\")</code></li>
  82         </ul>
  83
  84         <p>A <code>&lt;scheme&gt:</code> matches any URL of exactly the given
  85         scheme (ignoring case), keeping the extension from URL schemes to URL
  86         templates backwards compatible.  The <code>&lt;simple&gt:</code>
  87         regexps match any URL starting with a given string literal, followed
  88         by arbitrary characters (<code>&lt;simple-prefix&gt:</code>), or
  89         by arbitrary characters that start with one of '/', '?', or '#', if any
  90         (<code>&lt;simple-authority&gt:</code>), or by arbitrary characters not
  91         including any of '/', '?', or '#', followed by a given string literal,
  92         followed by arbitrary characters that start with one of '/', '?', or
  93         '#', if any. The comparison of string literals is done ignoring the
  94         case of ASCII letters.  The <code>&lt;translation&gt:</code> regexps
  95         match the same URLs as their <code>&lt;simple&gt:</code> counterparts,
  96         but they also describe how a (local) URL is mapped to another (remote)
  97         URL.  This mapping is only relevant for methods of the
  98         RemoteAccessContentProvider's
  99           XParameterizedContentProvider interface; in all other
 100         cases, <code>&lt;translation&gt:</code> regexps have the same semantics
 101         as their <code>&lt;simple&gt:</code> counterparts.
 102
 103         @param ReplaceExisting
 104         `TRUE`: replace the provider possibly registered for the given URL
 105         template. The replaced provider will not be deregistered automatically!
 106         If the superseding provider gets deregistered, the superseded one will
 107         become active again.
 108         <p>`FALSE`: do not register, if another provider is already registered
 109         for the given URL template.
 110
 111         @returns
 112         the replaced content provider, if there was one.
 113     */
 114     com::sun::star::ucb::XContentProvider registerContentProvider(
 115                 [in] com::sun::star::ucb::XContentProvider Provider,
 116                 [in] string Scheme,
 117                 [in] boolean ReplaceExisting )
 118         raises( com::sun::star::ucb::DuplicateProviderException );
 119
 120     /** deregisters a content provider.
 121
 122         @param Provider
 123         a content provider to deregister.
 124
 125         @param Scheme
 126         the URL scheme for the provided contents. More generally, this
 127         may not only be a URL scheme, but a URL template (see
 128         registerContentProvider() for a discussion of URL
 129         templates).
 130     */
 131     void deregisterContentProvider(
 132                 [in] com::sun::star::ucb::XContentProvider Provider,
 133                  [in] string Scheme );
 134
 135     /** returns a list of information on all registered content providers.
 136
 137         @returns
 138         a list information on content providers.
 139     */
 140     sequence<com::sun::star::ucb::ContentProviderInfo> queryContentProviders();
 141
 142     /** returns the currently active content provider for a content
 143         identifier.
 144
 145         @param Identifier
 146         a content identifier (i.e., a URL).
 147
 148         @returns
 149         a content provider, or null.
 150     */
 151     com::sun::star::ucb::XContentProvider queryContentProvider(
 152                 [in] string Identifier );
 153 };
 154
 155
 156 }; }; }; };
 157
 158 #endif
 159
 160 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */