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