include/comphelper/configurationhelper.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_COMPHELPER_CONFIGURATIONHELPER_HXX
  21 #define INCLUDED_COMPHELPER_CONFIGURATIONHELPER_HXX
  22
  23 #include <com/sun/star/uno/Reference.h>
  24 #include <com/sun/star/uno/Any.hxx>
  25 #include <rtl/ustring.hxx>
  26 #include <comphelper/comphelperdllapi.h>
  27 #include <o3tl/typed_flags_set.hxx>
  28
  29 namespace com::sun::star::uno { class XComponentContext; }
  30 namespace com::sun::star::uno { class XInterface; }
  31
  32 namespace comphelper
  33 {
  34     /** specify all possible modes, which can be used to open a configuration access.
  35      *
  36      *  @see    openConfig()
  37      *  @see    readDirectKey()
  38      *  @see    writeDirectKey()
  39      */
  40     enum class EConfigurationModes
  41     {
  42         /// opens configuration in read/write mode (without LAZY writing!)
  43         Standard = 0,
  44         /// configuration will be opened readonly
  45         ReadOnly = 1,
  46         /// all localized nodes will be interpreted as XInterface instead of interpreting it as atomic value nodes
  47         AllLocales = 2
  48     };
  49
  50
  51 }
  52
  53 namespace o3tl
  54 {
  55     template<> struct typed_flags<comphelper::EConfigurationModes> : is_typed_flags<comphelper::EConfigurationModes, 0x3> {};
  56 }
  57
  58 namespace comphelper
  59 {
  60
  61 class COMPHELPER_DLLPUBLIC ConfigurationHelper
  62 {
  63 public:
  64     /** returns access to the specified configuration package.
  65      *
  66      *  This method should be used, if e.g. more than one request to the same
  67      *  configuration package is needed. The configuration access can be cached
  68      *  outside and used inbetween.
  69      *
  70      *  @param  rxContext
  71      *          the uno service manager, which should be used to create the
  72      *          configuration access.
  73      *
  74      *  @param  sPackage
  75      *          the name of the configuration package.
  76      *          e.g. <ul>
  77      *                  <li>org.openoffice.Office.Common</li>
  78      *                  <li>org.openoffice.Office.Common/Menu</li>
  79      *               </ul>
  80      *
  81      *  @param  eMode
  82      *          specify the open mode for the returned configuration access.
  83      *          It's interpreted as a flag field and can be any useful combination
  84      *          of values of EConfigurationModes.
  85      *
  86      *  @throw  Any exceptions the underlying configuration can throw.
  87      *          E.g. css::uno::Exception if the configuration could not be opened.
  88      */
  89     static css::uno::Reference< css::uno::XInterface > openConfig(const css::uno::Reference< css::uno::XComponentContext >& rxContext,
  90                                                                   const OUString&                                           sPackage,
  91                                                                         EConfigurationModes                                 eMode   );
  92
  93
  94     /** reads the value of an existing(!) configuration key,
  95      *  which is searched relative to the specified configuration access.
  96      *
  97      *  This method must be used in combination with openConfig().
  98      *  The cached configuration access must be provided here ... and
  99      *  all operations are made relative to this access point.
 100      *
 101      *  @param  xCFG
 102      *          the configuration root, where sRelPath should be interpreted.
 103      *          as relative path
 104      *
 105      *  @param  sRelPath
 106      *          path relative to xCFG parameter.
 107      *
 108      *  @param  sKey
 109      *          the configuration node, where we should read the value.
 110      *
 111      *  @return [css.uno.Any]
 112      *          the value of sKey.
 113      *
 114      *  @throw  Any exceptions the underlying configuration can throw.
 115      *          E.g. css::container::NoSuchElementException if the specified
 116      *          key does not exists.
 117      */
 118     static css::uno::Any readRelativeKey(const css::uno::Reference< css::uno::XInterface >& xCFG    ,
 119                                          const OUString&                            sRelPath,
 120                                          const OUString&                            sKey    );
 121
 122
 123     /** writes a new value for an existing(!) configuration key,
 124      *  which is searched relative to the specified configuration access.
 125      *
 126      *  This method must be used in combination with openConfig().
 127      *  The cached configuration access must be provided here ... and
 128      *  all operations are made relative to this access point.
 129      *
 130      *  @param  xCFG
 131      *          the configuration root, where sRelPath should be interpreted.
 132      *          as relative path
 133      *
 134      *  @param  sRelPath
 135      *          path relative to xCFG parameter.
 136      *
 137      *  @param  sKey
 138      *          the configuration node, where we should write the new value.
 139      *
 140      *  @param  aValue
 141      *          the new value for sKey.
 142      *
 143      *  @throw  Any exceptions the underlying configuration can throw.
 144      *          E.g. css::container::NoSuchElementException if the specified
 145      *          key does not exists or css::uno::Exception if the provided configuration
 146      *          access does not allow writing for this key.
 147      */
 148     static void writeRelativeKey(const css::uno::Reference< css::uno::XInterface >& xCFG    ,
 149                                  const OUString&                            sRelPath,
 150                                  const OUString&                            sKey    ,
 151                                  const css::uno::Any&                              aValue  );
 152
 153
 154     /** it checks if the specified set node exists ... or create an empty one
 155      *  otherwise.
 156      *
 157      *  This method must be used in combination with openConfig().
 158      *  The cached configuration access must be provided here ... and
 159      *  all operations are made relative to this access point.
 160      *
 161      *  Further this method must be used only with configuration set's.
 162      *  Atomic keys can't be "created"... they "exist every time".
 163      *
 164      *  @param  xCFG
 165      *          the configuration root, where sRelPathToSet should be interpreted
 166      *          as relative path.
 167      *
 168      *  @param  sRelPathToSet
 169      *          path relative to xCFG parameter.
 170      *
 171      *  @param  sSetNode
 172      *          the set node, which should be checked if it exists...
 173      *          or which should be created with default values.
 174      *
 175      *  @return A reference to the found (or new created) set node.
 176      *          Can't be NULL .. in such case an exception occurs!
 177      *
 178      *  @throw  Any exceptions the underlying configuration can throw.
 179      *          E.g. css::uno::Exception if the provided configuration
 180      *          access does not allow writing for this set.
 181      */
 182     static css::uno::Reference< css::uno::XInterface > makeSureSetNodeExists(const css::uno::Reference< css::uno::XInterface >& xCFG         ,
 183                                                                              const OUString&                            sRelPathToSet,
 184                                                                              const OUString&                            sSetNode     );
 185
 186
 187     /** commit all changes made on the specified configuration access.
 188      *
 189      *  This method must be used in combination with openConfig().
 190      *  The cached configuration access must be provided here.
 191      *
 192      *  @param  xCFG
 193      *          the configuration root, where changes should be committed.
 194      *
 195      *  @throw  Any exceptions the underlying configuration can throw.
 196      *          E.g. css::uno::Exception if the provided configuration
 197      *          access does not allow writing for this set.
 198      */
 199     static void flush(const css::uno::Reference< css::uno::XInterface >& xCFG);
 200
 201
 202     /** does the same then openConfig() & readRelativeKey() together.
 203      *
 204      * This method should be used for reading one key at one code place only.
 205      * Because it opens the specified configuration package, reads the key and
 206      * closes the configuration again.
 207      *
 208      * So it's not very useful to use this method for reading multiple keys at the same time.
 209      * (Excepting these keys exists inside different configuration packages ...))
 210      */
 211     static css::uno::Any readDirectKey(const css::uno::Reference< css::uno::XComponentContext >&    rxContext,
 212                                        const OUString&                                       sPackage,
 213                                        const OUString&                                       sRelPath,
 214                                        const OUString&                                       sKey    ,
 215                                              EConfigurationModes                             eMode   );
 216
 217
 218     /** does the same then openConfig() / writeRelativeKey() & flush() together.
 219      *
 220      * This method should be used for writing one key at one code place only.
 221      * Because it opens the specified configuration package, writes the key, flush
 222      * all changes and closes the configuration again.
 223      *
 224      * So it's not very useful to use this method for writing multiple keys at the same time.
 225      * (Excepting these keys exists inside different configuration packages ...))
 226      */
 227     static void writeDirectKey(const css::uno::Reference< css::uno::XComponentContext >&    rxContext,
 228                                const OUString&                                       sPackage,
 229                                const OUString&                                       sRelPath,
 230                                const OUString&                                       sKey    ,
 231                                const css::uno::Any&                                  aValue  ,
 232                                      EConfigurationModes                             eMode   );
 233 };
 234
 235 } // namespace comphelper
 236
 237 #endif // INCLUDED_COMPHELPER_CONFIGURATIONHELPER_HXX
 238
 239 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */