offapi/com/sun/star/deployment/XExtensionManager.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_XExtensionManager_idl
  21 #define _com_sun_star_deployment_XExtensionManager_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 module com { module sun { module star { module deployment {
  35
  36 /** The XExtensionManager interface is used to manage extensions
  37     in the user, shared and bundled repository.
  38
  39     @see ExtensionManager
  40     @since OOo 3.3
  41 */
  42 interface XExtensionManager
  43 {
  44     /** interface to notify disposing
  45      */
  46     interface com::sun::star::lang::XComponent;
  47
  48     /** interface to notify changes of the set of deployed packages of
  49         this manager
  50     */
  51     interface com::sun::star::util::XModifyBroadcaster;
  52
  53
  54     /** gets the supported XPackageTypeInfos.
  55
  56         @return
  57                 supported XPackageTypeInfos.
  58     */
  59     sequence<XPackageTypeInfo> getSupportedPackageTypes();
  60
  61     /** creates a command channel to be used to asynchronously abort a command.
  62
  63         @return
  64                 abort channel
  65     */
  66     com::sun::star::task::XAbortChannel createAbortChannel();
  67
  68     /** adds an extension.
  69
  70         The properties argument is currently only used to suppress the license information
  71         for shared extensions.
  72
  73         @param url
  74                package URL, must be UCB conform
  75         @param properties
  76                additional properties, for example, that the license is to be
  77                suppressed (if supported by the extension)
  78         @param repository
  79                the name of the repository
  80         @param xAbortChannel
  81                abort channel to asynchronously abort the adding process,
  82                or null
  83         @param xCmdEnv
  84                command environment for error and progress handling
  85         @return
  86                object representing the extension.
  87     */
  88     XPackage addExtension( [in] string url,
  89                            [in] sequence<com::sun::star::beans::NamedValue> properties,
  90                            [in] string repository,
  91                            [in] com::sun::star::task::XAbortChannel xAbortChannel,
  92                            [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
  93         raises (DeploymentException,
  94                 com::sun::star::ucb::CommandFailedException,
  95                 com::sun::star::ucb::CommandAbortedException,
  96                 com::sun::star::lang::IllegalArgumentException);
  97
  98     /** removes an extension.
  99
 100         @param identifier
 101                package identifier
 102         @param fileName
 103                package file name
 104         @param repository
 105                the name of the repository
 106         @param xAbortChannel
 107                abort channel to asynchronously abort the removing process,
 108                or null
 109         @param xCmdEnv
 110                command environment for error and progress handling
 111     */
 112     void removeExtension(
 113         [in] string identifier,
 114         [in] string fileName,
 115         [in] string repository,
 116         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 117         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 118         raises (DeploymentException,
 119                 com::sun::star::ucb::CommandFailedException,
 120                 com::sun::star::ucb::CommandAbortedException,
 121                 com::sun::star::lang::IllegalArgumentException);
 122
 123
 124     /** enable an extension.
 125
 126         If the extension is not from the user repository then an
 127         IllegalArgumentException is thrown.
 128
 129         @param extension
 130                the extension which is to be enabled.
 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 enableExtension(
 138         [in] XPackage extension,
 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     /** disable an extension.
 147
 148         If the extension is not from the user repository then an
 149         IllegalArgumentException is thrown.
 150
 151         @param extension
 152                the extension which is to be disabled
 153         @param xAbortChannel
 154                abort channel to asynchronously abort the removing process,
 155                or null
 156         @param xCmdEnv
 157                command environment for error and progress handling
 158      */
 159     void  disableExtension(
 160         [in] XPackage extension,
 161         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 162         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 163         raises (DeploymentException,
 164                 com::sun::star::ucb::CommandFailedException,
 165                 com::sun::star::ucb::CommandAbortedException,
 166                 com::sun::star::lang::IllegalArgumentException);
 167
 168     /** gets all currently installed extensions, including disabled
 169         user extensions.
 170
 171         @param repository
 172                the repository from which the extensions are returned
 173         @param xAbortChannel
 174                abort channel to asynchronously abort the removing process,
 175                or null
 176         @param xCmdEnv
 177                command environment for error and progress handling
 178         @return
 179                all currently installed packages
 180     */
 181     sequence<XPackage> getDeployedExtensions(
 182         [in] string repository,
 183         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 184         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 185         raises (DeploymentException,
 186                 com::sun::star::ucb::CommandFailedException,
 187                 com::sun::star::ucb::CommandAbortedException,
 188                 com::sun::star::lang::IllegalArgumentException);
 189
 190
 191     /** gets an installed extensions.
 192
 193         @param repository
 194                the name of the repository
 195         @param identifier
 196                extension identifier
 197         @param fileName
 198                extension file name
 199         @param xCmdEnv
 200                command environment for error and progress handling
 201         @return
 202                XPackage object
 203     */
 204     XPackage getDeployedExtension(
 205         [in] string repository,
 206         [in] string identifier,
 207         [in] string fileName,
 208         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 209         raises (DeploymentException,
 210                 com::sun::star::ucb::CommandFailedException,
 211                 com::sun::star::lang::IllegalArgumentException);
 212
 213     /** gets all extensions with the same identifier from all repositories.
 214
 215         The extension at the first position in the returned sequence represents
 216         the extension from the user repository. The next element is from the shared
 217         and the last one is from the bundled repository.
 218         If one repository does not contain this extension, then the respective
 219         element is a null reference.
 220     */
 221     sequence<XPackage> getExtensionsWithSameIdentifier(
 222         [in] string identifier,
 223         [in] string fileName,
 224         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 225         raises (DeploymentException,
 226                 com::sun::star::ucb::CommandFailedException,
 227                 com::sun::star::lang::IllegalArgumentException);
 228
 229
 230     /** returns a sequence containing all installed extensions.
 231
 232         The members of the returned sequence correspond to an extension with a
 233         particular extension identifier. The members are also sequences which
 234         contain as many elements as there are repositories. Those are ordered
 235         according to the priority of the repository. That is, the first member
 236         is the extension from the user repository, the second is from the shared
 237         repository and the last is from the bundled repository.
 238      */
 239     sequence<sequence<XPackage> > getAllExtensions(
 240         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 241         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 242         raises (DeploymentException,
 243                 com::sun::star::ucb::CommandFailedException,
 244                 com::sun::star::ucb::CommandAbortedException,
 245                 com::sun::star::lang::IllegalArgumentException);
 246
 247
 248     /** Expert feature: erases the underlying registry cache and reinstalls
 249         all previously added extensions.  Please keep in mind that all
 250         registration status get lost.
 251         <p>
 252         Please use this in case of suspected cache inconsistencies only.
 253         </p>
 254         @param force
 255                set to true when called during soffice bootstrap after cleaning
 256                old extension cache
 257         @param repository
 258                the name of the repository
 259         @param xAbortChannel
 260                abort channel to asynchronously abort the adding process
 261         @param xCmdEnv
 262                command environment for error and progress handling
 263     */
 264     void reinstallDeployedExtensions(
 265         [in] boolean force,
 266         [in] string repository,
 267         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 268         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 269         raises (DeploymentException,
 270                 com::sun::star::ucb::CommandFailedException,
 271                 com::sun::star::ucb::CommandAbortedException,
 272                 com::sun::star::lang::IllegalArgumentException);
 273
 274
 275     /** synchronizes the extension database with the contents of the extensions
 276        folder of shared and bundled extensions.
 277
 278        Added extensions will be added to the database and removed extensions
 279        will be removed from the database.
 280        The active extensions are determined. That is, shared or bundled extensions
 281        are not necessaryly registered (XPackage::registerPackage()).
 282
 283        @return
 284               If true - then at least one extension was removed or added. Otherwise
 285               nothing was changed.
 286     */
 287     boolean synchronize(
 288         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 289         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 290         raises (DeploymentException,
 291                 com::sun::star::ucb::CommandFailedException,
 292                 com::sun::star::ucb::CommandAbortedException,
 293                 com::sun::star::lang::IllegalArgumentException);
 294
 295     /** returns all extensions which are currently not in use
 296         because the user did not accept the license.
 297
 298         The function will not return any object for the user repository, because
 299         a user extension will not be kept in the user repository if its license
 300         is declined. Only extensions which are registered at start-up of OOo,
 301         that is, shared and bundled extensions, can be returned.
 302
 303         Extensions which allow the license to be suppressed, that is, it does not
 304         need to be displayed, and which are installed with the corresponding option,
 305         are also not returned.
 306
 307         Extensions returned by these functions are not returned by
 308         XExtensionManager::getDeployedExtension()
 309         XExtensionManager::getDeployedExtensions()
 310         XExtensionManager::getAllExtensions()
 311         XExtensionManager::getExtensionsWithSameIdentifier()
 312     */
 313     sequence<XPackage> getExtensionsWithUnacceptedLicenses(
 314         [in] string repository,
 315         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 316         raises (DeploymentException,
 317                 com::sun::star::lang::IllegalArgumentException);
 318
 319     /** check if all prerequisites for the extension are fulfilled
 320         and activates it, if possible.
 321     */
 322     long checkPrerequisitesAndEnable(
 323         [in] XPackage extension,
 324         [in] com::sun::star::task::XAbortChannel xAbortChannel,
 325         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
 326         raises (DeploymentException,
 327                 com::sun::star::ucb::CommandFailedException,
 328                 com::sun::star::ucb::CommandAbortedException,
 329                 com::sun::star::lang::IllegalArgumentException);
 330
 331     /** determines if the current user has write access to the extensions folder
 332         of the repository.
 333     */
 334     boolean isReadOnlyRepository([in] string repository);
 335 };
 336
 337 }; }; }; };
 338
 339 #endif
 340
 341 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */