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