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