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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   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/graphic/XGraphic.idl>
  37 #include <com/sun/star/lang/XComponent.idl>
  38 #include <com/sun/star/lang/IllegalArgumentException.idl>
  39 #include <com/sun/star/task/XAbortChannel.idl>
  40 #include <com/sun/star/ucb/CommandFailedException.idl>
  41 #include <com/sun/star/ucb/CommandAbortedException.idl>
  42 #include <com/sun/star/ucb/XCommandEnvironment.idl>
  43 #include <com/sun/star/util/XModifyBroadcaster.idl>
  44
  45
  46 module com { module sun { module star { module deployment {
  47
  48 /** Objects of this interface reflect a bound package and are issued by a
  49     <type>PackageRegistryBackend</type>.
  50
  51     @since OOo 2.0.0
  52 */
  53 interface XPackage
  54 {
  55     /** implemented to notify that the package has been removed
  56      */
  57     interface com::sun::star::lang::XComponent;
  58
  59     /** notifies changes of the registration state of the package
  60      */
  61     interface com::sun::star::util::XModifyBroadcaster;
  62
  63
  64     /** creates a command channel to be used to asynchronously abort a command.
  65
  66         @return
  67                 abort channel
  68     */
  69     com::sun::star::task::XAbortChannel createAbortChannel();
  70
  71     /** checks if the package can be installed.
  72
  73         Only if the return value is true the package is allowed to be installed.
  74         In case of false or in case of an exception, the package must be removed
  75         in completely.
  76         After return of this function no code from the extension may be used
  77         anymore, so that the extension can be safely removed from the harddisk.
  78
  79         @param xCmdEnv
  80                command environment for error handling and other interaction.
  81         @installed
  82             signalls if an extension with the same identifyer is already installed.
  83
  84         @aContextName
  85             the name of the context of  XPackageManager implementation that is to be used
  86             to install the extension. Currently we use the names "user"
  87             and "shared".
  88
  89         @return
  90             true - the package can be installed
  91             false - the package must not be installed.
  92      */
  93     boolean checkPrerequisites(
  94         [in] com::sun::star::task::XAbortChannel xAbortChannel,
  95         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv,
  96         [in] boolean installed,
  97         [in] string aContextName)
  98         raises (DeploymentException,
  99                 com::sun::star::ucb::CommandFailedException,
 100                 com::sun::star::ucb::CommandAbortedException);
 101
 102     /** checks if the dependencies for this package are still satisfied
 103
 104         After updateing the OpenOffice.org, some dependencies for packages might
 105         no longer be satisfied.
 106
 107         @since OOo 3.2.0
 108
 109         @param xCmdEnv
 110                command environment for error handling and other interaction.
 111
 112         @return
 113             true - all dependencies are satisfied
 114             false - at least one dependency failed.
 115      */
 116     boolean checkDependencies(
 117         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 118         raises (DeploymentException,
 119                 com::sun::star::ucb::CommandFailedException);
 120
 121
 122     /** determines whether the package is currently is registered, i.e.
 123         whether it is active.
 124
 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         @return
 131                 status whether the package is registered (<TRUE/>, <FALSE/>) or
 132                 the status is ambiguous.  Additionally, a registration status
 133                 may not apply, e.g. in case of an empty package bundle.
 134     */
 135     com::sun::star::beans::Optional<
 136         com::sun::star::beans::Ambiguous<boolean> > isRegistered(
 137             [in] com::sun::star::task::XAbortChannel xAbortChannel,
 138             [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 139         raises (DeploymentException,
 140                 com::sun::star::ucb::CommandFailedException,
 141                 com::sun::star::ucb::CommandAbortedException);
 142
 143     /** registers this <type>XPackage</type>, thus activating the package.
 144
 145         @param xAbortChannel
 146                abort channel to asynchronously abort the registration process,
 147                or null
 148         @param xCmdEnv
 149                command environment for error and progress handling
 150     */
 151     void registerPackage(
 152         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 153         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 154         raises (DeploymentException,
 155                 com::sun::star::ucb::CommandFailedException,
 156                 com::sun::star::ucb::CommandAbortedException,
 157                 com::sun::star::lang::IllegalArgumentException);
 158
 159     /** revokes this <type>XPackage</type>.
 160
 161         @param xAbortChannel
 162                abort channel to asynchronously abort the registration process,
 163                or null
 164         @param xCmdEnv
 165                command environment for error and progress handling
 166     */
 167     void revokePackage(
 168         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 169         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 170         raises (DeploymentException,
 171                 com::sun::star::ucb::CommandFailedException,
 172                 com::sun::star::ucb::CommandAbortedException,
 173                 com::sun::star::lang::IllegalArgumentException);
 174
 175     /** reflects whether this package is a bundle of one or more packages,
 176         e.g. a zip (legacy) package file or a document hosting script packages.
 177
 178         @return
 179                 in case this package relfects a package bundle
 180     */
 181     boolean isBundle();
 182
 183     /** Gets packages of the bundle.
 184
 185         @param xAbortChannel
 186                abort channel to asynchronously abort the registration process,
 187                or null
 188         @param xCmdEnv
 189                command environment for error and progress handling
 190         @return
 191                 set of packages enclosed in this package
 192     */
 193     sequence<XPackage> getBundle(
 194         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 195         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 196         raises (DeploymentException,
 197                 com::sun::star::ucb::CommandFailedException,
 198                 com::sun::star::ucb::CommandAbortedException,
 199                 com::sun::star::lang::IllegalArgumentException);
 200
 201     /** returns the file name of the package.
 202
 203         @return
 204                 file name of the package
 205     */
 206     string getName();
 207
 208     /** returns the unique extension identifier.
 209
 210         @return
 211                 the extension identifier (a
 212         <code>"org.openoffice.legacy."</code> one if the extension does not
 213         explicitly specify one), or an empty <code>Optional</code> if this
 214         package does not represent an extension
 215     */
 216     com::sun::star::beans::Optional<string> getIdentifier();
 217
 218     /** returns the textual version representation of the package.
 219
 220         A textual version representation is a finite string following the
 221         BNF<br/>
 222         version ::= [element ("." element)*]<br/>
 223         element ::= ("0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9")+
 224
 225         @return
 226                 the textual version representation
 227     */
 228     string getVersion();
 229
 230     /** returns the location of the package.
 231
 232         @return
 233                 location of package
 234     */
 235     string getURL();
 236
 237     /** returns the display name of the package, e.g. for graphical user
 238         interfaces (GUI).
 239
 240         @return
 241                 display name of the package
 242     */
 243     string getDisplayName();
 244
 245     /** returns a description string to describe the  package.
 246
 247         @return
 248                 description
 249     */
 250     string getDescription();
 251
 252     /** returns a sequence of update information URLs.
 253
 254         The sequence may be empty in case no update information is available.
 255         If the sequence contains more than one URL, the extra URLs must mirror
 256         the information available at the first URL.
 257
 258         @return
 259                 update information URLs
 260     */
 261     sequence<string> getUpdateInformationURLs();
 262
 263     /** returns the publisher info for a package, the strings
 264         might be empty, if there are no publisher
 265
 266         <type scope="::com::sun::star::beans">StringPair</type>::First
 267         represents the publisher name and
 268         <type scope="::com::sun::star::beans">StringPair</type>::Second
 269         represents the URL to the publisher.
 270     */
 271
 272     ::com::sun::star::beans::StringPair getPublisherInfo();
 273
 274     /** returns the <type>XPackageTypeInfo</type>, e.g. media-type etc.
 275
 276         @return
 277                 media type of package
 278     */
 279     XPackageTypeInfo getPackageType();
 280
 281     /** exports package to given destination URL.
 282
 283         @param destFolderURL
 284                package destination folder URL, must be UCB conform
 285         @param newTitle
 286                new package name
 287         @param nameClashAction
 288                one of <type scope="com::sun::star::ucb">NameClash</type>
 289         @param xCmdEnv
 290                command environment for error and progress handling
 291     */
 292     void exportTo( [in] string destFolderURL,
 293                    [in] string newTitle,
 294                    [in] long nameClashAction,
 295                    [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 296         raises (com::sun::star::ucb::CommandFailedException,
 297                 com::sun::star::ucb::CommandAbortedException);
 298
 299     /** returns an icon for a package.
 300
 301         @param highContrast
 302             return high contrast icon
 303         @return
 304             the icon which should be used to represent the table in the
 305             database application window, or <NULL/> if the default icon
 306             should be used.
 307     */
 308     com::sun::star::graphic::XGraphic getIcon( [in] boolean highContrast );
 309 };
 310
 311 }; }; }; };
 312
 313 #endif