desktop/source/deployment/inc/dp_descriptioninfoset.hxx

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