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