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