path: root/offapi/com/sun/star/deployment/XPackageManager.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   Licensed to the Apache Software Foundation (ASF) under one or more
 *   contributor license agreements. See the NOTICE file distributed
 *   with this work for additional information regarding copyright
 *   ownership. The ASF licenses this file to you under the Apache
 *   License, Version 2.0 (the "License"); you may not use this file
 *   except in compliance with the License. You may obtain a copy of
 *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
 */

#ifndef _com_sun_star_deployment_XPackageManager_idl
#define _com_sun_star_deployment_XPackageManager_idl

#include <com/sun/star/lang/XComponent.idl>
#include <com/sun/star/task/XAbortChannel.idl>
#include <com/sun/star/util/XModifyBroadcaster.idl>
#include <com/sun/star/deployment/XPackage.idl>
#include <com/sun/star/deployment/XPackageTypeInfo.idl>
#include <com/sun/star/ucb/XCommandEnvironment.idl>
#include <com/sun/star/deployment/DeploymentException.idl>
#include <com/sun/star/container/NoSuchElementException.idl>
#include <com/sun/star/lang/IllegalArgumentException.idl>
#include <com/sun/star/beans/NamedValue.idl>


module com { module sun { module star { module deployment {

/** The XPackageManager interface is used to add or remove
    packages to a specific repository. This interface represents a particular
    repository.
    Packages are deployable files, e.g. scripts or UNO components.
    <p>
    Adding a UNO package means that a copy of the package is stored
    in the repository.
    </p>
    <p>
    Removing a UNO package means that the previously added package is
    removed from the repository.
    </p>
    <p>
    All interface methods do neither register nor revoke an extension.
    This happens exclusively by XExtensionManager.
    </p>
    <p>
    Objects of this interface are created using the
    XPackageManagerFactory service resp. the singleton
    <code>
    /singletons/com.sun.star.deployment.thePackageManagerFactory
    </code>.
    </p>

    @see thePackageManagerFactory
    @since OOo 2.0
    @deprecated
         Use XExtensionManager.
*/
interface XPackageManager
{
    /** interface to notify disposing
     */
    interface com::sun::star::lang::XComponent;

    /** interface to notify changes of the set of deployed packages of
        this manager
    */
    interface com::sun::star::util::XModifyBroadcaster;

    /** returns the underlying deployment context, that is,
        the name of the repository.

        @return
                underlying deployment context
    */
    string getContext();

    /** gets the supported XPackageTypeInfos.

        @return
                supported XPackageTypeInfos.
    */
    sequence<XPackageTypeInfo> getSupportedPackageTypes();

    /** creates a command channel to be used to asynchronously abort a command.

        @return
                abort channel
    */
    com::sun::star::task::XAbortChannel createAbortChannel();

    /** adds a UNO package.

        The properties argument is currently only used to suppress the license information
        for shared extensions.


        @param url
               package URL, must be UCB conform
        @param properties
               additional properties, for example, that the license is to be
               suppressed (if supported by the extension)
        @param mediaType
               media-type of package, empty string if to be detected
        @param xAbortChannel
               abort channel to asynchronously abort the adding process,
               or null
        @param xCmdEnv
               command environment for error and progress handling
        @return
               XPackage handle
    */
    XPackage addPackage( [in] string url,
                         [in] sequence<com::sun::star::beans::NamedValue> properties,
                         [in] string mediaType,
                         [in] com::sun::star::task::XAbortChannel xAbortChannel,
                         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException,
                com::sun::star::lang::IllegalArgumentException);

    /** adds an extension.

        This copies the extension. If it was from the same repository,
        which is represented by this XPackageManager interface, then
        nothing happens.

        @param extension

        @param xAbortChannel
               abort channel to asynchronously abort the adding process,
               or null
        @param xCmdEnv
               command environment for error and progress handling
        @return
               XPackage handle
    */
    XPackage importExtension( [in] XPackage extension,
                         [in] com::sun::star::task::XAbortChannel xAbortChannel,
                         [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException,
                com::sun::star::lang::IllegalArgumentException);

    /** removes a UNO package.

        @param identifier
               package identifier
        @param fileName
               package file name
        @param xAbortChannel
               abort channel to asynchronously abort the removing process,
               or null
        @param xCmdEnv
               command environment for error and progress handling
    */
    void removePackage( [in] string identifier,
                        [in] string fileName,
                        [in] com::sun::star::task::XAbortChannel xAbortChannel,
                        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException,
                com::sun::star::lang::IllegalArgumentException);

    /** gets a deployed package.

        @param identifier
               package identifier
        @param fileName
               package file name
        @param xCmdEnv
               command environment for error and progress handling
        @return
               XPackage handle
    */
    XPackage getDeployedPackage(
        [in] string identifier,
        [in] string fileName,
        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::lang::IllegalArgumentException);

    /** gets all currently deployed packages.

        @param xAbortChannel
               abort channel to asynchronously abort the removing process,
               or null
        @param xCmdEnv
               command environment for error and progress handling
        @return
                all currently deployed packages
    */
    sequence<XPackage> getDeployedPackages(
        [in] com::sun::star::task::XAbortChannel xAbortChannel,
        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException,
                com::sun::star::lang::IllegalArgumentException);

    /** Expert feature: erases the underlying registry cache and reinstalls
        all previously added packages.  Please keep in mind that all
        registration status get lost.
        <p>
        Please use this in case of suspected cache inconsistencies only.
        </p>

        @param force
               set to true when called during soffice bootstrap after cleaning
               old extension cache
        @param xAbortChannel
               abort channel to asynchronously abort the adding process
        @param xCmdEnv
               command environment for error and progress handling
    */
    void reinstallDeployedPackages(
        [in] boolean force,
        [in] com::sun::star::task::XAbortChannel xAbortChannel,
        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException,
                com::sun::star::lang::IllegalArgumentException);

    /** indicates that this implementation cannot be used for tasks
        which require write access to the location where the extensions
        are installed.
        <p>
        Normally one would call a method and handle the exception
        if writing failed. However, a GUI interface may need to know beforehand
        if writing is allowed. For example, the Extension Manager dialog
        needs to enable / disable the Add button depending if the user has
        write permission. Only the XPackageManager implementation knows the
        location of the installed extensions. Therefore it is not possible
        to check &quot;externally&quot; for write permission.
        </p>
    */
    boolean isReadOnly();

    /** synchronizes the extension database with the contents of the extensions
       folder.

       Added extensions will be added to the database and removed extensions
       will be removed from the database.

       @param  xAbortChannel
               abort channel to asynchronously abort the adding process
       @param  xCmdEnv
               command environment for error and progress handling

       @return
            If true - then at least one extension was removed or added. Otherwise
            nothing was changed.
    */
    boolean synchronize([in] com::sun::star::task::XAbortChannel xAbortChannel,
                     [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::ContentCreationException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException);


    /** returns all extensions which are currently not in use
        because the user did not accept the license.

        The function will not return any object for the user repository, because
        a user extension will not be kept in the user repository if its license
        is declined. Only extensions which are registered at start-up of OOo,
        that is, shared and bundled extensions, can be returned.

        Extensions which allow the license to be suppressed, that is, it does not
        need to be displayed, and which are installed with the corresponding option,
        are also not returned.
    */
    sequence<XPackage> getExtensionsWithUnacceptedLicenses(
        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException);

    /** checks if the extension can be used.

        The extension must be managed by this package manager, that is, it must
        be recorded in its database.  The package manager calls
        XPackage::checkPrerequisites and updates its data base with the
        result. The result, which is from Prerequisites will be
        returned.
     */
    long checkPrerequisites(
        [in] XPackage extension,
        [in] com::sun::star::task::XAbortChannel xAbortChannel,
        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
        raises (DeploymentException,
                com::sun::star::ucb::CommandFailedException,
                com::sun::star::ucb::CommandAbortedException,
                com::sun::star::lang::IllegalArgumentException);

};

}; }; }; };

#endif

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */