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