1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23
24#if ! defined INCLUDED_com_sun_star_deployment_XPackageRegistry_idl
25#define INCLUDED_com_sun_star_deployment_XPackageRegistry_idl
26
27#include <com/sun/star/deployment/XPackage.idl>
28#include <com/sun/star/deployment/XPackageTypeInfo.idl>
29#include <com/sun/star/deployment/InvalidRemovedParameterException.idl>
30#include <com/sun/star/beans/StringPair.idl>
31
32
33module com { module sun { module star { module deployment {
34
35/** Interface to bind an UNO package.
36
37    @since OpenOffice 2.0
38*/
39interface XPackageRegistry
40{
41    /** binds a package URL to a <type>XPackage</type> handle.
42        The returned UNO package handle ought to late-initialize itself,
43        thus the process of binding must not be an expensive operation, because
44        it is not abortable.
45
46        Calling the function several time with the same parameters must result
47        in returning the same object.
48
49        The file or folder at the location where url points to may not exist or
50        it was replaced. This can happen, for example, when a bundled extension
51        was removed by the setup and a user later starts OOo. Then the user data
52        may still contain all registration data of that extension, but the
53        actual extension files do not exist anymore. The registration data must
54        then be cleaned of all the remains of that extension. To to that one
55        creates an <type>XPackage</type> object on behalf of that extension and
56        calls <member>XPackage::revokePakage</member>. The parameter
57        <code>removed</code> indicates this case. The returned object may not
58        rely on the file or folder to which refers <code>url</url>. Instead it
59        must use previously saved data to successfully carry out the revocation
60        of this object (<member>XPackage::revokePackage</member>).
61
62        The implementation must ensure that there is only one instance of
63        <type>XPackage</type> for the same <code>url</code> at any
64        time. Therefore calling <member>bindPackage</member> again with the same
65        <code>url</code> but different <code>mediaType<code> (the exeption is,
66        if previsously an empty string was proveded to cause the determination
67        of the media type) or <code>removed</code> parameters will cause an
68        exception. An <type
69        scope="com::sun::star::lang">IllegalArgumentException</type> will be
70        thrown in case of a different <code>mediaType</code> parameter and a
71        <type>InvalidRemovedParameterException</type> is thrown if the
72        <code>removed</code> parameter is different.
73
74        The <code>identifier</code> parameter must be provided when
75        <code>removed</code> = true. If not, then an <type
76        scope="com::sun::star::lang">IllegalArgumentException</type> will be
77        thrown.
78
79        @param url
80               package URL, must be UCB conform
81        @param mediaType
82               media type of package, empty string if to be detected
83        @param removed
84
85        @para unfulfilledPrerequisites
86              has a value other null if the extension could not be installed previously
87              because <member>XPackage::checkPrerequisites</member> failed.
88
89        @param identifier
90               the identifier of the extension
91
92        @param xCmdEnv
93               command environment for error and progress handling
94        @return
95               <type>XPackage</type> handle
96    */
97    XPackage bindPackage(
98        [in] string url,
99        [in] string mediaType,
100        [in] boolean removed,
101        [in] string identifier,
102        [in] com::sun::star::ucb::XCommandEnvironment xCmdEnv )
103        raises (DeploymentException,
104                InvalidRemovedParameterException,
105                com::sun::star::ucb::CommandFailedException,
106                com::sun::star::lang::IllegalArgumentException);
107
108    /** gets the supported <type>XPackageTypeInfo</type>s.
109
110        @return
111                supported <type>XPackageTypeInfo</type>s.
112    */
113    sequence<XPackageTypeInfo> getSupportedPackageTypes();
114
115    void packageRemoved(
116        [in] string url,
117        [in] string mediaType)
118        raises (DeploymentException,
119                com::sun::star::lang::IllegalArgumentException);
120
121};
122
123}; }; }; };
124
125#endif
126