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