offapi/com/sun/star/deployment/XPackageManager.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_XPackageManager_idl
  21 #define _com_sun_star_deployment_XPackageManager_idl
  22
  23 #include <com/sun/star/lang/XComponent.idl>
  24 #include <com/sun/star/task/XAbortChannel.idl>
  25 #include <com/sun/star/util/XModifyBroadcaster.idl>
  26 #include <com/sun/star/deployment/XPackage.idl>
  27 #include <com/sun/star/deployment/XPackageTypeInfo.idl>
  28 #include <com/sun/star/ucb/XCommandEnvironment.idl>
  29 #include <com/sun/star/deployment/DeploymentException.idl>
  30 #include <com/sun/star/container/NoSuchElementException.idl>
  31 #include <com/sun/star/lang/IllegalArgumentException.idl>
  32 #include <com/sun/star/beans/NamedValue.idl>
  33
  34
  35 module com { module sun { module star { module deployment {
  36
  37 /** The XPackageManager interface is used to add or remove
  38     packages to a specific repository. This interface represents a particular
  39     repository.
  40     Packages are deployable files, e.g. scripts or UNO components.
  41     <p>
  42     Adding an UNO package means that a copy of the package is stored
  43     in the repository.
  44     </p>
  45     <p>
  46     Removing an UNO package means that the previously added package is
  47     removed from the repository.
  48     </p>
  49     <p>
  50     All interface methods do neither register nor revoke an extension.
  51     This happens exclusively by XExtensionManager.
  52     </p>
  53     <p>
  54     Objects of this interface are created using the
  55     XPackageManagerFactory service resp. the singleton
  56     <code>
  57     /singletons/com.sun.star.deployment.thePackageManagerFactory
  58     </code>.
  59     </p>
  60
  61     @see thePackageManagerFactory
  62     @since OOo 2.0
  63     @deprecated
  64          Use XExtensionManager.
  65 */
  66 interface XPackageManager
  67 {
  68     /** interface to notify disposing
  69      */
  70     interface com::sun::star::lang::XComponent;
  71
  72     /** interface to notify changes of the set of deployed packages of
  73         this manager
  74     */
  75     interface com::sun::star::util::XModifyBroadcaster;
  76
  77     /** returns the underlying deployment context, that is,
  78         the name of the repository.
  79
  80         @return
  81                 underlying deployment context
  82     */
  83     string getContext();
  84
  85     /** gets the supported XPackageTypeInfos.
  86
  87         @return
  88                 supported XPackageTypeInfos.
  89     */
  90     sequence<XPackageTypeInfo> getSupportedPackageTypes();
  91
  92     /** creates a command channel to be used to asynchronously abort a command.
  93
  94         @return
  95                 abort channel
  96     */
  97     com::sun::star::task::XAbortChannel createAbortChannel();
  98
  99     /** adds an UNO package.
 100
 101         The properties argument is currently only used to suppress the license information
 102         for shared extensions.
 103
 104
 105         @param url
 106                package URL, must be UCB conform
 107         @param properties
 108                additional properties, for example, that the license is to be
 109                suppressed (if supported by the extension)
 110         @param mediaType
 111                media-type of package, empty string if to be detected
 112         @param xAbortChannel
 113                abort channel to asynchronously abort the adding process,
 114                or null
 115         @param xCmdEnv
 116                command environment for error and progress handling
 117         @return
 118                XPackage handle
 119     */
 120     XPackage addPackage( [in] string url,
 121                          [in] sequence<com::sun::star::beans::NamedValue> properties,
 122                          [in] string mediaType,
 123                          [in] com::sun::star::task::XAbortChannel xAbortChannel,
 124                          [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 125         raises (DeploymentException,
 126                 com::sun::star::ucb::CommandFailedException,
 127                 com::sun::star::ucb::CommandAbortedException,
 128                 com::sun::star::lang::IllegalArgumentException);
 129
 130     /** adds an extension.
 131
 132         This copies the extension. If it was from the same repository,
 133         which is represented by this XPackageManager interface, then
 134         nothing happens.
 135
 136         @param extension
 137
 138         @param xAbortChannel
 139                abort channel to asynchronously abort the adding process,
 140                or null
 141         @param xCmdEnv
 142                command environment for error and progress handling
 143         @return
 144                XPackage handle
 145     */
 146     XPackage importExtension( [in] XPackage extension,
 147                          [in] com::sun::star::task::XAbortChannel xAbortChannel,
 148                          [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 149         raises (DeploymentException,
 150                 com::sun::star::ucb::CommandFailedException,
 151                 com::sun::star::ucb::CommandAbortedException,
 152                 com::sun::star::lang::IllegalArgumentException);
 153
 154     /** removes an UNO package.
 155
 156         @param identifier
 157                package identifier
 158         @param fileName
 159                package file name
 160         @param xAbortChannel
 161                abort channel to asynchronously abort the removing process,
 162                or null
 163         @param xCmdEnv
 164                command environment for error and progress handling
 165     */
 166     void removePackage( [in] string identifier,
 167                         [in] string fileName,
 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     /** gets a deployed package.
 176
 177         @param identifier
 178                package identifier
 179         @param fileName
 180                package file name
 181         @param xCmdEnv
 182                command environment for error and progress handling
 183         @return
 184                XPackage handle
 185     */
 186     XPackage getDeployedPackage(
 187         [in] string identifier,
 188         [in] string fileName,
 189         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 190         raises (DeploymentException,
 191                 com::sun::star::ucb::CommandFailedException,
 192                 com::sun::star::lang::IllegalArgumentException);
 193
 194     /** gets all currently deployed packages.
 195
 196         @param xAbortChannel
 197                abort channel to asynchronously abort the removing process,
 198                or null
 199         @param xCmdEnv
 200                command environment for error and progress handling
 201         @return
 202                 all currently deployed packages
 203     */
 204     sequence<XPackage> getDeployedPackages(
 205         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 206         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 207         raises (DeploymentException,
 208                 com::sun::star::ucb::CommandFailedException,
 209                 com::sun::star::ucb::CommandAbortedException,
 210                 com::sun::star::lang::IllegalArgumentException);
 211
 212     /** Expert feature: erases the underlying registry cache and reinstalls
 213         all previously added packages.  Please keep in mind that all
 214         registration status get lost.
 215         <p>
 216         Please use this in case of suspected cache inconsistencies only.
 217         </p>
 218
 219         @param force
 220                set to true when called during soffice bootstrap after cleaning
 221                old extension cache
 222         @param xAbortChannel
 223                abort channel to asynchronously abort the adding process
 224         @param xCmdEnv
 225                command environment for error and progress handling
 226     */
 227     void reinstallDeployedPackages(
 228         [in] boolean force,
 229         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 230         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 231         raises (DeploymentException,
 232                 com::sun::star::ucb::CommandFailedException,
 233                 com::sun::star::ucb::CommandAbortedException,
 234                 com::sun::star::lang::IllegalArgumentException);
 235
 236     /** indicates that this implementation cannot be used for tasks
 237         which require write access to the location where the extensions
 238         are installed.
 239         <p>
 240         Normally one would call a method and handle the exception
 241         if writing failed. However, a GUI interface may need to know beforehand
 242         if writing is allowed. For example, the Extension Manager dialog
 243         needs to enable / disable the Add button depending if the user has
 244         write permission. Only the XPackageManager implementation knows the
 245         location of the installed extensions. Therefore it is not possible
 246         to check &quot;externally&quot; for write permission.
 247         </p>
 248     */
 249     boolean isReadOnly();
 250
 251     /** synchronizes the extension database with the contents of the extensions
 252        folder.
 253
 254        Added extensions will be added to the database and removed extensions
 255        will be removed from the database.
 256
 257        @param  xAbortChannel
 258                abort channel to asynchronously abort the adding process
 259        @param  xCmdEnv
 260                command environment for error and progress handling
 261
 262        @return
 263             If true - then at least one extension was removed or added. Otherwise
 264             nothing was changed.
 265     */
 266     boolean synchronize([in] com::sun::star::task::XAbortChannel xAbortChannel,
 267                      [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 268         raises (DeploymentException,
 269                 com::sun::star::ucb::ContentCreationException,
 270                 com::sun::star::ucb::CommandFailedException,
 271                 com::sun::star::ucb::CommandAbortedException);
 272
 273
 274     /** returns all extensions which are currently not in use
 275         because the user did not accept the license.
 276
 277         The function will not return any object for the user repository, because
 278         a user extension will not be kept in the user repository if its license
 279         is declined. Only extensions which are registered at start-up of OOo,
 280         that is, shared and bundled extensions, can be returned.
 281
 282         Extensions which allow the license to be suppressed, that is, it does not
 283         need to be displayed, and which are installed with the corresponding option,
 284         are also not returned.
 285     */
 286     sequence<XPackage> getExtensionsWithUnacceptedLicenses(
 287         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 288         raises (DeploymentException);
 289
 290     /** checks if the extension can be used.
 291
 292         The extension must be managed by this package manager, that is, it must
 293         be recorded in its database.  The package manager calls
 294         XPackage::checkPrerequisites and updates its data base with the
 295         result. The result, which is from Prerequisites will be
 296         returned.
 297      */
 298     long checkPrerequisites(
 299         [in] XPackage extension,
 300         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 301         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 302         raises (DeploymentException,
 303                 com::sun::star::ucb::CommandFailedException,
 304                 com::sun::star::ucb::CommandAbortedException,
 305                 com::sun::star::lang::IllegalArgumentException);
 306
 307 };
 308
 309 }; }; }; };
 310
 311 #endif
 312
 313 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */