offapi/com/sun/star/deployment/XPackageManager.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  * $RCSfile: XPackageManager.idl,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #if ! defined INCLUDED_com_sun_star_deployment_XPackageManager_idl
  32 #define INCLUDED_com_sun_star_deployment_XPackageManager_idl
  33
  34 #include <com/sun/star/lang/XComponent.idl>
  35 #include <com/sun/star/task/XAbortChannel.idl>
  36 #include <com/sun/star/util/XModifyBroadcaster.idl>
  37 #include <com/sun/star/deployment/XPackage.idl>
  38 #include <com/sun/star/deployment/XPackageTypeInfo.idl>
  39 #include <com/sun/star/ucb/XCommandEnvironment.idl>
  40 #include <com/sun/star/deployment/DeploymentException.idl>
  41 #include <com/sun/star/container/NoSuchElementException.idl>
  42 #include <com/sun/star/lang/IllegalArgumentException.idl>
  43
  44
  45 module com { module sun { module star { module deployment {
  46
  47 /** The <type>XPackageManager</type> interface is used to add or remove
  48     packages to a specific deployment context.
  49     Packages are deployable files, e.g. scripts or UNO components.
  50     <p>
  51     Adding an UNO package means that a copy of the package is stored
  52     with respect to the context of the manager and the package is registered,
  53     thus activated.
  54     </p>
  55     <p>
  56     Removing an UNO package means that the previously added package is revoked,
  57     thus deactivated, first and then removed from the context.
  58     </p>
  59     <p>
  60     Objects of this interface are created using the
  61     <type>XPackageManagerFactory</type> service resp. the singleton
  62     <code>
  63     /singletons/com.sun.star.deployment.thePackageManagerFactory
  64     </code>.
  65     </p>
  66
  67     @see thePackageManagerFactory
  68     @since OOo 2.0.0
  69 */
  70 interface XPackageManager
  71 {
  72     /** interface to notify disposing
  73      */
  74     interface com::sun::star::lang::XComponent;
  75
  76     /** interface to notify changes of the set of deployed packages of
  77         this manager
  78     */
  79     interface com::sun::star::util::XModifyBroadcaster;
  80
  81     /** returns the underlying deployment context.
  82
  83         @return
  84                 underlying deployment context
  85     */
  86     string getContext();
  87
  88     /** gets the supported <type>XPackageTypeInfo</type>s.
  89
  90         @return
  91                 supported <type>XPackageTypeInfo</type>s.
  92     */
  93     sequence<XPackageTypeInfo> getSupportedPackageTypes();
  94
  95     /** creates a command channel to be used to asynchronously abort a command.
  96
  97         @return
  98                 abort channel
  99     */
 100     com::sun::star::task::XAbortChannel createAbortChannel();
 101
 102     /** adds an UNO package.
 103
 104         @param url
 105                package URL, must be UCB conform
 106         @param mediaType
 107                media-type of package, empty string if to be detected
 108         @param xAbortChannel
 109                abort channel to asynchronously abort the adding process,
 110                or null
 111         @param xCmdEnv
 112                command environment for error and progress handling
 113         @return
 114                <type>XPackage</type> handle
 115     */
 116     XPackage addPackage( [in] string url,
 117                          [in] string mediaType,
 118                          [in] com::sun::star::task::XAbortChannel xAbortChannel,
 119                          [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 120         raises (DeploymentException,
 121                 com::sun::star::ucb::CommandFailedException,
 122                 com::sun::star::ucb::CommandAbortedException,
 123                 com::sun::star::lang::IllegalArgumentException);
 124
 125     /** removes an UNO package.
 126
 127         @param identifier
 128                package identifier
 129         @param fileName
 130                package file name
 131         @param xAbortChannel
 132                abort channel to asynchronously abort the removing process,
 133                or null
 134         @param xCmdEnv
 135                command environment for error and progress handling
 136     */
 137     void removePackage( [in] string identifier,
 138                         [in] string fileName,
 139                         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 140                         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 141         raises (DeploymentException,
 142                 com::sun::star::ucb::CommandFailedException,
 143                 com::sun::star::ucb::CommandAbortedException,
 144                 com::sun::star::lang::IllegalArgumentException);
 145
 146     /** gets a deployed package.
 147
 148         @param identifier
 149                package identifier
 150         @param fileName
 151                package file name
 152         @param xCmdEnv
 153                command environment for error and progress handling
 154         @return
 155                <type>XPackage</type> handle
 156     */
 157     XPackage getDeployedPackage(
 158         [in] string identifier,
 159         [in] string fileName,
 160         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 161         raises (DeploymentException,
 162                 com::sun::star::ucb::CommandFailedException,
 163                 com::sun::star::lang::IllegalArgumentException);
 164
 165     /** gets all currently deployed packages.
 166
 167         @param xAbortChannel
 168                abort channel to asynchronously abort the removing process,
 169                or null
 170         @param xCmdEnv
 171                command environment for error and progress handling
 172         @return
 173                 all currently deployed packages
 174     */
 175     sequence<XPackage> getDeployedPackages(
 176         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 177         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 178         raises (DeploymentException,
 179                 com::sun::star::ucb::CommandFailedException,
 180                 com::sun::star::ucb::CommandAbortedException,
 181                 com::sun::star::lang::IllegalArgumentException);
 182
 183     /** Expert feature: erases the underlying registry cache and reinstalls
 184         all previously added packages.  Please keep in mind that all
 185         registration status get lost.
 186         <p>
 187         Please use this in case of suspected cache inconsistencies only.
 188         </p>
 189
 190         @param xAbortChannel
 191                abort channel to asynchronously abort the adding process
 192         @param xCmdEnv
 193                command environment for error and progress handling
 194     */
 195     void reinstallDeployedPackages(
 196         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 197         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 198         raises (DeploymentException,
 199                 com::sun::star::ucb::CommandFailedException,
 200                 com::sun::star::ucb::CommandAbortedException,
 201                 com::sun::star::lang::IllegalArgumentException);
 202
 203     /** indicates that this implementation cannot be used for tasks
 204         which require write access to the location where the extensions
 205         are installed.
 206         <p>
 207         Normally one would call a method and handle the exception
 208         if writing failed. However, a GUI interface may need to know beforehand
 209         if writing is allowed. For example, the Extension Manager dialog
 210         needs to enable / disable the Add button depending if the user has
 211         write permission. Only the XPackageManager implementation knows the
 212         location of the installed extensions. Therefore it is not possible
 213         to check &quot;externally&quot; for write permission.
 214         </p>
 215     */
 216     boolean isReadOnly();
 217
 218 };
 219
 220 }; }; }; };
 221
 222 #endif