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