1 /*************************************************************************
2  *
3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4  *
5  * Copyright 2000, 2010 Oracle and/or its affiliates.
6  *
7  * OpenOffice.org - a multi-platform office productivity suite
8  *
9  * This file is part of OpenOffice.org.
10  *
11  * OpenOffice.org is free software: you can redistribute it and/or modify
12  * it under the terms of the GNU Lesser General Public License version 3
13  * only, as published by the Free Software Foundation.
14  *
15  * OpenOffice.org is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU Lesser General Public License version 3 for more details
19  * (a copy is included in the LICENSE file that accompanied this code).
20  *
21  * You should have received a copy of the GNU Lesser General Public License
22  * version 3 along with OpenOffice.org.  If not, see
23  * <http://www.openoffice.org/license.html>
24  * for a copy of the LGPLv3 License.
25  *
26  ************************************************************************/
27 
28 #ifndef INCLUDED_DESKTOP_SOURCE_DEPLOYMENT_INC_DP_DESCRIPTIONINFOSET_HXX
29 #define INCLUDED_DESKTOP_SOURCE_DEPLOYMENT_INC_DP_DESCRIPTIONINFOSET_HXX
30 
31 #include "sal/config.h"
32 
33 #include "boost/optional.hpp"
34 #include "com/sun/star/uno/Reference.hxx"
35 #include "com/sun/star/uno/Sequence.hxx"
36 #include "sal/types.h"
37 #include "dp_misc_api.hxx"
38 
39 /// @HTML
40 
41 namespace com { namespace sun { namespace star {
42     namespace lang { struct Locale; }
43     namespace uno { class XComponentContext; }
44     namespace xml {
45         namespace dom {
46             class XNode;
47             class XNodeList;
48         }
49         namespace xpath { class XXPathAPI; }
50     }
51 } } }
52 namespace rtl { class OUString; }
53 
54 namespace dp_misc {
55 
56 struct DESKTOP_DEPLOYMENTMISC_DLLPUBLIC SimpleLicenseAttributes
57 {
58     ::rtl::OUString acceptBy;
59     //Attribute suppress-on-update. Default is false.
60     bool suppressOnUpdate;
61     //Attribute suppress-if-required. Default is false.
62     bool suppressIfRequired;
63 };
64 
65 
66 /**
67    Access to the content of an XML <code>description</code> element.
68 
69    <p>This works for <code>description</code> elements in both the
70    <code>description.xml</code> file and online update information formats.</p>
71 */
72 class DESKTOP_DEPLOYMENTMISC_DLLPUBLIC DescriptionInfoset {
73 public:
74     /**
75        Create an instance.
76 
77        @param context
78        a non-null component context
79 
80        @param element
81        a <code>description</code> element; may be null (equivalent to an element
82        with no content)
83     */
84     DescriptionInfoset(
85         ::com::sun::star::uno::Reference<
86             ::com::sun::star::uno::XComponentContext > const & context,
87         ::com::sun::star::uno::Reference<
88             ::com::sun::star::xml::dom::XNode > const & element);
89 
90     ~DescriptionInfoset();
91 
92     /**
93        Return the identifier.
94 
95        @return
96        the identifier, or an empty <code>optional</code> if none is specified
97     */
98     ::boost::optional< ::rtl::OUString > getIdentifier() const;
99 
100     /**
101        Return the textual version representation.
102 
103        @return
104        textual version representation
105     */
106     ::rtl::OUString getVersion() const;
107 
108     /**
109         Returns a list of supported platforms.
110 
111         If the extension does not specify a platform by leaving out the platform element
112         then we assume that the extension supports all platforms. In this case the returned
113         sequence will have one element, which is &quot;all&quot;.
114         If the platform element is present but does not specify a platform then an empty
115         sequence is returned. Examples for invalid platform elements:
116         <pre>
117             <platform />, <platform value="" />, <platfrom value=",">
118         </pre>
119 
120         The value attribute can contain various platform tokens. They must be separated by
121         commas.Each token will be stripped from leading and trailing white space (trim()).
122     */
123     ::com::sun::star::uno::Sequence< ::rtl::OUString > getSupportedPlaforms() const;
124 
125     /**
126         Returns the localized publisher name and the corresponding URL.
127 
128         In case there is no publisher element then a pair of two empty strings is returned.
129     */
130     ::std::pair< ::rtl::OUString, ::rtl::OUString > getLocalizedPublisherNameAndURL() const;
131 
132     /**
133         Returns the URL for the release notes corresponding to the office's locale.
134 
135         In case there is no release-notes element then an empty string is returned.
136     */
137     ::rtl::OUString getLocalizedReleaseNotesURL() const;
138 
139     /** returns the relative path to the license file.
140 
141         In case there is no simple-license element then an empty string is returned.
142     */
143     ::rtl::OUString getLocalizedLicenseURL() const;
144 
145     /** returns the attributes of the simple-license element
146 
147         As long as there is a simple-license element, the function will return
148         the structure. If it does not exist, then the optional object is uninitialized.
149     */
150     ::boost::optional<SimpleLicenseAttributes> getSimpleLicenseAttributes() const;
151 
152     /** returns the localized display name of the extensions.
153 
154         In case there is no localized display-name then an empty string is returned.
155     */
156     ::rtl::OUString getLocalizedDisplayName() const;
157 
158     /**
159         returns the download website URL from the update information.
160 
161         There can be multiple URLs where each is assigned to a particular locale.
162         The function returs the URL which locale matches best the one used in the office.
163 
164         The return value is an optional because it may be necessary to find out if there
165         was a value provided or not. This is necessary to flag the extension in the update dialog
166         properly as "browser based update". The return value will only then not be initialized
167         if there is no <code>&lt;update-website&gt;</code>. If the element exists, then it must
168         have at least one child element containing an URL.
169 
170         The <code>&lt;update-website&gt;</code> and <code>&lt;update-download&gt;</code>
171         elements are mutually exclusiv.
172 
173         @return
174         the download website URL, or an empty <code>optional</code> if none is
175         specified
176     */
177     ::boost::optional< ::rtl::OUString > getLocalizedUpdateWebsiteURL() const;
178 
179     /** returns the relative URL to the description.
180 
181        The URL is relative to the root directory of the extensions.
182     */
183     ::rtl::OUString getLocalizedDescriptionURL() const;
184     /**
185        Return the dependencies.
186 
187        @return
188        dependencies; will never be null
189     */
190     ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNodeList >
191     getDependencies() const;
192 
193     /**
194        Return the update information URLs.
195 
196        @return
197        update information URLs
198     */
199     ::com::sun::star::uno::Sequence< ::rtl::OUString >
200     getUpdateInformationUrls() const;
201 
202      /**
203         Return the download URLs from the update information.
204 
205         Because the <code>&lt;update-download&gt;</code> and the <code>&lt;update-website&gt;</code>
206         elements are mutually exclusive one may need to determine exacty if the element
207         was provided.
208 
209         @return
210         download URLs
211      */
212     ::com::sun::star::uno::Sequence< ::rtl::OUString >
213     getUpdateDownloadUrls() const;
214 
215     /**
216         Returns the URL for the icon image.
217     */
218     ::rtl::OUString getIconURL( sal_Bool bHighContrast ) const;
219 
220     bool hasDescription() const;
221 
222 private:
223     SAL_DLLPRIVATE ::boost::optional< ::rtl::OUString > getOptionalValue(
224         ::rtl::OUString const & expression) const;
225 
226     SAL_DLLPRIVATE ::com::sun::star::uno::Sequence< ::rtl::OUString > getUrls(
227         ::rtl::OUString const & expression) const;
228 
229     /** Retrieves a child element which as lang attribute which matches the office locale.
230 
231         Only top-level children are taken into account. It is also assumed that they are all
232         of the same element type and have a lang attribute. The matching algoritm is according
233         to RFC 3066, with the exception that only one variant is allowed.
234         @param parent
235         the expression used to obtain the parent of the localized children. It can be null.
236         Then a null reference is returned.
237     */
238     SAL_DLLPRIVATE ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode >
239         getLocalizedChild( ::rtl::OUString const & sParent) const;
240     SAL_DLLPRIVATE  ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode>
241         matchFullLocale(::com::sun::star::uno::Reference<
242         ::com::sun::star::xml::dom::XNode > const & xParent, ::rtl::OUString const & sLocale) const;
243     SAL_DLLPRIVATE  ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode>
244         matchCountryAndLanguage(::com::sun::star::uno::Reference<
245         ::com::sun::star::xml::dom::XNode > const & xParent,
246         ::com::sun::star::lang::Locale const & officeLocale) const;
247     SAL_DLLPRIVATE  ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode>
248         matchLanguage(
249         ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode > const & xParent,
250         ::com::sun::star::lang::Locale const & officeLocale) const;
251 
252     /** If there is no child element with a locale matching the office locale, then we use
253         the first child. In the case of the simple-license we also use the former default locale, which
254         was determined by the default-license-id (/description/registration/simple-license/@default-license-id)
255         and the license-id attributes (/description/registration/simple-license/license-text/@license-id).
256         However, since OOo 2.4 we use also the first child as default for the license
257         unless the two attributes are present.
258     */
259     SAL_DLLPRIVATE  ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode>
260         getChildWithDefaultLocale(
261         ::com::sun::star::uno::Reference< ::com::sun::star::xml::dom::XNode > const & xParent) const;
262     /**
263         @param out_bParentExists
264             indicates if the element node specified in sXPathParent exists.
265     */
266     SAL_DLLPRIVATE ::rtl::OUString getLocalizedHREFAttrFromChild(
267         ::rtl::OUString const & sXPathParent, bool * out_bParentExists) const;
268 
269     static SAL_DLLPRIVATE ::rtl::OUString
270         localeToString(::com::sun::star::lang::Locale const & locale);
271 
272     /** Gets the node value for a given expression. The expression is used in
273         m_xpath-selectSingleNode. The value of the returned node is return value
274         of this function.
275     */
276     SAL_DLLPRIVATE ::rtl::OUString
277         getNodeValueFromExpression(::rtl::OUString const & expression) const;
278 
279     ::com::sun::star::uno::Reference<
280         ::com::sun::star::xml::dom::XNode > m_element;
281     ::com::sun::star::uno::Reference<
282         ::com::sun::star::xml::xpath::XXPathAPI > m_xpath;
283 };
284 
285 inline  bool DescriptionInfoset::hasDescription() const
286 {
287     return m_element.is();
288 }
289 
290 /** creates a DescriptionInfoset object.
291 
292     The argument sExtensionFolderURL is a file URL to extension folder containing
293     the description.xml.
294  */
295 DESKTOP_DEPLOYMENTMISC_DLLPUBLIC
296 DescriptionInfoset getDescriptionInfoset(::rtl::OUString const & sExtensionFolderURL);
297 }
298 
299 #endif
300