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 = &lt any UTF-16 character except " or \></code></li>
99		<li><code>sescape = "\" (DQUOTE / "\")</code></li>
100		</ul>
101
102		<p>A <code>&lt;scheme&gt:</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>&lt;simple&gt:</code>
105	    regexps match any URL starting with a given	string literal, followed
106	    by arbitrary characters (<code>&lt;simple-prefix&gt:</code>), or
107		by arbitrary characters that start with one of '/', '?', or '#', if any
108		(<code>&lt;simple-authority&gt:</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>&lt;translation&gt:</code> regexps
113	    match the same URLs as their <code>&lt;simple&gt:</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>&lt;translation&gt:</code> regexps have the same semantics
119	    as their <code>&lt;simple&gt:</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