| /************************************************************** |
| * |
| * 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 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| * |
| *************************************************************/ |
| |
| |
| #ifndef __com_sun_star_ucb_XContentProviderManager_idl__ |
| #define __com_sun_star_ucb_XContentProviderManager_idl__ |
| |
| #ifndef __com_sun_star_uno_XInterface_idl__ |
| #include <com/sun/star/uno/XInterface.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_XContentProvider_idl__ |
| #include <com/sun/star/ucb/XContentProvider.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_DuplicateProviderException_idl__ |
| #include <com/sun/star/ucb/DuplicateProviderException.idl> |
| #endif |
| |
| #ifndef __com_sun_star_ucb_ContentProviderInfo_idl__ |
| #include <com/sun/star/ucb/ContentProviderInfo.idl> |
| #endif |
| |
| |
| //============================================================================= |
| |
| module com { module sun { module star { module ucb { |
| |
| //============================================================================= |
| /** makes it possible to query/register/deregister content providers. |
| |
| @version 1.0 |
| @author Kai Sommerfeld |
| @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 |
| <member>XContentProvider::queryContent</member> with an |
| <type>XContentIdentifier</type> 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 = < any UTF-16 character except " or \></code></li> |
| <li><code>sescape = "\" (DQUOTE / "\")</code></li> |
| </ul> |
| |
| <p>A <code><scheme>:</code> matches any URL of exactly the given |
| scheme (ignoring case), keeping the extension from URL schemes to URL |
| templates backwards compatible. The <code><simple>:</code> |
| regexps match any URL starting with a given string literal, followed |
| by arbitrary characters (<code><simple-prefix>:</code>), or |
| by arbitrary characters that start with one of '/', '?', or '#', if any |
| (<code><simple-authority>:</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 comparision of string literals is done ignoring the |
| case of ASCII letters. The <code><translation>:</code> regexps |
| match the same URLs as their <code><simple>:</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 |
| <type>RemoteAccessContentProvider</type>'s |
| <type>XParameterizedContentProvider</type> interface; in all other |
| cases, <code><translation>:</code> regexps have the same semantics |
| as their <code><simple>:</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 |
| <member>registerContentProvider</member> for a discussion of URL |
| templates). |
| */ |
| [oneway] 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. |
| */ |
| com::sun::star::ucb::XContentProvider queryContentProvider( |
| [in] string Identifier ); |
| }; |
| |
| //============================================================================= |
| |
| }; }; }; }; |
| |
| #endif |