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 _REGISTRY_REGISTRY_H_ 25 #define _REGISTRY_REGISTRY_H_ 26 27 #include <stddef.h> 28 #include <rtl/ustring.h> 29 #include <registry/regtype.h> 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif /* __cplusplus */ 34 35 /** This function creates the specified key. 36 37 If the key already exists in the registry, the function opens the key only. 38 @param hKey identifies a currently open key. The key which will be opened or created by this 39 function is a subkey of the key identified by hKey. 40 @param keyName points to a null terminated string specifying the name of a key. 41 @param phNewKey points to a variable that receives the handle of the opened or created key. 42 The memory to store this variable will be allocated and will be freed by the function 43 reg_closeKey. If the function fails, phNewKey is NULL. 44 @return REG_NO_ERROR if succeeds else an error code. 45 */ 46 RegError REGISTRY_CALLTYPE reg_createKey(RegKeyHandle hKey, 47 rtl_uString* keyName, 48 RegKeyHandle* phNewKey); 49 50 51 /** This function opens the specified key. 52 53 @param hKey identifies a currently open key. The key which will be opened by this function 54 is a subkey of the key identified by hKey 55 @param keyName points to a null terminated string specifying the name of a key. 56 @param phNewKey points to a variable that receives the handle of the opened key. 57 The memory to store this variable will be allocated and will be freed by the function 58 reg_closeKey. If the function fails, phNewKey is NULL. 59 @return REG_NO_ERROR if succeeds else an error code. 60 */ 61 RegError REGISTRY_CALLTYPE reg_openKey(RegKeyHandle hKey, 62 rtl_uString* keyName, 63 RegKeyHandle* phOpenKey); 64 65 66 67 /** This function opens all subkeys of the specified key. 68 69 @param hKey identifies a currently open key. The key that subkeys will be opened by this 70 function is a subkey of the key identified by hKey 71 @param keyName points to a null terminated string specifying the name of a key whose subkeys 72 will be opened. 73 @param pphSubKeys points to a variable that receives an array of all opened subkeys. 74 The memory to store this variable will be allocated and will be freed by the function 75 reg_closeSubKeys. If the function fails, pphSubKeys is NULL. 76 @param pnSubKeys specifies the length of the array (the number of open subkeys). 77 @return REG_NO_ERROR if succeeds else an error code. 78 */ 79 RegError REGISTRY_CALLTYPE reg_openSubKeys(RegKeyHandle hKey, 80 rtl_uString* keyName, 81 RegKeyHandle** pphSubKeys, 82 sal_uInt32* pnSubKeys); 83 84 85 /** This function closes all subkeys specified in the array. 86 87 @param phSubKeys points to a variable that containss an array of all opened subkeys. 88 The allocated memory of pphSubKeys and all open subkeys will be freed. 89 @param nSubKeys specifies the length of the array (the number of subkeys to closed). 90 @return REG_NO_ERROR if succeeds else an error code. 91 */ 92 RegError REGISTRY_CALLTYPE reg_closeSubKeys(RegKeyHandle* phSubKeys, 93 sal_uInt32 nSubKeys); 94 95 96 /** This function deletes the specified key. 97 98 @param hKey identifies a currently open key. The key deleted by this function 99 is a subkey of the key identified by hKey 100 @param keyName points to a null terminated string specifying the name of a key which will 101 be deleted. 102 @return REG_NO_ERROR if succeeds else an error code. 103 */ 104 RegError REGISTRY_CALLTYPE reg_deleteKey(RegKeyHandle hKey, 105 rtl_uString* keyName); 106 107 108 /** This function closes the specified key. 109 110 @param hKey identifies a currently open key which will be closed by this function. 111 The memory of the variable specifying the key will be freed. 112 @return REG_NO_ERROR if succeeds else an error code. 113 */ 114 RegError REGISTRY_CALLTYPE reg_closeKey(RegKeyHandle hKey); 115 116 117 /** This function returns the name of a key. 118 119 @param hKey identifies a currently open key which name will be returned. 120 @param pKeyName contains the keyname if succeeds else an empty string. 121 */ 122 RegError REGISTRY_CALLTYPE reg_getKeyName(RegKeyHandle hKey, rtl_uString** pKeyName); 123 124 125 /** This function sets a value of a key. 126 127 @param hKey identifies a currently open key. The key which value will be set by this 128 function is a subkey of the key identified by hKey. 129 @param keyName points to a null terminated string specifying the name of a key which value 130 will be set. If keyName is NULL, then the value of the key specified by 131 hKey will be set. 132 @param valueType specifies the type of the value. 133 @param pData points to a memory block containing the data of the value. 134 @param valueSize specifies the size of pData in bytes 135 @return REG_NO_ERROR if succeeds else an error code. 136 */ 137 RegError REGISTRY_CALLTYPE reg_setValue(RegKeyHandle hKey, 138 rtl_uString* keyName, 139 RegValueType valueType, 140 RegValue pData, 141 sal_uInt32 valueSize); 142 143 144 /** This function sets an long list value of a key. 145 146 @param keyName points to a null terminated string specifying the name of a key which value 147 will be set. If keyName is NULL, then the value of the key specified by 148 hKey will be set. 149 @param pValueList points to an array of longs containing the data of the value. 150 @param len specifies the len of pValueList. 151 @return REG_NO_ERROR if succeeds else an error code. 152 */ 153 RegError REGISTRY_CALLTYPE reg_setLongListValue(RegKeyHandle hKey, 154 rtl_uString* keyName, 155 sal_Int32* pValueList, 156 sal_uInt32 len); 157 158 159 /** This function sets an ascii list value of a key. 160 161 @param keyName points to a null terminated string specifying the name of a key which value 162 will be set. If keyName is NULL, then the value of the key specified by 163 hKey will be set. 164 @param pValueList points to an array of sal_Char* containing the data of the value. 165 @param len specifies the len of pValueList. 166 @return REG_NO_ERROR if succeeds else an error code. 167 */ 168 RegError REGISTRY_CALLTYPE reg_setStringListValue(RegKeyHandle hKey, 169 rtl_uString* keyName, 170 sal_Char** pValueList, 171 sal_uInt32 len); 172 173 174 /** This function sets an unicode string list value of a key. 175 176 @param keyName points to a null terminated string specifying the name of a key which value 177 will be set. If keyName is NULL, then the value of the key specified by 178 hKey will be set. 179 @param pValueList points to an array of sal_Unicode* containing the data of the value. 180 @param len specifies the len of pValueList. 181 @return REG_NO_ERROR if succeeds else an error code. 182 */ 183 RegError REGISTRY_CALLTYPE reg_setUnicodeListValue(RegKeyHandle hKey, 184 rtl_uString* keyName, 185 sal_Unicode** pValueList, 186 sal_uInt32 len); 187 188 189 /** This function gets info about type and size of a key value. 190 191 @param hKey identifies a currently open key. The key which value info will be got by this 192 function is a subkey of the key identified by hKey. 193 @param keyName points to a null terminated string specifying the name of a key which value 194 will be got. If keyName is NULL, then the value info of the key specified by 195 hKey will be got. 196 @param pValueType returns the type of the value. 197 @param pValueSize returns the size of the value in bytes 198 @return REG_NO_ERROR if succeeds else an error code. 199 */ 200 RegError REGISTRY_CALLTYPE reg_getValueInfo(RegKeyHandle hKey, 201 rtl_uString* keyName, 202 RegValueType* pValueType, 203 sal_uInt32* pValueSize); 204 205 206 /** This function gets the value of a key. 207 208 @param hKey identifies a currently open key. The key which value will be got by this 209 function is a subkey of the key identified by hKey. 210 @param keyName points to a null terminated string specifying the name of a key which value 211 will be got. If keyName is NULL, then the value of the key specified by 212 hKey will be got. 213 @param pData points to an allocated memory block receiving the data of the value. 214 @return REG_NO_ERROR if succeeds else an error code. 215 */ 216 RegError REGISTRY_CALLTYPE reg_getValue(RegKeyHandle hKey, 217 rtl_uString* keyName, 218 RegValue pData); 219 220 221 /** This function gets the long list value of a key. 222 223 @param keyName points to a null terminated string specifying the name of a key which value 224 will be got. If keyName is NULL, then the value of the key specified by 225 hKey will be got. 226 @param pValueList a Pointer to a long value list which returns the data of the value. 227 @param pLen returns the length of the value list. 228 @return REG_NO_ERROR if succeeds else an error code. 229 */ 230 RegError REGISTRY_CALLTYPE reg_getLongListValue(RegKeyHandle hKey, 231 rtl_uString* keyName, 232 sal_Int32** pValueList, 233 sal_uInt32* pLen); 234 235 236 /** This function gets the string list value of a key. 237 238 @param keyName points to a null terminated string specifying the name of a key which value 239 will be got. If keyName is NULL, then the value of the key specified by 240 hKey will be got. 241 @param pValueList a Pointer to an ascii value list which returns the data of the value. 242 @param pLen returns the length of the value list. 243 @return REG_NO_ERROR if succeeds else an error code. 244 */ 245 RegError REGISTRY_CALLTYPE reg_getStringListValue(RegKeyHandle hKey, 246 rtl_uString* keyName, 247 sal_Char*** pValueList, 248 sal_uInt32* pLen); 249 250 251 /** This function gets the unicode list value of a key. 252 253 @param keyName points to a null terminated string specifying the name of a key which value 254 will be got. If keyName is NULL, then the value of the key specified by 255 hKey will be got. 256 @param pValueList a Pointer to an unicode value list which returns the data of the value. 257 @param pLen returns the length of the value list. 258 @return REG_NO_ERROR if succeeds else an error code. 259 */ 260 RegError REGISTRY_CALLTYPE reg_getUnicodeListValue(RegKeyHandle hKey, 261 rtl_uString* keyName, 262 sal_Unicode*** pValueList, 263 sal_uInt32* pLen); 264 265 266 /** This function frees the memory of a value list. 267 268 @param valueType specifies the type of the list values. 269 @param pValueList a Pointer to the value list. 270 @param len specifies the length of the value list. 271 @return REG_NO_ERROR if succeeds else an error code. 272 */ 273 RegError REGISTRY_CALLTYPE reg_freeValueList(RegValueType valueType, 274 RegValue pValueList, 275 sal_uInt32 len); 276 277 /** This function used to create a link. 278 279 @obsolete Links are no longer supported. 280 281 @return REG_INVALID_LINK 282 */ 283 RegError REGISTRY_CALLTYPE reg_createLink(RegKeyHandle hKey, 284 rtl_uString* linkName, 285 rtl_uString* linkTarget); 286 287 /** This function used to delete a link. 288 289 @obsolete Links are no longer supported. 290 291 @return REG_INVALID_LINK 292 */ 293 RegError REGISTRY_CALLTYPE reg_deleteLink(RegKeyHandle hKey, 294 rtl_uString* linkName); 295 296 /** This function returns the type of a key. 297 298 The registry differentiates two possible types: 299 - RG_KEYTYPE represents a real key 300 - RG_LINKTYPE used to represent a link (no longer used) 301 @param keyName points to a null terminated string specifying the name of the key which keytype 302 will be returned. 303 @param pKeyType returns the type of the key. 304 @return REG_NO_ERROR if succeeds else an error code. 305 */ 306 RegError REGISTRY_CALLTYPE reg_getKeyType(RegKeyHandle hKey, 307 rtl_uString* keyName, 308 RegKeyType* pKeyType); 309 310 /** This function used to return the linktarget of a link. 311 312 @obsolete Links are no longer supported. 313 314 @return REG_INVALID_LINK 315 */ 316 RegError REGISTRY_CALLTYPE reg_getLinkTarget(RegKeyHandle hKey, 317 rtl_uString* linkName, 318 rtl_uString** pLinkTarget); 319 320 /** This function resolves a keyname. 321 322 and returns the resolved keyName in pResolvedName. 323 @param hKey identifies a currently open key. The key specified by keyName is a subkey 324 of the key identified by hKey. 325 @param keyName points to a null terminated string specifying the relativ name of a key. 326 The name of hKey together with keyName will be generated. 327 @param firstLinkOnly ignored 328 @return REG_NO_ERROR if succeeds else an error code. 329 */ 330 RegError REGISTRY_CALLTYPE reg_getResolvedKeyName(RegKeyHandle hKey, 331 rtl_uString* keyName, 332 sal_Bool firstLinkOnly, 333 rtl_uString** pResolvedName); 334 335 /** This function loads registry information from a file and save it under the 336 specified keyName. 337 338 @param hKey identifies a currently open key. The key which should store the registry information 339 is a subkey of this key. 340 @param keyName points to a null terminated string specifying the name of the key which stores the 341 registry information. If keyName is NULL the registry information will be saved under 342 the key specified by hKey. 343 @param regFileName points to a null terminated string specifying the file which conains the 344 registry information. 345 @return REG_NO_ERROR if succeeds else an error code. 346 */ 347 RegError REGISTRY_CALLTYPE reg_loadKey(RegKeyHandle hKey, 348 rtl_uString* keyName, 349 rtl_uString* regFileName); 350 351 352 /** This function saves the registry information under a specified key and all of its subkeys and save 353 it in a registry file. 354 355 @param hKey identifies a currently open key. The key which information is saved by this 356 function is a subkey of the key identified by hKey. 357 @param keyName points to a null terminated string specifying the name of the subkey. 358 If keyName is NULL the registry information under the key specified by hKey 359 will be saved in the specified file. 360 @param regFileName points to a null terminated string specifying the file which will contain the 361 registry information. 362 @return REG_NO_ERROR if succeeds else an error code. 363 */ 364 RegError REGISTRY_CALLTYPE reg_saveKey(RegKeyHandle hKey, 365 rtl_uString* keyName, 366 rtl_uString* regFileName); 367 368 369 /** This function merges the registry information from a specified source with the information of the 370 currently open registry. 371 372 All existing keys will be extended and existing key values will be overwritten. 373 @param hKey identifies a currently open key. The key which information is merged by this 374 function is a subkey of the key identified by hKey. 375 @param keyName points to a null terminated string specifying the name of the key which will be merged. 376 If keyName is NULL the registry information under the key specified by hKey 377 is merged with the complete information from the specified file. 378 @param regFileName points to a null terminated string specifying the file containing the 379 registry information. 380 @param bWarnings if TRUE the function returns an error if a key already exists. 381 @param bReport if TRUE the function reports warnings on stdout if a key already exists. 382 @return REG_NO_ERROR if succeeds else an error code. 383 */ 384 RegError REGISTRY_CALLTYPE reg_mergeKey(RegKeyHandle hKey, 385 rtl_uString* keyName, 386 rtl_uString* regFileName, 387 sal_Bool bWarnings, 388 sal_Bool bReport); 389 390 391 /** This function creates a new registry with the specified name and creates a root key. 392 393 @param registryName points to a null terminated string specifying the name of the new registry. 394 @param phRegistry points to a handle of the new registry if the function succeeds otherwise NULL. 395 @return REG_NO_ERROR if succeeds else an error code. 396 */ 397 RegError REGISTRY_CALLTYPE reg_createRegistry(rtl_uString* registryName, 398 RegHandle* phRegistry); 399 400 401 /** This function opens the root key of a registry. 402 403 @param hReg identifies a currently open registry whose rootKey will be returned. 404 @param phRootKey points to a handle of the open root key if the function succeeds otherwise NULL. 405 @return REG_NO_ERROR if succeeds else an error code. 406 */ 407 RegError REGISTRY_CALLTYPE reg_openRootKey(RegHandle hRegistry, 408 RegKeyHandle* phRootKey); 409 410 411 /** This function returns the name of a registry. 412 413 @param hReg identifies a currently open registry whose name will be returned. 414 @param pName returns the name of the registry if the function succeeds otherwise an empty string. 415 @return REG_NO_ERROR if succeeds else an error code. 416 */ 417 RegError REGISTRY_CALLTYPE reg_getName(RegHandle hRegistry, rtl_uString** pName); 418 419 420 /** This function returns the access mode of the registry. 421 422 @param hReg identifies a currently open registry. 423 @return TRUE if accessmode is read only else FALSE. 424 */ 425 sal_Bool REGISTRY_CALLTYPE reg_isReadOnly(RegHandle hReg); 426 427 428 /** This function opens a registry with the specified name. 429 430 @param registryName points to a null terminated string specifying the name of the registry. 431 @param phRegistry points to a hanle of the opened registry if the function succeeds otherwise NULL. 432 @param accessMode specifies the accessmode of the registry, REG_READONLY or REG_READWRITE. 433 @return REG_NO_ERROR if succeeds else an error code. 434 */ 435 RegError REGISTRY_CALLTYPE reg_openRegistry(rtl_uString* registryName, 436 RegHandle* phRegistry, 437 RegAccessMode accessMode); 438 439 440 /** This function closes a registry. 441 442 @param hRegistry identifies a currently open registry which should be closed. 443 @return REG_NO_ERROR if succeeds else an error code. 444 */ 445 RegError REGISTRY_CALLTYPE reg_closeRegistry(RegHandle hRegistry); 446 447 448 /** This function destroys a registry. 449 450 @param hRegistry identifies a currently open registry. 451 @param registryName specifies a registry name of a registry which should be destroyed. If the 452 name is NULL the registry itselfs will be destroyed. 453 @return REG_NO_ERROR if succeeds else an error code. 454 */ 455 RegError REGISTRY_CALLTYPE reg_destroyRegistry(RegHandle hRegistry, 456 rtl_uString* registryName); 457 458 459 /** This function reports the complete registry information of a key and all of its subkeys. 460 461 All information which are available (keynames, value types, values, ...) 462 will be printed to stdout for report issues only. 463 @param hKey identifies a currently open key which content will be reported. 464 @return REG_NO_ERROR if succeeds else an error code. 465 */ 466 RegError REGISTRY_CALLTYPE reg_dumpRegistry(RegKeyHandle hKey); 467 468 #ifdef __cplusplus 469 } 470 #endif 471 472 #endif 473 474