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
24#if ! defined INCLUDED_com_sun_star_deployment_XExtensionManager_idl
25#define INCLUDED_com_sun_star_deployment_XExtensionManager_idl
26
27#include <com/sun/star/lang/XComponent.idl>
28#include <com/sun/star/task/XAbortChannel.idl>
29#include <com/sun/star/util/XModifyBroadcaster.idl>
30#include <com/sun/star/deployment/XPackage.idl>
31#include <com/sun/star/deployment/XPackageTypeInfo.idl>
32#include <com/sun/star/ucb/XCommandEnvironment.idl>
33#include <com/sun/star/deployment/DeploymentException.idl>
34#include <com/sun/star/container/NoSuchElementException.idl>
35#include <com/sun/star/lang/IllegalArgumentException.idl>
36#include <com/sun/star/beans/NamedValue.idl>
37
38module com { module sun { module star { module deployment {
39
40/** The <type>XExtensionManager</type> interface is used to manage extensions
41    in the user, shared and bundled repository.
42
43    @see ExtensionManager
44    @since OpenOffice 3.3
45*/
46interface XExtensionManager
47{
48    /** interface to notify disposing
49     */
50    interface com::sun::star::lang::XComponent;
51
52    /** interface to notify changes of the set of deployed packages of
53        this manager
54    */
55    interface com::sun::star::util::XModifyBroadcaster;
56
57
58    /** gets the supported <type>XPackageTypeInfo</type>s.
59
60        @return
61                supported <type>XPackageTypeInfo</type>s.
62    */
63    sequence<XPackageTypeInfo> getSupportedPackageTypes();
64
65    /** creates a command channel to be used to asynchronously abort a command.
66
67        @return
68                abort channel
69    */
70    com::sun::star::task::XAbortChannel createAbortChannel();
71
72    /** adds an extension.
73
74        The properties argument is currently only used to suppress the license information
75        for shared extensions.
76
77        @param url
78               package URL, must be UCB conform
79        @param properties
80               additional properties, for example, that the license is to be
81               suppressed (if supported by the extension)
82        @param repository
83               the name of the repository
84        @param xAbortChannel
85               abort channel to asynchronously abort the adding process,
86               or null
87        @param xCmdEnv
88               command environment for error and progress handling
89        @return
90               object representing the extension.
91    */
92    XPackage addExtension( [in] string url,
93                           [in] sequence<com::sun::star::beans::NamedValue> properties,
94                           [in] string repository,
95                           [in] com::sun::star::task::XAbortChannel xAbortChannel,
96                           [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
97        raises (DeploymentException,
98                com::sun::star::ucb::CommandFailedException,
99                com::sun::star::ucb::CommandAbortedException,
100                com::sun::star::lang::IllegalArgumentException);
101
102    /** removes an extension.
103
104        @param identifier
105               package identifier
106        @param fileName
107               package file name
108        @param repository
109               the name of the repository
110        @param xAbortChannel
111               abort channel to asynchronously abort the removing process,
112               or null
113        @param xCmdEnv
114               command environment for error and progress handling
115    */
116    void removeExtension(
117        [in] string identifier,
118        [in] string fileName,
119        [in] string repository,
120        [in] com::sun::star::task::XAbortChannel xAbortChannel,
121        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
122        raises (DeploymentException,
123                com::sun::star::ucb::CommandFailedException,
124                com::sun::star::ucb::CommandAbortedException,
125                com::sun::star::lang::IllegalArgumentException);
126
127
128    /** enable an extension.
129
130        If the extension is not from the user repository then an
131        IllegalArgumentException is thrown.
132
133        @param extension
134               the extension which is to be enabled.
135        @param xAbortChannel
136               abort channel to asynchronously abort the removing process,
137               or null
138        @param xCmdEnv
139               command environment for error and progress handling
140    */
141    void enableExtension(
142        [in] XPackage extension,
143        [in] com::sun::star::task::XAbortChannel xAbortChannel,
144        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
145        raises (DeploymentException,
146                com::sun::star::ucb::CommandFailedException,
147                com::sun::star::ucb::CommandAbortedException,
148                com::sun::star::lang::IllegalArgumentException);
149
150    /** disable an extension.
151
152        If the extension is not from the user repository then an
153        IllegalArgumentException is thrown.
154
155        @param extension
156               the extension which is to be disabled
157        @param xAbortChannel
158               abort channel to asynchronously abort the removing process,
159               or null
160        @param xCmdEnv
161               command environment for error and progress handling
162     */
163    void  disableExtension(
164        [in] XPackage extension,
165        [in] com::sun::star::task::XAbortChannel xAbortChannel,
166        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
167        raises (DeploymentException,
168                com::sun::star::ucb::CommandFailedException,
169                com::sun::star::ucb::CommandAbortedException,
170                com::sun::star::lang::IllegalArgumentException);
171
172    /** gets all currently installed extensions, including disabled
173        user extensions.
174
175        @param repository
176               the repository from which the extensions are returned
177        @param xAbortChannel
178               abort channel to asynchronously abort the removing process,
179               or null
180        @param xCmdEnv
181               command environment for error and progress handling
182        @return
183               all currently installed packages
184    */
185    sequence<XPackage> getDeployedExtensions(
186        [in] string repository,
187        [in] com::sun::star::task::XAbortChannel xAbortChannel,
188        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
189        raises (DeploymentException,
190                com::sun::star::ucb::CommandFailedException,
191                com::sun::star::ucb::CommandAbortedException,
192                com::sun::star::lang::IllegalArgumentException);
193
194
195    /** gets an installed extensions.
196
197        @param repository
198               the name of the repository
199        @param identifier
200               extension identifier
201        @param fileName
202               extension file name
203        @param xCmdEnv
204               command environment for error and progress handling
205        @return
206               <type>XPackage</type> object
207    */
208    XPackage getDeployedExtension(
209        [in] string repository,
210        [in] string identifier,
211        [in] string fileName,
212        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
213        raises (DeploymentException,
214                com::sun::star::ucb::CommandFailedException,
215                com::sun::star::lang::IllegalArgumentException);
216
217    /** gets all extensions with the same identifier from all repositories.
218
219        The extension at the first position in the returned sequence represents
220        the extension from the user repository. The next element is from the shared
221        and the last one is from the bundled repository.
222        If one repository does not contain this extension, then the respective
223        element is a null reference.
224    */
225    sequence<XPackage> getExtensionsWithSameIdentifier(
226        [in] string identifier,
227        [in] string fileName,
228        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
229        raises (DeploymentException,
230                com::sun::star::ucb::CommandFailedException,
231                com::sun::star::lang::IllegalArgumentException);
232
233
234    /** returns a sequence containing all installed extensions.
235
236        The members of the returned sequence correspond to an extension with a
237        particular extension identifier. The members are also sequences which
238        contain as many elements as there are repositories. Those are ordered
239        according to the priority of the repository. That is, the first member
240        is the extension from the user repository, the second is from the shared
241        repository and the last is from the bundled repository.
242     */
243    sequence<sequence<XPackage> > getAllExtensions(
244        [in] com::sun::star::task::XAbortChannel xAbortChannel,
245        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
246        raises (DeploymentException,
247                com::sun::star::ucb::CommandFailedException,
248                com::sun::star::ucb::CommandAbortedException,
249                com::sun::star::lang::IllegalArgumentException);
250
251
252    /** Expert feature: erases the underlying registry cache and reinstalls
253        all previously added extensions.  Please keep in mind that all
254        registration status get lost.
255        <p>
256        Please use this in case of suspected cache inconsistencies only.
257        </p>
258        @param repository
259               the name of the repository
260        @param xAbortChannel
261               abort channel to asynchronously abort the adding process
262        @param xCmdEnv
263               command environment for error and progress handling
264    */
265    void reinstallDeployedExtensions(
266        [in] string repository,
267        [in] com::sun::star::task::XAbortChannel xAbortChannel,
268        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
269        raises (DeploymentException,
270                com::sun::star::ucb::CommandFailedException,
271                com::sun::star::ucb::CommandAbortedException,
272                com::sun::star::lang::IllegalArgumentException);
273
274
275    /** synchronizes the extension database with the contents of the extensions
276       folder of shared and bundled extensions.
277
278       Added extensions will be added to the database and removed extensions
279       will be removed from the database.
280       The active extensions are determined. That is, shared or bundled extensions
281       are not necessarily registered (<member>XPackage::registerPackage</member>).
282
283       @return
284              If true - then at least one extension was removed or added. Otherwise
285              nothing was changed.
286    */
287    boolean synchronize(
288        [in] com::sun::star::task::XAbortChannel xAbortChannel,
289        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
290        raises (DeploymentException,
291                com::sun::star::ucb::CommandFailedException,
292                com::sun::star::ucb::CommandAbortedException,
293                com::sun::star::lang::IllegalArgumentException);
294
295
296    /** synchronizes the special bundled_prereg repository, which is based on
297       the bundled extensions and has its registration data folder at
298       $BUNDLED_EXTENSIONS_PREREG (for example openoffice.org3/share/prereg).
299
300       All bundled extensions are registered (<member>XPackage::registerPackage</member>).
301       The active extensions are NOT determined, because this function only works
302       with bundled extensions.
303
304       This function is intended to be called during the installation of AOO.
305       OpenOffice will copy parts of the registration data folder to the user installation at the
306       first startup.
307    */
308
309    void synchronizeBundledPrereg(
310        [in] com::sun::star::task::XAbortChannel xAbortChannel,
311        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
312        raises (DeploymentException);
313
314
315    /** returns all extensions which are currently not in use
316        because the user did not accept the license.
317
318        The function will not return any object for the user repository, because
319        a user extension will not be kept in the user repository if its license
320        is declined. Only extensions which are registered at start-up of AOO,
321        that is, shared and bundled extensions, can be returned.
322
323        Extensions which allow the license to be suppressed, that is, it does not
324        need to be displayed, and which are installed with the corresponding option,
325        are also not returned.
326
327        Extensions returned by this functions are not returned by
328        <member>XExtensionManger::getDeployedExtension</member>
329        <member>XExtensionManger::getDeployedExtensions</member>
330        <member>XExtensionManger::getAllExtensions</member>
331        <member>XExtensionManger::getExtensionsWithSameIdentifier</member>
332    */
333    sequence<XPackage> getExtensionsWithUnacceptedLicenses(
334        [in] string repository,
335        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
336        raises (DeploymentException,
337                com::sun::star::lang::IllegalArgumentException);
338
339    /** check if all prerequisites for the extension are fulfilled
340        and activates it, if possible.
341    */
342    long checkPrerequisitesAndEnable(
343        [in] XPackage extension,
344        [in] com::sun::star::task::XAbortChannel xAbortChannel,
345        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
346        raises (DeploymentException,
347                com::sun::star::ucb::CommandFailedException,
348                com::sun::star::ucb::CommandAbortedException,
349                com::sun::star::lang::IllegalArgumentException);
350
351    /** determines if the current user has write access to the extensions folder
352        of the repository.
353    */
354    boolean isReadOnlyRepository([in] string repository);
355};
356
357}; }; }; };
358
359#endif
360