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