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