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