include/comphelper/configuration.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
  10 #ifndef INCLUDED_COMPHELPER_CONFIGURATION_HXX
  11 #define INCLUDED_COMPHELPER_CONFIGURATION_HXX
  12
  13 #include <sal/config.h>
  14
  15 #include <optional>
  16 #include <string_view>
  17
  18 #include <com/sun/star/uno/Any.hxx>
  19 #include <com/sun/star/uno/Reference.h>
  20 #include <comphelper/comphelperdllapi.h>
  21 #include <comphelper/processfactory.hxx>
  22 #include <sal/types.h>
  23 #include <memory>
  24
  25 namespace com::sun::star {
  26     namespace configuration { class XReadWriteAccess; }
  27     namespace container {
  28         class XHierarchicalNameAccess;
  29         class XHierarchicalNameReplace;
  30         class XNameAccess;
  31         class XNameContainer;
  32     }
  33     namespace uno { class XComponentContext; }
  34 }
  35
  36 namespace comphelper {
  37
  38 namespace detail { class ConfigurationWrapper; }
  39
  40 /// A batch of configuration changes that is committed as a whole.
  41 ///
  42 /// Client code needs to call commit explicitly; otherwise the changes are lost
  43 /// when the instance is destroyed.
  44 ///
  45 /// This is the only class from this header file that client code should use
  46 /// directly.
  47 class COMPHELPER_DLLPUBLIC ConfigurationChanges {
  48 public:
  49     static std::shared_ptr<ConfigurationChanges> create(
  50         css::uno::Reference<css::uno::XComponentContext> const & context
  51             = css::uno::Reference<css::uno::XComponentContext>());
  52
  53     ~ConfigurationChanges();
  54
  55     void commit() const;
  56
  57 private:
  58     ConfigurationChanges(const ConfigurationChanges&) = delete;
  59     ConfigurationChanges& operator=(const ConfigurationChanges&) = delete;
  60
  61     SAL_DLLPRIVATE ConfigurationChanges(
  62         css::uno::Reference< css::uno::XComponentContext >
  63             const & context);
  64
  65     SAL_DLLPRIVATE void setPropertyValue(
  66         OUString const & path, css::uno::Any const & value)
  67         const;
  68
  69     SAL_DLLPRIVATE css::uno::Reference<
  70         css::container::XHierarchicalNameReplace >
  71     getGroup(OUString const & path) const;
  72
  73     SAL_DLLPRIVATE
  74     css::uno::Reference< css::container::XNameContainer >
  75     getSet(OUString const & path) const;
  76
  77     css::uno::Reference<
  78         css::configuration::XReadWriteAccess > access_;
  79
  80     friend class detail::ConfigurationWrapper;
  81 };
  82
  83 namespace detail {
  84
  85 /// @internal
  86 class COMPHELPER_DLLPUBLIC ConfigurationWrapper {
  87 public:
  88     static ConfigurationWrapper const & get(
  89         css::uno::Reference<css::uno::XComponentContext> const & context);
  90
  91     bool isReadOnly(OUString const & path) const;
  92
  93     css::uno::Any getPropertyValue(std::u16string_view path) const;
  94
  95     static void setPropertyValue(
  96         std::shared_ptr< ConfigurationChanges > const & batch,
  97         OUString const & path, css::uno::Any const & value);
  98
  99     css::uno::Any getLocalizedPropertyValue(
 100         std::u16string_view path) const;
 101
 102     static void setLocalizedPropertyValue(
 103         std::shared_ptr< ConfigurationChanges > const & batch,
 104         OUString const & path, css::uno::Any const & value);
 105
 106     css::uno::Reference<
 107         css::container::XHierarchicalNameAccess >
 108     getGroupReadOnly(OUString const & path) const;
 109
 110     static css::uno::Reference<
 111         css::container::XHierarchicalNameReplace >
 112     getGroupReadWrite(
 113         std::shared_ptr< ConfigurationChanges > const & batch,
 114         OUString const & path);
 115
 116     css::uno::Reference< css::container::XNameAccess >
 117     getSetReadOnly(OUString const & path) const;
 118
 119     static css::uno::Reference< css::container::XNameContainer >
 120     getSetReadWrite(
 121         std::shared_ptr< ConfigurationChanges > const & batch,
 122         OUString const & path);
 123
 124     std::shared_ptr< ConfigurationChanges > createChanges() const;
 125
 126 private:
 127     SAL_DLLPRIVATE explicit ConfigurationWrapper(
 128         css::uno::Reference<css::uno::XComponentContext> const & context);
 129
 130     SAL_DLLPRIVATE ~ConfigurationWrapper();
 131
 132     ConfigurationWrapper(const ConfigurationWrapper&) = delete;
 133     ConfigurationWrapper& operator=(const ConfigurationWrapper&) = delete;
 134
 135     css::uno::Reference< css::uno::XComponentContext >          context_;
 136
 137     css::uno::Reference< css::configuration::XReadWriteAccess > access_;
 138         // should really be a css.configuration.ReadOnlyAccess (with added
 139         // css.beans.XHierarchicalPropertySetInfo), but then
 140         // configmgr::Access::asProperty() would report all properties as
 141         // READONLY, so isReadOnly() would not work
 142 };
 143
 144 /// @internal
 145 template< typename T > struct Convert {
 146     static css::uno::Any toAny(T const & value)
 147     { return css::uno::Any(value); }
 148
 149     static T fromAny(css::uno::Any const & value)
 150     { return value.get< T >(); }
 151
 152 private:
 153     Convert(const Convert&) = delete;
 154     Convert& operator=(const Convert&) = delete;
 155
 156     Convert() = delete;
 157     ~Convert() = delete;
 158 };
 159
 160 /// @internal
 161 template< typename T > struct Convert< std::optional< T > >
 162 {
 163     static css::uno::Any toAny(std::optional< T > const & value) {
 164         return value
 165             ? css::uno::Any(*value)
 166             : css::uno::Any();
 167     }
 168
 169     static std::optional< T > fromAny(css::uno::Any const & value)
 170     {
 171         return value.hasValue()
 172             ? std::optional< T >(value.get< T >()) : std::optional< T >();
 173     }
 174
 175 private:
 176     Convert(const Convert&) = delete;
 177     Convert& operator=(const Convert&) = delete;
 178
 179     Convert() = delete;
 180     ~Convert() = delete;
 181 };
 182
 183 }
 184
 185 // Avoid using the config layer and rely on defaults which is only useful
 186 // for special test tool targets (typically fuzzing) where start-up speed
 187 // is of the essence
 188 #if defined(FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION)
 189 constexpr bool IsFuzzing() { return true; }
 190 #else
 191 COMPHELPER_DLLPUBLIC bool IsFuzzing();
 192 #endif
 193 COMPHELPER_DLLPUBLIC void EnableFuzzing();
 194
 195 /// A type-safe wrapper around a (non-localized) configuration property.
 196 ///
 197 /// Automatically generated headers for the various configuration properties
 198 /// derive from this template and make available its member functions to access
 199 /// each given configuration property.
 200 template< typename T, typename U > struct ConfigurationProperty
 201 {
 202     /// Get the read-only status of the given (non-localized) configuration
 203     /// property.
 204     static bool isReadOnly(
 205         css::uno::Reference<css::uno::XComponentContext> const & context
 206             = css::uno::Reference<css::uno::XComponentContext>())
 207     {
 208         return detail::ConfigurationWrapper::get(context).isReadOnly(T::path());
 209     }
 210
 211     /// Get the value of the given (non-localized) configuration property.
 212     ///
 213     /// For nillable properties, U is of type std::optional<U'>.
 214     static U get(
 215         css::uno::Reference<css::uno::XComponentContext> const & context
 216             = css::uno::Reference<css::uno::XComponentContext>())
 217     {
 218         if (comphelper::IsFuzzing())
 219             return U();
 220         // Folding this into one statement causes a bogus error at least with
 221         // Red Hat GCC 4.6.2-1:
 222         css::uno::Any a(
 223             detail::ConfigurationWrapper::get(context).getPropertyValue(
 224                 T::path()));
 225         return detail::Convert< U >::fromAny(a);
 226     }
 227
 228     /// Set the value of the given (non-localized) configuration property, via a
 229     /// given changes batch.
 230     ///
 231     /// For nillable properties, U is of type std::optional<U'>.
 232     static void set(
 233         U const & value,
 234         std::shared_ptr< ConfigurationChanges > const & batch)
 235     {
 236         comphelper::detail::ConfigurationWrapper::setPropertyValue(
 237             batch, T::path(), detail::Convert< U >::toAny(value));
 238     }
 239
 240 private:
 241     ConfigurationProperty(const ConfigurationProperty&) = delete;
 242     ConfigurationProperty& operator=(const ConfigurationProperty&) = delete;
 243
 244     ConfigurationProperty() = delete;
 245     ~ConfigurationProperty() = delete;
 246 };
 247
 248 /// A type-safe wrapper around a localized configuration property.
 249 ///
 250 /// Automatically generated headers for the various localized configuration
 251 /// properties derive from this template and make available its member functions
 252 /// to access each given localized configuration property.
 253 template< typename T, typename U > struct ConfigurationLocalizedProperty
 254 {
 255     /// Get the read-only status of the given (localized) configuration
 256     /// property.
 257     static bool isReadOnly(
 258         css::uno::Reference<css::uno::XComponentContext> const & context
 259             = css::uno::Reference<css::uno::XComponentContext>())
 260     {
 261         return detail::ConfigurationWrapper::get(context).isReadOnly(T::path());
 262     }
 263
 264     /// Get the value of the given localized configuration property, for the
 265     /// locale currently set at the
 266     /// com.sun.star.configuration.theDefaultProvider.
 267     ///
 268     /// For nillable properties, U is of type std::optional<U'>.
 269     static U get(
 270         css::uno::Reference<css::uno::XComponentContext> const & context
 271             = css::uno::Reference<css::uno::XComponentContext>())
 272     {
 273         // Folding this into one statement causes a bogus error at least with
 274         // Red Hat GCC 4.6.2-1:
 275         css::uno::Any a(
 276             detail::ConfigurationWrapper::get(context).
 277             getLocalizedPropertyValue(T::path()));
 278         return detail::Convert< U >::fromAny(a);
 279     }
 280
 281     /// Set the value of the given localized configuration property, for the
 282     /// locale currently set at the
 283     /// com.sun.star.configuration.theDefaultProvider, via a given changes
 284     /// batch.
 285     ///
 286     /// For nillable properties, U is of type std::optional<U'>.
 287     static void set(
 288         U const & value,
 289         std::shared_ptr< ConfigurationChanges > const & batch)
 290     {
 291         comphelper::detail::ConfigurationWrapper::setLocalizedPropertyValue(
 292             batch, T::path(), detail::Convert< U >::toAny(value));
 293     }
 294
 295 private:
 296     ConfigurationLocalizedProperty(const ConfigurationLocalizedProperty&) = delete;
 297     ConfigurationLocalizedProperty& operator=(const ConfigurationLocalizedProperty&) = delete;
 298
 299     ConfigurationLocalizedProperty() = delete;
 300     ~ConfigurationLocalizedProperty() = delete;
 301 };
 302
 303 /// A type-safe wrapper around a configuration group.
 304 ///
 305 /// Automatically generated headers for the various configuration groups derive
 306 /// from this template and make available its member functions to access each
 307 /// given configuration group.
 308 template< typename T > struct ConfigurationGroup {
 309     /// Get the read-only status of the given configuration group.
 310     static bool isReadOnly(
 311         css::uno::Reference<css::uno::XComponentContext> const & context
 312             = css::uno::Reference<css::uno::XComponentContext>())
 313     {
 314         return detail::ConfigurationWrapper::get(context).isReadOnly(T::path());
 315     }
 316
 317     /// Get read-only access to the given configuration group.
 318     static css::uno::Reference<
 319         css::container::XHierarchicalNameAccess >
 320     get(css::uno::Reference<css::uno::XComponentContext> const & context
 321             = css::uno::Reference<css::uno::XComponentContext>())
 322     {
 323         return detail::ConfigurationWrapper::get(context).getGroupReadOnly(
 324             T::path());
 325     }
 326
 327     /// Get read/write access to the given configuration group, storing any
 328     /// modifications via the given changes batch.
 329     static css::uno::Reference<
 330         css::container::XHierarchicalNameReplace >
 331     get(std::shared_ptr< ConfigurationChanges > const & batch)
 332     {
 333         return comphelper::detail::ConfigurationWrapper::getGroupReadWrite(
 334             batch, T::path());
 335     }
 336
 337 private:
 338     ConfigurationGroup(const ConfigurationGroup&) = delete;
 339     ConfigurationGroup& operator=(const ConfigurationGroup&) = delete;
 340
 341     ConfigurationGroup() = delete;
 342     ~ConfigurationGroup() = delete;
 343 };
 344
 345 /// A type-safe wrapper around a configuration set.
 346 ///
 347 /// Automatically generated headers for the various configuration sets derive
 348 /// from this template and make available its member functions to access each
 349 /// given configuration set.
 350 template< typename T > struct ConfigurationSet {
 351     /// Get the read-only status of the given configuration set.
 352     static bool isReadOnly(
 353         css::uno::Reference<css::uno::XComponentContext> const & context
 354             = css::uno::Reference<css::uno::XComponentContext>())
 355     {
 356         return detail::ConfigurationWrapper::get(context).isReadOnly(T::path());
 357     }
 358
 359     /// Get read-only access to the given configuration set.
 360     static
 361     css::uno::Reference< css::container::XNameAccess >
 362     get(css::uno::Reference<css::uno::XComponentContext> const & context
 363             = css::uno::Reference<css::uno::XComponentContext>())
 364     {
 365         return detail::ConfigurationWrapper::get(context).getSetReadOnly(
 366             T::path());
 367     }
 368
 369     /// Get read/write access to the given configuration set, storing any
 370     /// modifications via the given changes batch.
 371     static
 372     css::uno::Reference< css::container::XNameContainer >
 373     get(std::shared_ptr< ConfigurationChanges > const & batch)
 374     {
 375         return comphelper::detail::ConfigurationWrapper::getSetReadWrite(
 376             batch, T::path());
 377     }
 378
 379 private:
 380     ConfigurationSet(const ConfigurationSet&) = delete;
 381     ConfigurationSet& operator=(const ConfigurationSet&) = delete;
 382
 383     ConfigurationSet() = delete;
 384     ~ConfigurationSet() = delete;
 385 };
 386
 387 }
 388
 389 #endif
 390
 391 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */