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