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