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         css::uno::Reference< css::uno::XComponentContext > const & context,
  76         css::uno::Reference< css::xml::dom::XNode > const & element);
  77
  78     ~DescriptionInfoset();
  79
  80     /**
  81        Return the identifier.
  82
  83        @return
  84        the identifier, or an empty <code>optional</code> if none is specified
  85     */
  86     ::boost::optional< OUString > getIdentifier() const;
  87
  88     /**
  89        Return the textual version representation.
  90
  91        @return
  92        textual version representation
  93     */
  94     OUString getVersion() const;
  95
  96     /**
  97         Returns a list of supported platforms.
  98
  99         If the extension does not specify a platform by leaving out the platform element
 100         then we assume that the extension supports all platforms. In this case the returned
 101         sequence will have one element, which is &quot;all&quot;.
 102         If the platform element is present but does not specify a platform then an empty
 103         sequence is returned. Examples for invalid platform elements:
 104         <pre>
 105             <platform />, <platform value="" />, <platform value=",">
 106         </pre>
 107
 108         The value attribute can contain various platform tokens. They must be separated by
 109         commas.Each token will be stripped from leading and trailing white space (trim()).
 110     */
 111     css::uno::Sequence< OUString > getSupportedPlatforms() const;
 112
 113     /**
 114         Returns the localized publisher name and the corresponding URL.
 115
 116         In case there is no publisher element then a pair of two empty strings is returned.
 117     */
 118     std::pair< OUString, OUString > getLocalizedPublisherNameAndURL() const;
 119
 120     /**
 121         Returns the URL for the release notes corresponding to the office's locale.
 122
 123         In case there is no release-notes element then an empty string is returned.
 124     */
 125     OUString getLocalizedReleaseNotesURL() const;
 126
 127     /** returns the relative path to the license file.
 128
 129         In case there is no simple-license element then an empty string is returned.
 130     */
 131     OUString getLocalizedLicenseURL() const;
 132
 133     /** returns the attributes of the simple-license element
 134
 135         As long as there is a simple-license element, the function will return
 136         the structure. If it does not exist, then the optional object is uninitialized.
 137     */
 138     ::boost::optional<SimpleLicenseAttributes> getSimpleLicenseAttributes() const;
 139
 140     /** returns the localized display name of the extensions.
 141
 142         In case there is no localized display-name then an empty string is returned.
 143     */
 144     OUString getLocalizedDisplayName() const;
 145
 146     /**
 147         returns the download website URL from the update information.
 148
 149         There can be multiple URLs where each is assigned to a particular locale.
 150         The function returns the URL which locale matches best the one used in the office.
 151
 152         The return value is an optional because it may be necessary to find out if there
 153         was a value provided or not. This is necessary to flag the extension in the update dialog
 154         properly as "browser based update". The return value will only then not be initialized
 155         if there is no <code>&lt;update-website&gt;</code>. If the element exists, then it must
 156         have at least one child element containing a URL.
 157
 158         The <code>&lt;update-website&gt;</code> and <code>&lt;update-download&gt;</code>
 159         elements are mutually exclusive.
 160
 161         @return
 162         the download website URL, or an empty <code>optional</code> if none is
 163         specified
 164     */
 165     ::boost::optional< OUString > getLocalizedUpdateWebsiteURL() const;
 166
 167     /** returns the relative URL to the description.
 168
 169        The URL is relative to the root directory of the extensions.
 170     */
 171     OUString getLocalizedDescriptionURL() const;
 172     /**
 173        Return the dependencies.
 174
 175        @return
 176        dependencies; will never be null
 177     */
 178     css::uno::Reference< css::xml::dom::XNodeList >
 179     getDependencies() const;
 180
 181     /**
 182        Return the update information URLs.
 183
 184        @return
 185        update information URLs
 186     */
 187     css::uno::Sequence< OUString > getUpdateInformationUrls() const;
 188
 189      /**
 190         Return the download URLs from the update information.
 191
 192         Because the <code>&lt;update-download&gt;</code> and the <code>&lt;update-website&gt;</code>
 193         elements are mutually exclusive one may need to determine exactly if the element
 194         was provided.
 195
 196         @return
 197         download URLs
 198      */
 199     css::uno::Sequence< OUString > getUpdateDownloadUrls() const;
 200
 201     /**
 202         Returns the URL for the icon image.
 203     */
 204     OUString getIconURL( bool bHighContrast ) const;
 205
 206     bool hasDescription() const;
 207
 208 private:
 209     SAL_DLLPRIVATE ::boost::optional< OUString > getOptionalValue(
 210         OUString const & expression) const;
 211
 212     SAL_DLLPRIVATE css::uno::Sequence< OUString > getUrls(
 213         OUString const & expression) const;
 214
 215     /** Retrieves a child element which as lang attribute which matches the office locale.
 216
 217         Only top-level children are taken into account. It is also assumed that they are all
 218         of the same element type and have a lang attribute. The matching algorithm is according
 219         to RFC 3066, with the exception that only one variant is allowed.
 220         @param parent
 221         the expression used to obtain the parent of the localized children. It can be null.
 222         Then a null reference is returned.
 223     */
 224     SAL_DLLPRIVATE css::uno::Reference< css::xml::dom::XNode >
 225         getLocalizedChild( OUString const & sParent) const;
 226     SAL_DLLPRIVATE  css::uno::Reference< css::xml::dom::XNode>
 227         matchLanguageTag(
 228         css::uno::Reference< css::xml::dom::XNode > const & xParent,
 229         OUString const & rTag) const;
 230
 231     /** If there is no child element with a locale matching the office locale, then we use
 232         the first child. In the case of the simple-license we also use the former default locale, which
 233         was determined by the default-license-id (/description/registration/simple-license/@default-license-id)
 234         and the license-id attributes (/description/registration/simple-license/license-text/@license-id).
 235         However, since OOo 2.4 we use also the first child as default for the license
 236         unless the two attributes are present.
 237     */
 238     SAL_DLLPRIVATE  css::uno::Reference< css::xml::dom::XNode>
 239         getChildWithDefaultLocale(
 240         css::uno::Reference< css::xml::dom::XNode > const & xParent) const;
 241     /**
 242         @param out_bParentExists
 243             indicates if the element node specified in sXPathParent exists.
 244     */
 245     SAL_DLLPRIVATE OUString getLocalizedHREFAttrFromChild(
 246         OUString const & sXPathParent, bool * out_bParentExists) const;
 247
 248     /** Gets the node value for a given expression. The expression is used in
 249         m_xpath-selectSingleNode. The value of the returned node is return value
 250         of this function.
 251     */
 252     SAL_DLLPRIVATE OUString
 253         getNodeValueFromExpression(OUString const & expression) const;
 254
 255     /** Check the extensions blacklist if additional extension meta data (e.g. dependencies)
 256         are defined for this extension and have to be taken into account.
 257     */
 258     SAL_DLLPRIVATE void
 259         checkBlacklist() const;
 260
 261     /** Helper method to compare the versions with the current version
 262      */
 263     SAL_DLLPRIVATE static bool
 264         checkBlacklistVersion(const OUString& currentversion,
 265                               css::uno::Sequence< OUString > const & versions);
 266
 267     css::uno::Reference< css::uno::XComponentContext > m_context;
 268     css::uno::Reference< css::xml::dom::XNode >        m_element;
 269     css::uno::Reference< css::xml::xpath::XXPathAPI >  m_xpath;
 270 };
 271
 272 inline  bool DescriptionInfoset::hasDescription() const
 273 {
 274     return m_element.is();
 275 }
 276
 277 /** creates a DescriptionInfoset object.
 278
 279     The argument sExtensionFolderURL is a file URL to extension folder containing
 280     the description.xml.
 281  */
 282 DESKTOP_DEPLOYMENTMISC_DLLPUBLIC
 283 DescriptionInfoset getDescriptionInfoset(OUString const & sExtensionFolderURL);
 284 }
 285
 286 #endif
 287
 288 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */