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

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