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_UniversalContentBroker_idl__
24#define __com_sun_star_ucb_UniversalContentBroker_idl__
25
26#ifndef __com_sun_star_lang_XComponent_idl__
27#include <com/sun/star/lang/XComponent.idl>
28#endif
29
30#ifndef __com_sun_star_ucb_XCommandProcessor_idl__
31#include <com/sun/star/ucb/XCommandProcessor.idl>
32#endif
33
34#ifndef __com_sun_star_ucb_XCommandProcessor2_idl__
35#include <com/sun/star/ucb/XCommandProcessor2.idl>
36#endif
37
38#ifndef __com_sun_star_ucb_XContentProviderManager_idl__
39#include <com/sun/star/ucb/XContentProviderManager.idl>
40#endif
41
42#ifndef __com_sun_star_ucb_XContentProvider_idl__
43#include <com/sun/star/ucb/XContentProvider.idl>
44#endif
45
46#ifndef __com_sun_star_ucb_XContentIdentifierFactory_idl__
47#include <com/sun/star/ucb/XContentIdentifierFactory.idl>
48#endif
49
50#ifndef __com_sun_star_lang_XInitialization_idl__
51#include <com/sun/star/lang/XInitialization.idl>
52#endif
53
54//=============================================================================
55
56module com { module sun { module star { module ucb {
57
58//=============================================================================
59/** is a one-instance service that provides access to a set of
60    <type>Content</type>s via <type>ContentProvider</type>s.
61
62	<p>If the instance is created with two arguments of type string,
63	these two strings are used to configure the newly instantiated broker;
64	see the description of the required
65	<type scope="com::sun::star::lang">XInitialization</type> interface for
66	details.
67
68	<p>If the instance is created without arguments, the newly instatiated
69    broker is not configured.
70*/
71published service UniversalContentBroker
72{
73	//-------------------------------------------------------------------------
74	/** must be implemented to make it possible to resolve cyclic object
75	    references.
76
77		<p>Those references i.e. may occur if content provider	implementations
78		hold references to the Broker. The Broker itself always holds its
79		providers. If the Broker shall be released,
80		<member scope="com::sun::star::lang">XComponent::dispose</member>
81		must be called at the Broker. The implementation of this method must
82		call
83		<member scope="com::sun::star::lang">XEventListener::disposing</member>
84		on the registered listeners	(the providers holding the Broker must be
85		those listeners) and release the appropriate object references. At
86		the other hand, the	implementation of XEventListener::disposing must
87		release its appropriate references.
88
89		<p>This interface is required.
90	 */
91	interface com::sun::star::lang::XComponent;
92
93	//-------------------------------------------------------------------------
94	/** provides access to all kind of contents provided by the registered
95		content providers.
96
97		<p>This interface is required.
98	 */
99	interface com::sun::star::ucb::XContentProvider;
100
101	//-------------------------------------------------------------------------
102	/** provides access to a set of content providers registered with the UCB.
103
104		<p>This interface is required.
105	 */
106	interface com::sun::star::ucb::XContentProviderManager;
107
108	//-------------------------------------------------------------------------
109	/** creates <type>XContentIdentifier</type> implementation objects for
110	    all kind of contents provided by the UCB.
111
112		<p>This interface is required.
113	  */
114	interface com::sun::star::ucb::XContentIdentifierFactory;
115
116	//-------------------------------------------------------------------------
117	/**	supports the configuration of a newly created broker.
118
119		<p>The
120		<member scope="com::sun::star::lang">XInitialization::initialize</member>
121		method should be called with two arguments of type string. These strings
122		are used as a pair of keys to retrieve a set of content provider
123		descriptions from the configuration	management (stored at
124		<code>org.openoffice.ucb.Configuration.ContentProviders.<var>key<sub>1</sub></var>.SecondaryKeys.<var>key<sub>2</sub></var>.ProviderData</code>
125		within the configuration management's hierarchy). The retrieved
126		descriptions are in turn used to register the corresponding content
127		provider services at the broker.
128
129		<p>Typical values for the pair of strings would be
130		<code>"Local"</code>/<code>"Office"</code>, to configure a broker that
131		contains all the relevant content providers.
132
133		<p>This interface is required.
134	 */
135	interface com::sun::star::lang::XInitialization;
136
137	//-------------------------------------------------------------------------
138	/**	enables the caller to execute commands at the broker.
139
140		<p>This interface is required.
141
142		<p><pre>
143		=======================================================================
144		Commands:
145		=======================================================================
146
147		[return type]
148			[command name]
149				[parameter type and name]
150
151		-----------------------------------------------------------------------
152		Requiered commands:
153		-----------------------------------------------------------------------
154
155		// This command obtains an interface which allows to query
156		// information on commands supported by the Content Broker.
157
158		<type>XCommandInfo</type>
159			getCommandInfo
160				void
161
162		// This command transfers Contents from one location to another.
163		// Additionally, it can be used to create a link to a Content.
164		// The implementation must be able to handle Contents provided
165		// by any Content Provider. This is different from the command
166		// 'transfer' that can be supported by a Content. That command
167		// typically can only handle <type>Content</type>s provided by one
168		// <type>ContentProvider</type>.
169
170		void
171			globalTransfer
172				<type>GlobalTransferCommandArgument</type>
173		</pre>
174	 */
175    interface com::sun::star::ucb::XCommandProcessor;
176
177    //-------------------------------------------------------------------------
178    /** is an enhanced version of <type>XCommandProcessor</type> that has an
179        additional method for releasing command identifiers obtained via
180        <member>XCommandProcessor::createCommandIdentifier</member> to avoid
181        resource leaks. For a detailed description of the problem refer to
182        <member>XCommandProcessor2::releaseCommandIdentifier</member>.
183
184        <p>Where many existing <type>UniversalContentBroker</type>
185        implementations do not (yet), every new implementation should support
186        this interface.
187     */
188    [optional] interface com::sun::star::ucb::XCommandProcessor2;
189
190};
191
192//=============================================================================
193
194}; }; }; };
195
196#endif
197