include/registry/registry.h

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