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