/*************************************************************************
 *
 *  OpenOffice.org - a multi-platform office productivity suite
 *
 *  $RCSfile: XContentProviderManager.idl,v $
 *
 *  $Revision: 1.13 $
 *
 *  last change: $Author: rt $ $Date: 2005/09/08 08:05:00 $
 *
 *  The Contents of this file are made available subject to
 *  the terms of GNU Lesser General Public License Version 2.1.
 *
 *
 *    GNU Lesser General Public License Version 2.1
 *    =============================================
 *    Copyright 2005 by Sun Microsystems, Inc.
 *    901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License version 2.1, as published by the Free Software Foundation.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 *
 *    You should have received a copy of the GNU Lesser General Public
 *    License along with this library; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *    MA  02111-1307  USA
 *
 ************************************************************************/
#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 = &lt any UTF-16 character except " or \></code></li>
		<li><code>sescape = "\" (DQUOTE / "\")</code></li>
		</ul>

		<p>A <code>&lt;scheme&gt:</code> matches any URL of exactly the given
	    scheme (ignoring case),	keeping the extension from URL schemes to URL
	    templates backwards	compatible.  The <code>&lt;simple&gt:</code>
	    regexps match any URL starting with a given	string literal, followed
	    by arbitrary characters (<code>&lt;simple-prefix&gt:</code>), or
		by arbitrary characters that start with one of '/', '?', or '#', if any
		(<code>&lt;simple-authority&gt:</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>&lt;translation&gt:</code> regexps
	    match the same URLs as their <code>&lt;simple&gt:</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>&lt;translation&gt:</code> regexps have the same semantics
	    as their <code>&lt;simple&gt:</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
