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_XPackage_idl
29#define INCLUDED_com_sun_star_deployment_XPackage_idl
30
31#include <com/sun/star/beans/Optional.idl>
32#include <com/sun/star/beans/Ambiguous.idl>
33#include <com/sun/star/beans/StringPair.idl>
34#include <com/sun/star/deployment/DeploymentException.idl>
35#include <com/sun/star/deployment/XPackageTypeInfo.idl>
36#include <com/sun/star/deployment/ExtensionRemovedException.idl>
37#include <com/sun/star/graphic/XGraphic.idl>
38#include <com/sun/star/lang/XComponent.idl>
39#include <com/sun/star/lang/IllegalArgumentException.idl>
40#include <com/sun/star/task/XAbortChannel.idl>
41#include <com/sun/star/ucb/CommandFailedException.idl>
42#include <com/sun/star/ucb/CommandAbortedException.idl>
43#include <com/sun/star/ucb/XCommandEnvironment.idl>
44#include <com/sun/star/util/XModifyBroadcaster.idl>
45
46
47module com { module sun { module star { module deployment {
48
49/** Objects of this interface reflect a bound package and are issued by a
50    <type>PackageRegistryBackend</type>.
51
52    @since OOo 2.0
53*/
54interface XPackage
55{
56    /** implemented to notify that the package has been removed
57     */
58    interface com::sun::star::lang::XComponent;
59
60    /** notifies changes of the registration state of the package
61     */
62    interface com::sun::star::util::XModifyBroadcaster;
63
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    /** checks if the package can be installed.
73
74        Only if the return value is true the package is allowed to be installed.
75        In case of false or in case of an exception, the package must be removed
76        completely.
77        After return of this function no code from the extension may be used
78        anymore, so that the extension can be safely removed from the harddisk.
79
80        @param xCmdEnv
81               command environment for error handling and other interaction.
82        @alreadyInstalled
83            indicates that an extension with the same identifyer is already installed.
84
85        @return
86            null - all prerequisites are met. Otherwise, a value from
87            <member>Prerequisites</member> indicating what prerequisites are missing.
88     */
89    long checkPrerequisites(
90        [in] com::sun::star::task::XAbortChannel xAbortChannel,
91        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv,
92        [in] boolean alreadyInstalled)
93        raises (DeploymentException,
94                ExtensionRemovedException,
95                com::sun::star::ucb::CommandFailedException,
96                com::sun::star::ucb::CommandAbortedException);
97
98    /** checks if the dependencies for this package are still satisfied
99
100        After updateing the OpenOffice.org, some dependencies for packages might
101        no longer be satisfied.
102
103        @since OOo 3.2
104
105        @param xCmdEnv
106               command environment for error handling and other interaction.
107
108        @return
109            true - all dependencies are satisfied
110            false - at least one dependency failed.
111     */
112    boolean checkDependencies(
113        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
114        raises (DeploymentException,
115                ExtensionRemovedException,
116                com::sun::star::ucb::CommandFailedException);
117
118
119    /** determines whether the package is currently is registered, i.e.
120        whether it is active.
121
122        @param xAbortChannel
123               abort channel to asynchronously abort the registration process,
124               or null
125        @param xCmdEnv
126               command environment for error and progress handling
127        @return
128                status whether the package is registered (<TRUE/>, <FALSE/>) or
129                the status is ambiguous.  Additionally, a registration status
130                may not apply, e.g. in case of an empty package bundle.
131    */
132    com::sun::star::beans::Optional<
133        com::sun::star::beans::Ambiguous<boolean> > isRegistered(
134            [in] com::sun::star::task::XAbortChannel xAbortChannel,
135            [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
136        raises (DeploymentException,
137                com::sun::star::ucb::CommandFailedException,
138                com::sun::star::ucb::CommandAbortedException);
139
140    /** registers this <type>XPackage</type>.
141
142        NEVER call this directly. This is done by the extension manager if necessary.
143
144        @param startup
145               indicates that registration is adapted to the particular
146               startup scenario. That is, it is set to true, when called
147               from <member>XExtensionManager::synchronize</member>
148        @param xAbortChannel
149               abort channel to asynchronously abort the registration process,
150               or null
151        @param xCmdEnv
152               command environment for error and progress handling
153    */
154    void registerPackage(
155        [in] boolean startup,
156        [in] com::sun::star::task::XAbortChannel xAbortChannel,
157        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
158        raises (DeploymentException,
159                ExtensionRemovedException,
160                com::sun::star::ucb::CommandFailedException,
161                com::sun::star::ucb::CommandAbortedException,
162                com::sun::star::lang::IllegalArgumentException);
163
164    /** revokes this <type>XPackage</type>.
165
166        NEVER call this directly. This is done by the extension manager if necessary.
167
168        @param xAbortChannel
169               abort channel to asynchronously abort the registration process,
170               or null
171        @param xCmdEnv
172               command environment for error and progress handling
173    */
174    void revokePackage(
175        [in] com::sun::star::task::XAbortChannel xAbortChannel,
176        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
177        raises (DeploymentException,
178                com::sun::star::ucb::CommandFailedException,
179                com::sun::star::ucb::CommandAbortedException,
180                com::sun::star::lang::IllegalArgumentException);
181
182    /** reflects whether this package is a bundle of one or more packages,
183        e.g. a zip (legacy) package file or a document hosting script packages.
184
185        @return
186                in case this package relfects a package bundle
187    */
188    boolean isBundle();
189
190    /** Gets packages of the bundle.
191
192        If <member>isRemoved</member> returns true then getBundle may return an
193        empty sequence in case the object is not registered.
194
195        @param xAbortChannel
196               abort channel to asynchronously abort the registration process,
197               or null
198        @param xCmdEnv
199               command environment for error and progress handling
200        @return
201                set of packages enclosed in this package
202    */
203    sequence<XPackage> getBundle(
204        [in] com::sun::star::task::XAbortChannel xAbortChannel,
205        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
206        raises (DeploymentException,
207                com::sun::star::ucb::CommandFailedException,
208                com::sun::star::ucb::CommandAbortedException,
209                com::sun::star::lang::IllegalArgumentException);
210
211    /** returns the file name of the package.
212
213        @return
214                file name of the package
215    */
216    string getName();
217
218    /** returns the unique extension identifier.
219
220        @return
221                the extension identifier (a
222        <code>"org.openoffice.legacy."</code> one if the extension does not
223        explicitly specify one), or an empty <code>Optional</code> if this
224        package does not represent an extension
225    */
226    com::sun::star::beans::Optional<string> getIdentifier();
227
228    /** returns the textual version representation of the package.
229
230        A textual version representation is a finite string following the
231        BNF<br/>
232        version ::= [element ("." element)*]<br/>
233        element ::= ("0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9")+
234
235        @return
236                the textual version representation
237    */
238    string getVersion()
239        raises (ExtensionRemovedException);
240
241    /** returns the location of the package.
242
243        @return
244                location of package
245    */
246    string getURL();
247
248    /** returns the display name of the package, e.g. for graphical user
249        interfaces (GUI).
250
251        @return
252                display name of the package
253    */
254    string getDisplayName()
255        raises (ExtensionRemovedException);
256
257    /** returns a description string to describe the  package.
258
259        @return
260                description
261    */
262    string getDescription()
263         raises (ExtensionRemovedException);
264
265    /** returns a string containing the license text.
266
267        @return
268                license
269    */
270    string getLicenseText()
271         raises (ExtensionRemovedException);
272
273    /** returns a sequence of update information URLs.
274
275        The sequence may be empty in case no update information is available.
276        If the sequence contains more than one URL, the extra URLs must mirror
277        the information available at the first URL.
278
279        @return
280                update information URLs
281    */
282    sequence<string> getUpdateInformationURLs()
283        raises (ExtensionRemovedException);
284    /** returns the publisher info for a package, the strings
285        might be empty, if there are no publisher
286
287        <type scope="::com::sun::star::beans">StringPair</type>::First
288        represents the publisher name and
289        <type scope="::com::sun::star::beans">StringPair</type>::Second
290        represents the URL to the publisher.
291    */
292
293    ::com::sun::star::beans::StringPair getPublisherInfo()
294        raises (ExtensionRemovedException);
295    /** returns the <type>XPackageTypeInfo</type>, e.g. media-type etc.
296
297        @return
298                media type of package
299    */
300    XPackageTypeInfo getPackageType();
301
302    /** exports package to given destination URL.
303
304        @param destFolderURL
305               package destination folder URL, must be UCB conform
306        @param newTitle
307               new package name
308        @param nameClashAction
309               one of <type scope="com::sun::star::ucb">NameClash</type>
310        @param xCmdEnv
311               command environment for error and progress handling
312    */
313    void exportTo( [in] string destFolderURL,
314                   [in] string newTitle,
315                   [in] long nameClashAction,
316                   [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
317        raises (
318            ExtensionRemovedException,
319            com::sun::star::ucb::CommandFailedException,
320            com::sun::star::ucb::CommandAbortedException);
321
322    /** returns an icon for a package.
323
324        @param highContrast
325            return high contrast icon
326        @return
327            the icon which should be used to represent the table in the
328            database application window, or <NULL/> if the default icon
329            should be used.
330    */
331    com::sun::star::graphic::XGraphic getIcon( [in] boolean highContrast )
332        raises (ExtensionRemovedException);
333
334    /** returns the name of the repository where this object comes from.
335     */
336    string getRepositoryName();
337
338    /** return a URL to a directory which contains the registration data.
339
340        This data may be created when calling
341        <member>XPackage::registerPackage</member>.  If this is the case is
342        indicated by <member
343        scope="com::sun::star::beans">Optional::IsPresent</member> of the return
344        value.
345        If registration data are created during registration, but the package is
346        currently not registered, for example after calling
347        <member>XPackage::revokePackage</member>, then <member
348        scope="com::sun::star::beans">Optional::IsPresent</member> is true and
349        the <member scope="com::sun::star::beans">Optional::Value</member> may
350        be an empty string.
351    */
352    com::sun::star::beans::Optional<string> getRegistrationDataURL()
353        raises (ExtensionRemovedException);
354
355    /** indicates if this object represents a removed extension or extension
356        item. This is the case when it was created by providing
357        <code>true</code> for the <code>removed</code> parameter in the function
358        <member>XPackageRegistry::bindPackage</member>.
359     */
360    boolean isRemoved();
361
362};
363
364}; }; }; };
365
366#endif
367