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