modules/libreg/include/NSReg.h

   1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Mozilla Communicator client code, released
  17  * March 31, 1998.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 1998
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *   Daniel Veditz <dveditz@netscape.com>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40 /* NSReg.h
  41  */
  42 #ifndef _NSREG_H_
  43 #define _NSREG_H_
  44
  45 typedef void (*nr_RegPackCallbackFunc) (void *userData, int32 bytes, int32 totalBytes);
  46
  47 typedef int32   REGERR;
  48 typedef int32   RKEY;
  49 typedef uint32  REGENUM;
  50 typedef void *  HREG;
  51
  52 typedef struct _reginfo
  53 {
  54    uint16  size;        /* must be initialized to sizeof(REGINFO) */
  55    uint16  entryType;
  56    uint32  entryLength;
  57 } REGINFO;
  58
  59 #define REGERR_OK           (0)
  60 #define REGERR_FAIL         (1)
  61 #define REGERR_NOMORE       (2)
  62 #define REGERR_NOFIND       (3)
  63 #define REGERR_BADREAD      (4)
  64 #define REGERR_BADLOCN      (5)
  65 #define REGERR_PARAM        (6)
  66 #define REGERR_BADMAGIC     (7)
  67 #define REGERR_BADCHECK     (8)
  68 #define REGERR_NOFILE       (9)
  69 #define REGERR_MEMORY       (10)
  70 #define REGERR_BUFTOOSMALL  (11)
  71 #define REGERR_NAMETOOLONG  (12)
  72 #define REGERR_REGVERSION   (13)
  73 #define REGERR_DELETED      (14)
  74 #define REGERR_BADTYPE      (15)
  75 #define REGERR_NOPATH       (16)
  76 #define REGERR_BADNAME      (17)
  77 #define REGERR_READONLY     (18)
  78 #define REGERR_BADUTF8      (19)
  79
  80
  81 /* Total path length */
  82 #define MAXREGPATHLEN   (2048)
  83 /* Name on the path (including null terminator) */
  84 #define MAXREGNAMELEN   (512)
  85 /* Value of an entry */
  86 #define MAXREGVALUELEN  (0x7FFF)
  87
  88 /* Standard keys */
  89 #define ROOTKEY_USERS                   (0x01)
  90 #define ROOTKEY_COMMON                  (0x02)
  91 #define ROOTKEY_CURRENT_USER            (0x03)
  92 #define ROOTKEY_PRIVATE                 (0x04)
  93
  94 /* enumeration styles */
  95 #define REGENUM_NORMAL                  (0x00)
  96 #define REGENUM_CHILDREN                REGENUM_NORMAL
  97 #define REGENUM_DESCEND                 (0x01)
  98 #define REGENUM_DEPTH_FIRST             (0x02)
  99
 100 /* entry data types */
 101 #define REGTYPE_ENTRY                 (0x0010)
 102 #define REGTYPE_ENTRY_STRING_UTF      (REGTYPE_ENTRY + 1)
 103 #define REGTYPE_ENTRY_INT32_ARRAY     (REGTYPE_ENTRY + 2)
 104 #define REGTYPE_ENTRY_BYTES           (REGTYPE_ENTRY + 3)
 105 #define REGTYPE_ENTRY_FILE            (REGTYPE_ENTRY + 4)
 106
 107 #define REG_DELETE_LIST_KEY  "Mozilla/XPInstall/Delete List"
 108 #define REG_REPLACE_LIST_KEY "Mozilla/XPInstall/Replace List"
 109 #define REG_UNINSTALL_DIR    "Mozilla/XPInstall/Uninstall/"
 110 #define REG_REPLACE_SRCFILE  "ReplacementFile"
 111 #define REG_REPLACE_DESTFILE "DestinationFile"
 112
 113 #define UNINSTALL_NAV_STR "_"
 114
 115
 116 #define UNIX_GLOBAL_FLAG     "MOZILLA_SHARED_REGISTRY"
 117
 118 /* libreg functions are not DLLexported and may have hidden visibility */
 119 #define VR_INTERFACE(type)     type
 120
 121 PR_BEGIN_EXTERN_C
 122
 123
 124
 125 /* ---------------------------------------------------------------------
 126  * Registry API -- General
 127  * ---------------------------------------------------------------------
 128  */
 129
 130
 131 /* ---------------------------------------------------------------------
 132  * NR_RegSetBufferSize - Sets the file buffer size
 133  *
 134  * Parameters:
 135  *    hReg       - handle to opened registry
 136  *    bufsize    - size of the new buffer
 137  *
 138  * Output:
 139  * ---------------------------------------------------------------------
 140  *    returns the size of the buffer or -1 for err
 141  */
 142 VR_INTERFACE(int) NR_RegSetBufferSize(
 143          HREG hReg,        /* handle to opened registry */
 144          int  bufsize
 145        );
 146
 147
 148 /* ---------------------------------------------------------------------
 149  * NR_RegOpen - Open a netscape XP registry
 150  *
 151  * Parameters:
 152  *    filename   - registry file to open. NULL or ""  opens the standard
 153  *                 local registry.
 154  *    hReg       - OUT: handle to opened registry
 155  *
 156  * Output:
 157  * ---------------------------------------------------------------------
 158  */
 159 VR_INTERFACE(REGERR) NR_RegOpen(
 160          const char *filename, /* reg. file to open (NULL == standard registry) */
 161          HREG *hReg            /* OUT: handle to opened registry */
 162        );
 163
 164
 165 /* ---------------------------------------------------------------------
 166  * NR_RegClose - Close a netscape XP registry
 167  *
 168  * Parameters:
 169  *    hReg     - handle of open registry to be closed.
 170  *
 171  * After calling this routine the handle is no longer valid
 172  * ---------------------------------------------------------------------
 173  */
 174 VR_INTERFACE(REGERR) NR_RegClose(
 175          HREG hReg         /* handle of open registry to close */
 176        );
 177
 178
 179 /* ---------------------------------------------------------------------
 180  * NR_RegFlush - Manually flush data in a netscape XP registry
 181  *
 182  * Parameters:
 183  *    hReg     - handle of open registry to be flushed.
 184  *
 185  * ---------------------------------------------------------------------
 186  */
 187 VR_INTERFACE(REGERR) NR_RegFlush(
 188          HREG hReg         /* handle of open registry to flush */
 189        );
 190
 191
 192 /* ---------------------------------------------------------------------
 193  * NR_RegIsWritable - Check read/write status of open registry
 194  *
 195  * Parameters:
 196  *    hReg     - handle of open registry to query
 197  * Returns:
 198  *    REGERR_OK if writable, REGERR_READONLY if not, possibly
 199  *    other errors for an invalid hReg
 200  * ---------------------------------------------------------------------
 201  */
 202 VR_INTERFACE(REGERR) NR_RegIsWritable(
 203          HREG hReg         /* handle of open registry to query */
 204        );
 205
 206 VR_INTERFACE(REGERR) NR_RegPack(
 207          HREG hReg,         /* handle of open registry to pack */
 208          void *userData,
 209          nr_RegPackCallbackFunc fn
 210        );
 211
 212
 213 /* ---------------------------------------------------------------------
 214  * NR_RegSetUsername - Set the current username
 215  *
 216  * If the current user profile name is not set then trying to use
 217  * HKEY_CURRENT_USER will result in an error.
 218  *
 219  * Parameters:
 220  *     name     - name of the current user
 221  *
 222  * Output:
 223  * ---------------------------------------------------------------------
 224  */
 225 VR_INTERFACE(REGERR) NR_RegSetUsername(
 226          const char *name  /* name of current user */
 227        );
 228
 229
 230 /* ---------------------------------------------------------------------
 231  * NR_RegGetUniqueName
 232  *
 233  * Returns a unique name that can be used for anonymous key/value names
 234  *
 235  * Parameters:
 236  *     hReg     - handle of open registry
 237  *     outbuf   - where to put the string
 238  *     buflen   - how big the buffer is
 239  * ---------------------------------------------------------------------
 240  */
 241 VR_INTERFACE(REGERR) NR_RegGetUniqueName(
 242          HREG hReg,     /* handle of open registry */
 243          char* outbuf,  /* buffer to hold key name */
 244          uint32 buflen  /* size of buffer */
 245        );
 246
 247
 248 /* ---------------------------------------------------------------------
 249  * DO NOT USE -- Will be removed
 250  * ---------------------------------------------------------------------
 251  */
 252 VR_INTERFACE(REGERR) NR_RegGetUsername(
 253          char **name        /* on return, an alloc'ed copy of the current user name */
 254        );
 255
 256
 257
 258
 259
 260
 261 /* ---------------------------------------------------------------------
 262  * Registry API -- Key Management functions
 263  * ---------------------------------------------------------------------
 264  */
 265
 266 /* ---------------------------------------------------------------------
 267  * NR_RegAddKey - Add a key node to the registry
 268  *
 269  * Can also be used to find an existing node for convenience.
 270  *
 271  * Parameters:
 272  *    hReg     - handle of open registry
 273  *    key      - registry key obtained from NR_RegGetKey(),
 274  *               or one of the standard top-level keys
 275  *    path     - relative path of key to be added.  Intermediate
 276  *               nodes will be added if necessary.
 277  *    newkey   - If not null returns RKEY of new or found node
 278  * ---------------------------------------------------------------------
 279  */
 280 VR_INTERFACE(REGERR) NR_RegAddKey(
 281          HREG hReg,        /* handle of open registry */
 282          RKEY key,         /* root key */
 283          char *path,       /* relative path of subkey to add */
 284          RKEY *newKey      /* if not null returns newly created key */
 285        );
 286
 287
 288 /* ---------------------------------------------------------------------
 289  * NR_RegAddKeyRaw - Add a key node to the registry
 290  *
 291  *      This routine is different from NR_RegAddKey() in that it takes
 292  *      a keyname rather than a path.
 293  *
 294  * Parameters:
 295  *    hReg     - handle of open registry
 296  *    key      - registry key obtained from NR_RegGetKey(),
 297  *               or one of the standard top-level keys
 298  *    keyname  - name of key to be added. No parsing of this
 299  *               name happens.
 300  *    newkey   - if not null the RKEY of the new key is returned
 301  * ---------------------------------------------------------------------
 302  */
 303 VR_INTERFACE(REGERR) NR_RegAddKeyRaw(
 304          HREG hReg,        /* handle of open registry */
 305          RKEY key,         /* root key */
 306          char *keyname,    /* name of key to add */
 307          RKEY *newKey      /* if not null returns newly created key */
 308        );
 309
 310
 311 /* ---------------------------------------------------------------------
 312  * NR_RegDeleteKey - Delete the specified key
 313  *
 314  * Note that delete simply orphans blocks and makes no attempt
 315  * to reclaim space in the file. Use NR_RegPack()
 316  *
 317  * Cannot be used to delete keys with child keys
 318  *
 319  * Parameters:
 320  *    hReg     - handle of open registry
 321  *    key      - starting node RKEY, typically one of the standard ones.
 322  *    path     - relative path of key to delete
 323  * ---------------------------------------------------------------------
 324  */
 325 VR_INTERFACE(REGERR) NR_RegDeleteKey(
 326          HREG hReg,        /* handle of open registry */
 327          RKEY key,         /* root key */
 328          char *path        /* relative path of subkey to delete */
 329        );
 330
 331
 332 /* ---------------------------------------------------------------------
 333  * NR_RegDeleteKeyRaw - Delete the specified raw key
 334  *
 335  * Note that delete simply orphans blocks and makes no attempt
 336  * to reclaim space in the file. Use NR_RegPack()
 337  *
 338  * Parameters:
 339  *    hReg     - handle of open registry
 340  *    key      - RKEY or parent to the raw key you wish to delete
 341  *    keyname  - name of child key to delete
 342  * ---------------------------------------------------------------------
 343  */
 344 VR_INTERFACE(REGERR) NR_RegDeleteKeyRaw(
 345          HREG hReg,        /* handle of open registry */
 346          RKEY key,         /* root key */
 347          char *keyname     /* name subkey to delete */
 348        );
 349
 350
 351 /* ---------------------------------------------------------------------
 352  * NR_RegGetKey - Get the RKEY value of a node from its path
 353  *
 354  * Parameters:
 355  *    hReg     - handle of open registry
 356  *    key      - starting node RKEY, typically one of the standard ones.
 357  *    path     - relative path of key to find.  (a blank path just gives you
 358  *               the starting key--useful for verification, VersionRegistry)
 359  *    result   - if successful the RKEY of the specified sub-key
 360  * ---------------------------------------------------------------------
 361  */
 362 VR_INTERFACE(REGERR) NR_RegGetKey(
 363          HREG hReg,        /* handle of open registry */
 364          RKEY key,         /* root key */
 365          const char *path, /* relative path of subkey to find */
 366          RKEY *result      /* returns RKEY of specified sub-key */
 367        );
 368
 369
 370 /* ---------------------------------------------------------------------
 371  * NR_RegGetKeyRaw - Get the RKEY value of a node from its keyname
 372  *
 373  * Parameters:
 374  *    hReg     - handle of open registry
 375  *    key      - starting node RKEY, typically one of the standard ones.
 376  *    keyname  - keyname of key to find.  (a blank keyname just gives you
 377  *               the starting key--useful for verification, VersionRegistry)
 378  *    result   - if successful the RKEY of the specified sub-key
 379  * ---------------------------------------------------------------------
 380  */
 381 VR_INTERFACE(REGERR) NR_RegGetKeyRaw(
 382          HREG hReg,        /* handle of open registry */
 383          RKEY key,         /* root key */
 384          char *keyname,       /* name of key to get */
 385          RKEY *result      /* returns RKEY of specified sub-key */
 386        );
 387
 388
 389 /* ---------------------------------------------------------------------
 390  * NR_RegEnumSubkeys - Enumerate the subkey names for the specified key
 391  *
 392  * Returns REGERR_NOMORE at end of enumeration.
 393  *
 394  * Parameters:
 395  *    hReg     - handle of open registry
 396  *    key      - RKEY of key to enumerate--obtain with NR_RegGetKey()
 397  *    eState   - enumerations state, must contain NULL to start
 398  *    buffer   - location to store subkey names.  Once an enumeration
 399  *               is started user must not modify contents since values
 400  *               are built using the previous contents.
 401  *    bufsize  - size of buffer for names
 402  *    style    - 0 returns direct child keys only, REGENUM_DESCEND
 403  *               returns entire sub-tree
 404  * ---------------------------------------------------------------------
 405  */
 406 VR_INTERFACE(REGERR) NR_RegEnumSubkeys(
 407          HREG    hReg,        /* handle of open registry */
 408          RKEY    key,         /* containing key */
 409          REGENUM *state,      /* enum state, must be NULL to start */
 410          char    *buffer,     /* buffer for entry names */
 411          uint32  bufsize,     /* size of buffer */
 412          uint32  style        /* 0: children only; REGENUM_DESCEND: sub-tree */
 413        );
 414
 415
 416
 417 /* ---------------------------------------------------------------------
 418  * Registry API -- Entry Management functions
 419  * ---------------------------------------------------------------------
 420  */
 421
 422
 423 /* ---------------------------------------------------------------------
 424  * NR_RegGetEntryInfo - Get some basic info about the entry data
 425  *
 426  * Parameters:
 427  *    hReg     - handle of open registry
 428  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 429  *    name     - name of entry
 430  *    info     - return: Entry info object
 431  * ---------------------------------------------------------------------
 432  */
 433 VR_INTERFACE(REGERR) NR_RegGetEntryInfo(
 434          HREG    hReg,     /* handle of open registry */
 435          RKEY    key,      /* containing key */
 436          char    *name,    /* entry name */
 437          REGINFO *info     /* returned entry info */
 438        );
 439
 440
 441 /* ---------------------------------------------------------------------
 442  * NR_RegGetEntryString - Get the UTF string value associated with the
 443  *                       named entry of the specified key.
 444  *
 445  * Parameters:
 446  *    hReg     - handle of open registry
 447  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 448  *    name     - name of entry
 449  *    buffer   - destination for string
 450  *    bufsize  - size of buffer
 451  * ---------------------------------------------------------------------
 452  */
 453 VR_INTERFACE(REGERR) NR_RegGetEntryString(
 454          HREG   hReg,      /* handle of open registry */
 455          RKEY   key,       /* containing key */
 456          char   *name,     /* entry name */
 457          char   *buffer,   /* buffer to hold value (UTF String) */
 458          uint32 bufsize    /* length of buffer */
 459        );
 460
 461 /* ---------------------------------------------------------------------
 462  * NR_RegGetEntry - Get the value data associated with the
 463  *                  named entry of the specified key.
 464  *
 465  * Parameters:
 466  *    hReg     - handle of open registry
 467  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 468  *    name     - name of entry
 469  *    buffer   - destination for data
 470  *    size     - in:  size of buffer
 471  *               out: size of actual data (incl. \0 term. for strings)
 472  * ---------------------------------------------------------------------
 473  */
 474 VR_INTERFACE(REGERR) NR_RegGetEntry(
 475          HREG   hReg,      /* handle of open registry */
 476          RKEY   key,       /* containing key */
 477          char   *name,     /* entry name */
 478          void   *buffer,   /* buffer to hold value */
 479          uint32 *size      /* in:length of buffer */
 480        );                  /* out: data length, >>includes<< null terminator*/
 481
 482
 483 /* ---------------------------------------------------------------------
 484  * NR_RegSetEntryString - Store a UTF-8 string value associated with the
 485  *                       named entry of the specified key.  Used for
 486  *                       both creation and update.
 487  *
 488  * Parameters:
 489  *    hReg     - handle of open registry
 490  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 491  *    name     - name of entry
 492  *    buffer   - UTF-8 String to store
 493  * ---------------------------------------------------------------------
 494  */
 495 VR_INTERFACE(REGERR) NR_RegSetEntryString(
 496          HREG hReg,        /* handle of open registry */
 497          RKEY key,         /* containing key */
 498          char *name,       /* entry name */
 499          char *buffer      /* UTF String value */
 500        );
 501
 502
 503 /* ---------------------------------------------------------------------
 504  * NR_RegSetEntry - Store value data associated with the named entry
 505  *                  of the specified key.  Used for both creation and update.
 506  *
 507  * Parameters:
 508  *    hReg     - handle of open registry
 509  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 510  *    name     - name of entry
 511  *    type     - type of data to be stored
 512  *    buffer   - data to store
 513  *    size     - length of data to store in bytes
 514  * ---------------------------------------------------------------------
 515  */
 516 VR_INTERFACE(REGERR) NR_RegSetEntry(
 517          HREG   hReg,        /* handle of open registry */
 518          RKEY   key,         /* containing key */
 519          char   *name,       /* entry name */
 520          uint16 type,        /* type of value data */
 521          void   *buffer,     /* data buffer */
 522          uint32 size         /* data length in bytes; incl. null term for strings */
 523        );
 524
 525
 526 /* ---------------------------------------------------------------------
 527  * NR_RegDeleteEntry - Delete the named entry
 528  *
 529  * Parameters:
 530  *    hReg     - handle of open registry
 531  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 532  *    name     - name of entry
 533  * ---------------------------------------------------------------------
 534  */
 535 VR_INTERFACE(REGERR) NR_RegDeleteEntry(
 536          HREG hReg,        /* handle of open registry */
 537          RKEY key,         /* containing key */
 538          char *name        /* value name */
 539        );
 540
 541
 542 /* ---------------------------------------------------------------------
 543  * NR_RegEnumEntries - Enumerate the entry names for the specified key
 544  *
 545  * Returns REGERR_NOMORE at end of enumeration.
 546  *
 547  * Parameters:
 548  *    hReg     - handle of open registry
 549  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
 550  *    eState   - enumerations state, must contain NULL to start
 551  *    buffer   - location to store entry names
 552  *    bufsize  - size of buffer for names
 553  * ---------------------------------------------------------------------
 554  */
 555 VR_INTERFACE(REGERR) NR_RegEnumEntries(
 556          HREG    hReg,        /* handle of open registry */
 557          RKEY    key,         /* containing key */
 558          REGENUM *state,      /* enum state, must be NULL to start */
 559          char    *buffer,     /* buffer for entry names */
 560          uint32  bufsize,     /* size of buffer */
 561          REGINFO *info        /* optional; returns info about entry */
 562        );
 563
 564
 565 VR_INTERFACE(void)      NR_ShutdownRegistry(void);
 566 VR_INTERFACE(REGERR)    NR_StartupRegistry(void);
 567
 568
 569 PR_END_EXTERN_C
 570
 571 #endif   /* _NSREG_H_ */
 572
 573 /* EOF: NSReg.h */
 574