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