include/unotools/configvaluecontainer.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 #ifndef INCLUDED_UNOTOOLS_CONFIGVALUECONTAINER_HXX
  20 #define INCLUDED_UNOTOOLS_CONFIGVALUECONTAINER_HXX
  21
  22 #include <config_options.h>
  23 #include <unotools/unotoolsdllapi.h>
  24 #include <com/sun/star/uno/Type.hxx>
  25 #include <memory>
  26 #include <mutex>
  27
  28
  29 namespace com::sun::star::uno { template <typename > class Reference; }
  30 namespace com::sun::star::uno { class XComponentContext; }
  31 namespace osl { class Mutex; }
  32
  33 namespace utl
  34 {
  35
  36     struct OConfigurationValueContainerImpl;
  37     struct NodeValueAccessor;
  38
  39     //= OConfigurationValueContainer
  40
  41     /** allows simple access to static configuration structures.
  42
  43         <p>The basic idea of this class is that it's clients (usually derived classes) simply register an
  44         address in memory and a node path, and upon explicit request, the configuration value and the memory
  45         are synchronized.<br/>
  46         This means that when calling <method>read</method>, the current configuration values are copied into
  47         the memory registered for them, and upon calling <method>write</method> the current values in memory
  48         are set in the configuration nodes.</p>
  49
  50         <p>This way, the usage of this class is pretty straight forward: derive your own class, spend some members
  51         to it, and bind these members to configuration node (usually done in the ctor of the derived class).<br/>
  52         In the dtor, simply call <method>write</method> and <method>commit</method>.</p>
  53
  54         <p>There is no auto-commit mechanism in the dtor: In the usual scenario, when you derive from this class
  55         and bind some members of your derived class to config nodes, this means that your members will be destroyed
  56         before your base class' dtor is called, so accessing the memory during such a theoretical auto-commit would
  57         yield undefined behaviour.</p>
  58     */
  59     class UNLESS_MERGELIBS(UNOTOOLS_DLLPUBLIC) OConfigurationValueContainer
  60     {
  61     private:
  62         std::unique_ptr<OConfigurationValueContainerImpl> m_pImpl;
  63
  64     protected:
  65
  66         // construction/destruction
  67
  68         /** constructs the object
  69
  70             @param _rxORB
  71                 specifies the service factory which should be used to access the configuration
  72             @param _rAccessSafety
  73                 As this class is intended to manipulate objects it does not hold itself (see the various
  74                 registerXXX methods), it needs to guard these access for multi threading safety.<br/>
  75                 The mutex given here is locked whenever such an access occurs.
  76             @param _rConfigLocation
  77                 is an ASCII string describing the configurations node path
  78             @param _nAccessFlags
  79                 specifies different aspects of the configuration aspect to be created, e.g. it's update mode etc.<br/>
  80                 See the CVC_xxx constants for what you can use here.
  81             @param _nLevels
  82                 specifies the number of levels to access under the node given by <arg>_pConfigLocation</arg>
  83         */
  84         OConfigurationValueContainer(
  85             const css::uno::Reference< css::uno::XComponentContext >& _rxORB,
  86             std::mutex& _rAccessSafety,
  87             const OUString& _rConfigLocation,
  88             const sal_Int32 _nLevels
  89         );
  90
  91         /// dtor
  92         ~OConfigurationValueContainer();
  93
  94         // registering data containers
  95
  96         /** registers a data accessor of an arbitrary type.
  97
  98             <p>Usually, in your derived class you simply add a member of the correct type of the configuration
  99             value, and then call this method with the address of this member.</p>
 100
 101             @param _rRelativePathAscii
 102                 is a relative (ASCII) path of the node which should be "mirrored" into the accessor.
 103             @param _pContainer
 104                 points to the accessors location in memory. Usually, this is simply an address of your derived class
 105             @param _rValueType
 106                 is the type of your accessor. This type must be supported by the configuration.
 107         */
 108         void    registerExchangeLocation(
 109             const OUString& _rRelativePathAscii,
 110             void* _pContainer,
 111             const css::uno::Type& _rValueType
 112         );
 113
 114     public:
 115         /** reads the configuration data
 116
 117             <p>The current values of the nodes bound (using the registerXXX methods) is copied into their
 118             respective exchange locations.</p>
 119
 120             <p>Please note that any changes done to your exchange locations are overridden with the current config
 121             values.</p>
 122
 123             @see write
 124         */
 125         void    read( );
 126
 127         /** commits any changes done
 128
 129             <p>Note that calling <method>write</method>(<sal_True/) is the same as calling <method>commit</method>(<TRUE/>).</p>
 130
 131             The current values in the exchange locations are written to the configuration nodes
 132             before the changes are committed.<br/>
 133
 134             @precond
 135                 The access must have been created for update access
 136         */
 137         void    commit();
 138
 139     private:
 140         /// implements the ctors
 141         void implConstruct(
 142             const OUString& _rConfigLocation,
 143             const sal_Int32 _nLevels
 144         );
 145
 146         /// registers a value container
 147         void    implRegisterExchangeLocation( const NodeValueAccessor& _rAccessor );
 148     };
 149
 150 }   // namespace utl
 151
 152 #endif // INCLUDED_UNOTOOLS_CONFIGVALUECONTAINER_HXX
 153
 154 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */