offapi/com/sun/star/deployment/XPackage.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef _com_sun_star_deployment_XPackage_idl
  21 #define _com_sun_star_deployment_XPackage_idl
  22
  23 #include <com/sun/star/beans/Optional.idl>
  24 #include <com/sun/star/beans/Ambiguous.idl>
  25 #include <com/sun/star/beans/StringPair.idl>
  26 #include <com/sun/star/deployment/DeploymentException.idl>
  27 #include <com/sun/star/deployment/XPackageTypeInfo.idl>
  28 #include <com/sun/star/deployment/ExtensionRemovedException.idl>
  29 #include <com/sun/star/graphic/XGraphic.idl>
  30 #include <com/sun/star/lang/XComponent.idl>
  31 #include <com/sun/star/lang/IllegalArgumentException.idl>
  32 #include <com/sun/star/task/XAbortChannel.idl>
  33 #include <com/sun/star/ucb/CommandFailedException.idl>
  34 #include <com/sun/star/ucb/CommandAbortedException.idl>
  35 #include <com/sun/star/ucb/XCommandEnvironment.idl>
  36 #include <com/sun/star/util/XModifyBroadcaster.idl>
  37
  38
  39 module com { module sun { module star { module deployment {
  40
  41 /** Objects of this interface reflect a bound package and are issued by a
  42     PackageRegistryBackend.
  43
  44     @since OOo 2.0
  45 */
  46 interface XPackage
  47 {
  48     /** implemented to notify that the package has been removed
  49      */
  50     interface com::sun::star::lang::XComponent;
  51
  52     /** notifies changes of the registration state of the package
  53      */
  54     interface com::sun::star::util::XModifyBroadcaster;
  55
  56
  57     /** creates a command channel to be used to asynchronously abort a command.
  58
  59         @return
  60                 abort channel
  61     */
  62     com::sun::star::task::XAbortChannel createAbortChannel();
  63
  64     /** checks if the package can be installed.
  65
  66         Only if the return value is `TRUE` the package is allowed to be installed.
  67         In case of `FALSE` or in case of an exception, the package must be removed
  68         completely.
  69         After return of this function no code from the extension may be used
  70         anymore, so that the extension can be safely removed from the hard disk.
  71
  72         @param xAbortChannel
  73                abort channel to asynchronously abort the registration process,
  74                or `NULL`
  75         @param xCmdEnv
  76                command environment for error handling and other interaction.
  77         @param alreadyInstalled
  78             indicates that an extension with the same identifier is already installed.
  79
  80         @return
  81             `NULL` - all prerequisites are met. Otherwise, a value from
  82             Prerequisites indicating what prerequisites are missing.
  83      */
  84     long checkPrerequisites(
  85         [in] com::sun::star::task::XAbortChannel xAbortChannel,
  86         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv,
  87         [in] boolean alreadyInstalled)
  88         raises (DeploymentException,
  89                 ExtensionRemovedException,
  90                 com::sun::star::ucb::CommandFailedException,
  91                 com::sun::star::ucb::CommandAbortedException);
  92
  93     /** checks if the dependencies for this package are still satisfied
  94
  95         After updating the OpenOffice.org, some dependencies for packages might
  96         no longer be satisfied.
  97
  98         @since OOo 3.2
  99
 100         @param xCmdEnv
 101                command environment for error handling and other interaction.
 102
 103         @return
 104             `TRUE` - all dependencies are satisfied
 105             `FALSE` - at least one dependency failed.
 106      */
 107     boolean checkDependencies(
 108         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 109         raises (DeploymentException,
 110                 ExtensionRemovedException,
 111                 com::sun::star::ucb::CommandFailedException);
 112
 113
 114     /** determines whether the package is currently registered, i.e.
 115         whether it is active.
 116
 117         @param xAbortChannel
 118                abort channel to asynchronously abort the registration process,
 119                or `NULL`
 120         @param xCmdEnv
 121                command environment for error and progress handling
 122         @return
 123                 status whether the package is registered (`TRUE`, `FALSE`) or
 124                 the status is ambiguous.  Additionally, a registration status
 125                 may not apply, e.g. in case of an empty package bundle.
 126     */
 127     com::sun::star::beans::Optional<
 128         com::sun::star::beans::Ambiguous<boolean> > isRegistered(
 129             [in] com::sun::star::task::XAbortChannel xAbortChannel,
 130             [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 131         raises (DeploymentException,
 132                 com::sun::star::ucb::CommandFailedException,
 133                 com::sun::star::ucb::CommandAbortedException);
 134
 135     /** registers this XPackage.
 136
 137         NEVER call this directly. This is done by the extension manager if necessary.
 138
 139         @param startup
 140                indicates that registration is adapted to the particular
 141                startup scenario. That is, it is set to `TRUE`, when called
 142                from XExtensionManager::synchronize()
 143         @param xAbortChannel
 144                abort channel to asynchronously abort the registration process,
 145                or `NULL`
 146         @param xCmdEnv
 147                command environment for error and progress handling
 148     */
 149     void registerPackage(
 150         [in] boolean startup,
 151         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 152         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 153         raises (DeploymentException,
 154                 ExtensionRemovedException,
 155                 com::sun::star::ucb::CommandFailedException,
 156                 com::sun::star::ucb::CommandAbortedException,
 157                 com::sun::star::lang::IllegalArgumentException);
 158
 159     /** revokes this XPackage.
 160
 161         NEVER call this directly. This is done by the extension manager if necessary.
 162
 163         @param startup
 164                indicates that registration is adapted to the particular
 165                startup scenario. That is, it is set to `TRUE`, when called
 166                from XExtensionManager::synchronize()
 167         @param xAbortChannel
 168                abort channel to asynchronously abort the registration process,
 169                or `NULL`
 170         @param xCmdEnv
 171                command environment for error and progress handling
 172     */
 173     void revokePackage(
 174         [in] boolean startup,
 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                 `TRUE` if this package is a package bundle, `FALSE` otherwise
 187     */
 188     boolean isBundle();
 189
 190     /** Gets packages of the bundle.
 191
 192         If isRemoved() 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 (DeploymentException,
 272                  ExtensionRemovedException);
 273
 274     /** returns a sequence of update information URLs.
 275
 276         The sequence may be empty in case no update information is available.
 277         If the sequence contains more than one URL, the extra URLs must mirror
 278         the information available at the first URL.
 279
 280         @return
 281                 update information URLs
 282     */
 283     sequence<string> getUpdateInformationURLs()
 284         raises (ExtensionRemovedException);
 285     /** returns the publisher info for the package, the strings
 286         might be empty, if there is no publisher
 287
 288         ::com::sun::star::beans::StringPair::First
 289         represents the publisher name and
 290         ::com::sun::star::beans::StringPair::Second
 291         represents the URL to the publisher.
 292     */
 293
 294     ::com::sun::star::beans::StringPair getPublisherInfo()
 295         raises (ExtensionRemovedException);
 296     /** returns the XPackageTypeInfo, e.g. media-type etc.
 297
 298         @return
 299                 media type of package
 300     */
 301     XPackageTypeInfo getPackageType();
 302
 303     /** exports package to given destination URL.
 304
 305         @param destFolderURL
 306                package destination folder URL, must be UCB conforming
 307         @param newTitle
 308                new package name
 309         @param nameClashAction
 310                one of com::sun::star::ucb::NameClash
 311         @param xCmdEnv
 312                command environment for error and progress handling
 313     */
 314     void exportTo( [in] string destFolderURL,
 315                    [in] string newTitle,
 316                    [in] long nameClashAction,
 317                    [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 318         raises (
 319             ExtensionRemovedException,
 320             com::sun::star::ucb::CommandFailedException,
 321             com::sun::star::ucb::CommandAbortedException,
 322             com::sun::star::ucb::ContentCreationException);
 323
 324     /** returns an icon for a package.
 325
 326         @param highContrast
 327             return high contrast icon
 328         @return
 329             the icon which should be used to represent the table in the
 330             database application window, or `NULL` if the default icon
 331             should be used.
 332     */
 333     com::sun::star::graphic::XGraphic getIcon( [in] boolean highContrast )
 334         raises (ExtensionRemovedException);
 335
 336     /** returns the name of the repository where this object comes from.
 337      */
 338     string getRepositoryName();
 339
 340     /** return a URL to a directory which contains the registration data.
 341
 342         This data may be created when calling
 343         XPackage::registerPackage().  If this is the case is
 344         indicated by
 345         com::sun::star::beans::Optional::IsPresent of the return
 346         value.
 347         If registration data are created during registration, but the package is
 348         currently not registered, for example after calling
 349         XPackage::revokePackage(), then
 350         com::sun::star::beans::Optional::IsPresent is `TRUE` and
 351         the com::sun::star::beans::Optional::Value may
 352         be an empty string.
 353     */
 354     com::sun::star::beans::Optional<string> getRegistrationDataURL()
 355         raises (DeploymentException, ExtensionRemovedException);
 356
 357     /** indicates if this object represents a removed extension or extension
 358         item. This is the case when it was created by providing
 359         `TRUE` for the <code>removed</code> parameter in the function
 360         XPackageRegistry::bindPackage().
 361      */
 362     boolean isRemoved();
 363
 364 };
 365
 366 }; }; }; };
 367
 368 #endif
 369
 370 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */