/*************************************************************************
 *
 *  OpenOffice.org - a multi-platform office productivity suite
 *
 *  $RCSfile: XPackageManager.idl,v $
 *
 *  $Revision: 1.7 $
 *
 *  last change: $Author: rt $ $Date: 2005/09/07 22:58:36 $
 *
 *  The Contents of this file are made available subject to
 *  the terms of GNU Lesser General Public License Version 2.1.
 *
 *
 *    GNU Lesser General Public License Version 2.1
 *    =============================================
 *    Copyright 2005 by Sun Microsystems, Inc.
 *    901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License version 2.1, as published by the Free Software Foundation.
 *
 *    This library 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 for more details.
 *
 *    You should have received a copy of the GNU Lesser General Public
 *    License along with this library; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *    MA  02111-1307  USA
 *
 ************************************************************************/

#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>


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

/** The <type>XPackageManager</type> interface is used to add or remove
    packages to a specific deployment context.
    Packages are deployable files, e.g. scripts or UNO components.
    <p>
    Adding an UNO package means that a copy of the package is stored
    with respect to the context of the manager and the package is registered,
    thus activated.
    </p>
    <p>
    Removing an UNO package means that the previously added package is revoked,
    thus deactivated, first and then removed from the context.
    </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.0
*/
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.

        @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.
        
        @param url
               package URL, must be UCB conform
        @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] 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);
    
    /** removes an UNO package.
        
        @param name
               package name (not URL)
        @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 name,
                        [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 name
               package name (an URL is NOT allowed!)
        @param xCmdEnv
               command environment for error and progress handling
        @return
               <type>XPackage</type> handle
    */
    XPackage getDeployedPackage(
        [in] string name,
        [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);
};

}; }; }; };

#endif
