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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_ucb_XContentProviderManager_idl__
  28 #define __com_sun_star_ucb_XContentProviderManager_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33
  34 #ifndef __com_sun_star_ucb_XContentProvider_idl__
  35 #include <com/sun/star/ucb/XContentProvider.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_ucb_DuplicateProviderException_idl__
  39 #include <com/sun/star/ucb/DuplicateProviderException.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_ucb_ContentProviderInfo_idl__
  43 #include <com/sun/star/ucb/ContentProviderInfo.idl>
  44 #endif
  45
  46
  47 //=============================================================================
  48
  49 module com { module sun { module star { module ucb {
  50
  51 //=============================================================================
  52 /** makes it possible to query/register/deregister content providers.
  53
  54     @version  1.0
  55     @author   Kai Sommerfeld
  56     @see      XContentProvider
  57 */
  58 published interface XContentProviderManager: com::sun::star::uno::XInterface
  59 {
  60     //-------------------------------------------------------------------------
  61     /** registers a content provider for a specific URL template.
  62
  63         @see XContentIdentifier
  64
  65         @param Provider
  66         the content provider to register.
  67
  68         <p>This may be <NULL/>, in which case a later
  69         <member>XContentProvider::queryContent</member> with an
  70         <type>XContentIdentifier</type> that matches the <var>Scheme</var>
  71         will simply return <NULL/>. These "dummy" content providers are useful
  72         in combination with other content providers that are registered on a
  73         wildcard URL template: For example, imagine that you want to route all
  74         http URLs to a HTTP content provider, but want to block all URLs for
  75         the server <code>www.dont.go</code>. One solution would be to register
  76         the HTTP content provider on the <var>Scheme</var> <code>http</code>,
  77         and to register a "dummy" (i.e., <NULL/>) content provider on the
  78         <var>Scheme</var> <code>"http://www.dont.go"([/?#].*)?</code>.
  79
  80         @param Scheme
  81         the URL scheme for the provided contents. More generally, this may not
  82         only be a URL scheme, but a URL template.
  83
  84         <p>A URL template is a regular expression (represented as a string) that
  85         specifies a subset of the set of all possible URLs (this subset
  86         consists of exactly those URLs that match the regular expression).  The
  87         language to denote the regular expressions is initially quite limited,
  88         but it may be extended in the future:
  89
  90         <p><ul>
  91         <li><code>regexp = scheme / simple / translation</code></li>
  92         <li><code>scheme = ALPHA *(ALPHA / DIGIT / "+" / "-" / ".")</code></li>
  93         <li><code>simple = simple-prefix / simple-authority / simple-domain</code></li>
  94         <li><code>translation = trans-prefix / trans-authority / trans-domain</code></li>
  95         <li><code>simple-prefix = [string] ".*"</code></li>
  96         <li><code>trans-prefix = [string] "(.*)->" [string] "\1"</code></li>
  97         <li><code>simple-authority = [string] "([/?#].*)?"</code></li>
  98         <li><code>trans-authority = [string] "(([/?#].*)?)->" string "\1"</code></li>
  99         <li><code>simple-domain = [string] "[^/?#]*" string "([/?#].*)?"</code></li>
 100         <li><code>trans-domain = [string] "([^/?#]*" string "([/?#].*)?)->" string "\1"</code></li>
 101         <li><code>string = DQUOTE 1*(schar / sescape) DQUOTE  ; DQUOTE is "</code></li>
 102         <li><code>schar = &lt any UTF-16 character except " or \></code></li>
 103         <li><code>sescape = "\" (DQUOTE / "\")</code></li>
 104         </ul>
 105
 106         <p>A <code>&lt;scheme&gt:</code> matches any URL of exactly the given
 107         scheme (ignoring case), keeping the extension from URL schemes to URL
 108         templates backwards compatible.  The <code>&lt;simple&gt:</code>
 109         regexps match any URL starting with a given string literal, followed
 110         by arbitrary characters (<code>&lt;simple-prefix&gt:</code>), or
 111         by arbitrary characters that start with one of '/', '?', or '#', if any
 112         (<code>&lt;simple-authority&gt:</code>), or by arbitrary characters not
 113         including any of '/', '?', or '#', followed by a given string literal,
 114         followed by arbitrary characters that start with one of '/', '?', or
 115         '#', if any. The comparision of string literals is done ignoring the
 116         case of ASCII letters.  The <code>&lt;translation&gt:</code> regexps
 117         match the same URLs as their <code>&lt;simple&gt:</code> counterparts,
 118         but they also describe how a (local) URL is mapped to another (remote)
 119         URL.  This mapping is only relevant for methods of the
 120         <type>RemoteAccessContentProvider</type>'s
 121           <type>XParameterizedContentProvider</type> interface; in all other
 122         cases, <code>&lt;translation&gt:</code> regexps have the same semantics
 123         as their <code>&lt;simple&gt:</code> counterparts.
 124
 125         @param ReplaceExisting
 126         <TRUE/>: replace the provider possibly registered for the given URL
 127         template. The replaced provider will not be deregistered automatically!
 128         If the superseding provider gets deregistered, the superseded one will
 129         become active again.
 130         <p><FALSE/>: do not register, if another provider is already registered
 131         for the given URL template.
 132
 133         @returns
 134         the replaced content provider, if there was one.
 135     */
 136     com::sun::star::ucb::XContentProvider registerContentProvider(
 137                 [in] com::sun::star::ucb::XContentProvider Provider,
 138                 [in] string Scheme,
 139                 [in] boolean ReplaceExisting )
 140         raises( com::sun::star::ucb::DuplicateProviderException );
 141
 142     //-------------------------------------------------------------------------
 143     /** deregisters a content provider.
 144
 145         @param Provider
 146         a content provider to deregister.
 147
 148         @param Scheme
 149         the URL scheme for the provided contents. More generally, this
 150         may not only be a URL scheme, but a URL template (see
 151         <member>registerContentProvider</member> for a discussion of URL
 152         templates).
 153     */
 154     [oneway] void deregisterContentProvider(
 155                 [in] com::sun::star::ucb::XContentProvider Provider,
 156                  [in] string Scheme );
 157
 158     //-------------------------------------------------------------------------
 159     /** returns a list of information on all registered content providers.
 160
 161         @returns
 162         a list information on content providers.
 163     */
 164     sequence<com::sun::star::ucb::ContentProviderInfo> queryContentProviders();
 165
 166     //-------------------------------------------------------------------------
 167     /** returns the currently active content provider for a content
 168         identifier.
 169
 170         @param Identifier
 171         a content identifier (i.e., a URL).
 172
 173         @returns
 174         a content provider.
 175     */
 176     com::sun::star::ucb::XContentProvider queryContentProvider(
 177                 [in] string Identifier );
 178 };
 179
 180 //=============================================================================
 181
 182 }; }; }; };
 183
 184 #endif