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_XPackageManager_idl
29#define INCLUDED_com_sun_star_deployment_XPackageManager_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
42
43module com { module sun { module star { module deployment {
44
45/** The <type>XPackageManager</type> interface is used to add or remove
46    packages to a specific repository. This interface represents a particular
47    repository.
48    Packages are deployable files, e.g. scripts or UNO components.
49    <p>
50    Adding an UNO package means that a copy of the package is stored
51    in the repository.
52    </p>
53    <p>
54    Removing an UNO package means that the previously added package is
55    removed from the repository.
56    </p>
57    <p>
58    All interface methods do neither register nor revoke an extension.
59    This happens exclusively by <type>XExtensionManager</type>.
60    </p>
61    <p>
62    Objects of this interface are created using the
63    <type>XPackageManagerFactory</type> service resp. the singleton
64    <code>
65    /singletons/com.sun.star.deployment.thePackageManagerFactory
66    </code>.
67    </p>
68
69    @see thePackageManagerFactory
70    @since OOo 2.0
71    @deprecated
72         Use <type>XExtensionManager</type>.
73*/
74interface XPackageManager
75{
76    /** interface to notify disposing
77     */
78    interface com::sun::star::lang::XComponent;
79
80    /** interface to notify changes of the set of deployed packages of
81        this manager
82    */
83    interface com::sun::star::util::XModifyBroadcaster;
84
85    /** returns the underlying deployment context, that is,
86        the name of the repository..
87
88        @return
89                underlying deployment context
90    */
91    string getContext();
92
93    /** gets the supported <type>XPackageTypeInfo</type>s.
94
95        @return
96                supported <type>XPackageTypeInfo</type>s.
97    */
98    sequence<XPackageTypeInfo> getSupportedPackageTypes();
99
100    /** creates a command channel to be used to asynchronously abort a command.
101
102        @return
103                abort channel
104    */
105    com::sun::star::task::XAbortChannel createAbortChannel();
106
107    /** adds an UNO package.
108
109        The properties argument is currently only used to suppress the license information
110        for shared extensions.
111
112
113        @param url
114               package URL, must be UCB conform
115        @param properties
116               additional properties, for example, that the license is to be
117               suppressed (if supported by the extension)
118        @param mediaType
119               media-type of package, empty string if to be detected
120        @param xAbortChannel
121               abort channel to asynchronously abort the adding process,
122               or null
123        @param xCmdEnv
124               command environment for error and progress handling
125        @return
126               <type>XPackage</type> handle
127    */
128    XPackage addPackage( [in] string url,
129                         [in] sequence<com::sun::star::beans::NamedValue> properties,
130                         [in] string mediaType,
131                         [in] com::sun::star::task::XAbortChannel xAbortChannel,
132                         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
133        raises (DeploymentException,
134                com::sun::star::ucb::CommandFailedException,
135                com::sun::star::ucb::CommandAbortedException,
136                com::sun::star::lang::IllegalArgumentException);
137
138    /** adds an extension.
139
140        This copies the extension. If it was from the same repository,
141        which is represented by this XPackageManager insterface, then
142        nothing happens.
143
144        @param extension
145
146        @param xAbortChannel
147               abort channel to asynchronously abort the adding process,
148               or null
149        @param xCmdEnv
150               command environment for error and progress handling
151        @return
152               <type>XPackage</type> handle
153    */
154    XPackage importExtension( [in] XPackage extension,
155                         [in] com::sun::star::task::XAbortChannel xAbortChannel,
156                         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
157        raises (DeploymentException,
158                com::sun::star::ucb::CommandFailedException,
159                com::sun::star::ucb::CommandAbortedException,
160                com::sun::star::lang::IllegalArgumentException);
161
162    /** removes an UNO package.
163
164        @param identifier
165               package identifier
166        @param fileName
167               package file name
168        @param xAbortChannel
169               abort channel to asynchronously abort the removing process,
170               or null
171        @param xCmdEnv
172               command environment for error and progress handling
173    */
174    void removePackage( [in] string identifier,
175                        [in] string fileName,
176                        [in] com::sun::star::task::XAbortChannel xAbortChannel,
177                        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
178        raises (DeploymentException,
179                com::sun::star::ucb::CommandFailedException,
180                com::sun::star::ucb::CommandAbortedException,
181                com::sun::star::lang::IllegalArgumentException);
182
183    /** gets a deployed package.
184
185        @param identifier
186               package identifier
187        @param fileName
188               package file name
189        @param xCmdEnv
190               command environment for error and progress handling
191        @return
192               <type>XPackage</type> handle
193    */
194    XPackage getDeployedPackage(
195        [in] string identifier,
196        [in] string fileName,
197        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
198        raises (DeploymentException,
199                com::sun::star::ucb::CommandFailedException,
200                com::sun::star::lang::IllegalArgumentException);
201
202    /** gets all currently deployed packages.
203
204        @param xAbortChannel
205               abort channel to asynchronously abort the removing process,
206               or null
207        @param xCmdEnv
208               command environment for error and progress handling
209        @return
210                all currently deployed packages
211    */
212    sequence<XPackage> getDeployedPackages(
213        [in] com::sun::star::task::XAbortChannel xAbortChannel,
214        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
215        raises (DeploymentException,
216                com::sun::star::ucb::CommandFailedException,
217                com::sun::star::ucb::CommandAbortedException,
218                com::sun::star::lang::IllegalArgumentException);
219
220    /** Expert feature: erases the underlying registry cache and reinstalls
221        all previously added packages.  Please keep in mind that all
222        registration status get lost.
223        <p>
224        Please use this in case of suspected cache inconsistencies only.
225        </p>
226
227        @param xAbortChannel
228               abort channel to asynchronously abort the adding process
229        @param xCmdEnv
230               command environment for error and progress handling
231    */
232    void reinstallDeployedPackages(
233        [in] com::sun::star::task::XAbortChannel xAbortChannel,
234        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
235        raises (DeploymentException,
236                com::sun::star::ucb::CommandFailedException,
237                com::sun::star::ucb::CommandAbortedException,
238                com::sun::star::lang::IllegalArgumentException);
239
240    /** indicates that this implementation cannot be used for tasks
241        which require write access to the location where the extensions
242        are installed.
243        <p>
244        Normally one would call a method and handle the exception
245        if writing failed. However, a GUI interface may need to know beforehand
246        if writing is allowed. For example, the Extension Manager dialog
247        needs to enable / disable the Add button depending if the user has
248        write permission. Only the XPackageManager implementation knows the
249        location of the installed extensions. Therefore it is not possible
250        to check &quot;externally&quot; for write permission.
251        </p>
252    */
253    boolean isReadOnly();
254
255    /** synchronizes the extension database with the contents of the extensions
256       folder.
257
258       Added extensions will be added to the database and removed extensions
259       will be removed from the database.
260
261       @param xAddedExtension
262            new extensions which may need to be registered.
263
264       @param
265            removed extensions which must be revoked
266       @return
267            If true - then at least one extension was removed or added. Otherwise
268            nothing was chaned.
269    */
270    boolean synchronize([in] com::sun::star::task::XAbortChannel xAbortChannel,
271                     [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
272        raises (DeploymentException,
273                com::sun::star::ucb::CommandFailedException,
274                com::sun::star::ucb::CommandAbortedException);
275
276
277    /** returns all extensions which are currently not in use
278        because the user did not accept the license.
279
280        The function will not return any object for the user repository, because
281        a user extension will not be kept in the user repository if its license
282        is declined. Only extensions which are registered at start-up of OOo,
283        that is, shared and bundled extensions, can be returned.
284
285        Extensions which allow the license to be suppressed, that is, it does not
286        need to be displayed, and which are installed with the corresponding option,
287        are also not returned.
288    */
289    sequence<XPackage> getExtensionsWithUnacceptedLicenses(
290        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
291        raises (DeploymentException);
292
293    /** checks if the extension can be used.
294
295        The extension must be managed by this package manager, that is, it must
296        be recorded in its database.  The package manager calls
297        XPackage::checkPrerequisites and updates its data base with the
298        result. The result, which is from <type>Prerequisites</type> will be
299        returned.
300     */
301    long checkPrerequisites(
302        [in] XPackage extension,
303        [in] com::sun::star::task::XAbortChannel xAbortChannel,
304        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
305        raises (DeploymentException,
306                com::sun::star::ucb::CommandFailedException,
307                com::sun::star::ucb::CommandAbortedException,
308                com::sun::star::lang::IllegalArgumentException);
309
310};
311
312}; }; }; };
313
314#endif
315