extensions/source/oooimprovement/myconfigurationhelper.hxx

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: myconfigurationhelper.hxx,v $
  10  * $Revision: 1.1 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31
  32 #ifndef EXTENSIONS_OOOIMPROVEMENT_CONFIGURATIONHELPER_HXX
  33 #define EXTENSIONS_OOOIMPROVEMENT_CONFIGURATIONHELPER_HXX
  34
  35 #include <com/sun/star/uno/XInterface.hpp>
  36 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  37 #include <com/sun/star/beans/PropertyValue.hpp>
  38 #include <com/sun/star/container/XHierarchicalNameAccess.hpp>
  39 #include <com/sun/star/util/XChangesBatch.hpp>
  40 #include <rtl/ustring.hxx>
  41
  42
  43 namespace oooimprovement
  44 {
  45     #ifdef css
  46         #error css defined globally
  47     #endif
  48     #define css ::com::sun::star
  49     // Copy from comphelper module, we cant use that directly from an extension
  50     class MyConfigurationHelper
  51     {
  52         public:
  53             //-----------------------------------------------
  54             /** specify all possible modes, which can be used to open a configuration access.
  55              *
  56              *  @see    openConfig()
  57              *  @see    readDirectKey()
  58              *  @see    writeDirectKey()
  59              */
  60             enum EConfigurationModes
  61             {
  62                 /// opens configuration in read/write mode (without LAZY writing!)
  63                 E_STANDARD = 0,
  64                 /// configuration will be opened readonly
  65                 E_READONLY = 1,
  66                 /// all localized nodes will be interpreted as css::uno::XInterface instead of interpreting it as atomic value nodes
  67                 E_ALL_LOCALES = 2,
  68                 /// enable lazy writing
  69                 E_LAZY_WRITE = 4
  70             };
  71
  72             //-----------------------------------------------
  73             /** returns access to the specified configuration package.
  74              *
  75              *  This method should be used, if e.g. more then one request to the same
  76              *  configuration package is needed. The configuration access can be cached
  77              *  outside and used inbetween.
  78              *
  79              *  @param  xSMGR
  80              *          the uno service manager, which should be used to create the
  81              *          configuration access.
  82              *
  83              *  @param  sPackage
  84              *          the name of the configuration package.
  85              *          e.g. <ul>
  86              *                  <li>org.openoffice.Office.Common</li>
  87              *                  <li>org.openoffice.Office.Common/Menu</li>
  88              *               </ul>
  89              *
  90              *  @param  eMode
  91              *          specify the open mode for the returned configuration access.
  92              *          It's interpreted as a flag field and can be any usefull combination
  93              *          of values of EConfigurationModes.
  94              *
  95              *  @throw  css::uno::Any exceptions the underlying configuration can throw.
  96              *          E.g. css::uno::Exception if the configuration could not be opened.
  97              */
  98             static css::uno::Reference< css::uno::XInterface> openConfig(
  99                 const css::uno::Reference< css::lang::XMultiServiceFactory> xSMGR,
 100                 const ::rtl::OUString& sPackage,
 101                 sal_Int32 eMode);
 102
 103             //-----------------------------------------------
 104             /** reads the value of an existing(!) configuration key,
 105              *  which is searched relative to the specified configuration access.
 106              *
 107              *  This method must be used in combination with openConfig().
 108              *  The cached configuration access must be provided here ... and
 109              *  all operations are made relativ to this access point.
 110              *
 111              *  @param  xCFG
 112              *          the configuration root, where sRelPath should be interpreted.
 113              *          as relativ path
 114              *
 115              *  @param  sRelPath
 116              *          path relative to xCFG parameter.
 117              *
 118              *  @param  sKey
 119              *          the configuration node, where we should read the value.
 120              *
 121              *  @return [css.uno.css::uno::Any]
 122              *          the value of sKey.
 123              *
 124              *  @throw  css::uno::Any exceptions the underlying configuration can throw.
 125              *          E.g. css::container::NoSuchElementException if the specified
 126              *          key does not exists.
 127              */
 128             static css::uno::Any readRelativeKey(
 129                 const css::uno::Reference< css::uno::XInterface> xCFG,
 130                 const ::rtl::OUString& sRelPath,
 131                 const ::rtl::OUString& sKey);
 132
 133         //-----------------------------------------------
 134         /** writes a new value for an existing(!) configuration key,
 135          *  which is searched relative to the specified configuration access.
 136          *
 137          *  This method must be used in combination with openConfig().
 138          *  The cached configuration access must be provided here ... and
 139          *  all operations are made relativ to this access point.
 140          *
 141          *  @param  xCFG
 142          *          the configuration root, where sRelPath should be interpreted.
 143          *          as relativ path
 144          *
 145          *  @param  sRelPath
 146          *          path relative to xCFG parameter.
 147          *
 148          *  @param  sKey
 149          *          the configuration node, where we should write the new value.
 150          *
 151          *  @param  aValue
 152          *          the new value for sKey.
 153          *
 154          *  @throw  css::uno::Any exceptions the underlying configuration can throw.
 155          *          E.g. css::container::NoSuchElementException if the specified
 156          *          key does not exists or css::uno::Exception if the provided configuration
 157          *          access does not allow writing for this key.
 158          */
 159         static void writeRelativeKey(
 160             const css::uno::Reference< css::uno::XInterface> xCFG,
 161             const ::rtl::OUString& sRelPath,
 162             const ::rtl::OUString& sKey,
 163             const css::uno::Any& aValue);
 164
 165         //-----------------------------------------------
 166         /** commit all changes made on the specified configuration access.
 167          *
 168          *  This method must be used in combination with openConfig().
 169          *  The cached configuration access must be provided here.
 170          *
 171          *  @param  xCFG
 172          *          the configuration root, where changes should be commited.
 173          *
 174          *  @throw  css::uno::Any exceptions the underlying configuration can throw.
 175          *          E.g. uno::Exception if the provided configuration
 176          *          access does not allow writing for this set.
 177          */
 178         static void flush(const css::uno::Reference< css::uno::XInterface>& xCFG);
 179
 180         //-----------------------------------------------
 181         /** does the same then openConfig() & readRelativeKey() together.
 182          *
 183          * This method should be used for reading one key at one code place only.
 184          * Because it opens the specified configuration package, reads the key and
 185          * closes the configuration again.
 186          *
 187          * So its not very usefull to use this method for reading multiple keys at the same time.
 188          * (Excepting these keys exists inside different configuration packages ...))
 189          */
 190         static css::uno::Any readDirectKey(
 191             const css::uno::Reference< css::lang::XMultiServiceFactory> xSMGR,
 192             const ::rtl::OUString& sPackage,
 193             const ::rtl::OUString& sRelPath,
 194             const ::rtl::OUString& sKey,
 195             sal_Int32 eMode);
 196
 197         //-----------------------------------------------
 198         /** does the same then openConfig() / writeRelativeKey() & flush() together.
 199          *
 200          * This method should be used for writing one key at one code place only.
 201          * Because it opens the specified configuration package, writes the key, flush
 202          * all changes and closes the configuration again.
 203          *
 204          * So its not very usefull to use this method for writing multiple keys at the same time.
 205          * (Excepting these keys exists inside different configuration packages ...))
 206          */
 207         static void writeDirectKey(
 208             const css::uno::Reference< css::lang::XMultiServiceFactory> xSMGR,
 209             const ::rtl::OUString& sPackage,
 210             const ::rtl::OUString& sRelPath,
 211             const ::rtl::OUString& sKey,
 212             const css::uno::Any& aValue,
 213             sal_Int32 eMode);
 214     };
 215     #undef css
 216 }
 217 #endif