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

/*************************************************************************
 *
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 * 
 * Copyright 2000, 2010 Oracle and/or its affiliates.
 *
 * OpenOffice.org - a multi-platform office productivity suite
 *
 * This file is part of OpenOffice.org.
 *
 * OpenOffice.org is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3
 * only, as published by the Free Software Foundation.
 *
 * OpenOffice.org is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License version 3 for more details
 * (a copy is included in the LICENSE file that accompanied this code).
 *
 * You should have received a copy of the GNU Lesser General Public License
 * version 3 along with OpenOffice.org.  If not, see
 * <http://www.openoffice.org/license.html>
 * for a copy of the LGPLv3 License.
 *
 ************************************************************************/

#if ! defined INCLUDED_com_sun_star_deployment_XPackageManager_idl
#define INCLUDED_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 <type>XPackageManager</type> 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 an UNO package means that a copy of the package is stored
    in the repository.
    </p>
    <p>
    Removing an 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 <type>XExtensionManager</type>.
    </p>
    <p>
    Objects of this interface are created using the
    <type>XPackageManagerFactory</type> service resp. the singleton
    <code>
    /singletons/com.sun.star.deployment.thePackageManagerFactory
    </code>.
    </p>

    @see thePackageManagerFactory
    @since OOo 2.0
    @deprecated
         Use <type>XExtensionManager</type>.
*/
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 <type>XPackageTypeInfo</type>s.
        
        @return
                supported <type>XPackageTypeInfo</type>s.
    */
    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 an 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
               <type>XPackage</type> 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
               <type>XPackage</type> 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 an 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
               <type>XPackage</type> 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 xAbortChannel
               abort channel to asynchronously abort the adding process
        @param xCmdEnv
               command environment for error and progress handling
    */
    void reinstallDeployedPackages(
        [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 xAddedExtension
            new extensions which may need to be registered.

       @param
            removed extensions which must be revoked
       @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::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 <type>Prerequisites</type> 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