desktop/source/deployment/inc/dp_descriptioninfoset.hxx

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