Back to index

lightning-sunbird  0.9+nobinonly
NSReg.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
00002  *
00003  * ***** BEGIN LICENSE BLOCK *****
00004  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00005  *
00006  * The contents of this file are subject to the Mozilla Public License Version
00007  * 1.1 (the "License"); you may not use this file except in compliance with
00008  * the License. You may obtain a copy of the License at
00009  * http://www.mozilla.org/MPL/
00010  *
00011  * Software distributed under the License is distributed on an "AS IS" basis,
00012  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00013  * for the specific language governing rights and limitations under the
00014  * License.
00015  *
00016  * The Original Code is Mozilla Communicator client code, released
00017  * March 31, 1998.
00018  *
00019  * The Initial Developer of the Original Code is
00020  * Netscape Communications Corporation.
00021  * Portions created by the Initial Developer are Copyright (C) 1998
00022  * the Initial Developer. All Rights Reserved.
00023  *
00024  * Contributor(s):
00025  *   Daniel Veditz <dveditz@netscape.com>
00026  *
00027  * Alternatively, the contents of this file may be used under the terms of
00028  * either the GNU General Public License Version 2 or later (the "GPL"), or
00029  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00030  * in which case the provisions of the GPL or the LGPL are applicable instead
00031  * of those above. If you wish to allow use of your version of this file only
00032  * under the terms of either the GPL or the LGPL, and not to allow others to
00033  * use your version of this file under the terms of the MPL, indicate your
00034  * decision by deleting the provisions above and replace them with the notice
00035  * and other provisions required by the GPL or the LGPL. If you do not delete
00036  * the provisions above, a recipient may use your version of this file under
00037  * the terms of any one of the MPL, the GPL or the LGPL.
00038  *
00039  * ***** END LICENSE BLOCK ***** */
00040 /* NSReg.h
00041  */
00042 #ifndef _NSREG_H_
00043 #define _NSREG_H_
00044 
00045 typedef void (*nr_RegPackCallbackFunc) (void *userData, int32 bytes, int32 totalBytes);
00046 
00047 typedef int32   REGERR;
00048 typedef int32   RKEY;
00049 typedef uint32  REGENUM;
00050 typedef void *  HREG;
00051 
00052 typedef struct _reginfo
00053 {
00054    uint16  size;        /* must be initialized to sizeof(REGINFO) */
00055    uint16  entryType;
00056    uint32  entryLength;
00057 } REGINFO;
00058 
00059 #define REGERR_OK           (0)
00060 #define REGERR_FAIL         (1)
00061 #define REGERR_NOMORE       (2)
00062 #define REGERR_NOFIND       (3)
00063 #define REGERR_BADREAD      (4)
00064 #define REGERR_BADLOCN      (5)
00065 #define REGERR_PARAM        (6)
00066 #define REGERR_BADMAGIC     (7)
00067 #define REGERR_BADCHECK     (8)
00068 #define REGERR_NOFILE       (9)
00069 #define REGERR_MEMORY       (10)
00070 #define REGERR_BUFTOOSMALL  (11)
00071 #define REGERR_NAMETOOLONG  (12)
00072 #define REGERR_REGVERSION   (13)
00073 #define REGERR_DELETED      (14)
00074 #define REGERR_BADTYPE      (15)
00075 #define REGERR_NOPATH       (16)
00076 #define REGERR_BADNAME      (17)
00077 #define REGERR_READONLY     (18)
00078 #define REGERR_BADUTF8      (19)
00079 
00080 
00081 /* Total path length */
00082 #define MAXREGPATHLEN   (2048)
00083 /* Name on the path (including null terminator) */
00084 #define MAXREGNAMELEN   (512)
00085 /* Value of an entry */
00086 #define MAXREGVALUELEN  (0x7FFF)
00087 
00088 /* Standard keys */
00089 #define ROOTKEY_USERS                   (0x01)
00090 #define ROOTKEY_COMMON                  (0x02)
00091 #define ROOTKEY_CURRENT_USER            (0x03)
00092 #define ROOTKEY_PRIVATE                 (0x04)
00093 
00094 /* enumeration styles */
00095 #define REGENUM_NORMAL                  (0x00)
00096 #define REGENUM_CHILDREN                REGENUM_NORMAL
00097 #define REGENUM_DESCEND                 (0x01)
00098 #define REGENUM_DEPTH_FIRST             (0x02)
00099 
00100 /* entry data types */
00101 #define REGTYPE_ENTRY                 (0x0010)
00102 #define REGTYPE_ENTRY_STRING_UTF      (REGTYPE_ENTRY + 1)
00103 #define REGTYPE_ENTRY_INT32_ARRAY     (REGTYPE_ENTRY + 2)
00104 #define REGTYPE_ENTRY_BYTES           (REGTYPE_ENTRY + 3)
00105 #define REGTYPE_ENTRY_FILE            (REGTYPE_ENTRY + 4)
00106 
00107 #define REG_DELETE_LIST_KEY  "Mozilla/XPInstall/Delete List"
00108 #define REG_REPLACE_LIST_KEY "Mozilla/XPInstall/Replace List"
00109 #define REG_UNINSTALL_DIR    "Mozilla/XPInstall/Uninstall/"
00110 #define REG_REPLACE_SRCFILE  "ReplacementFile"
00111 #define REG_REPLACE_DESTFILE "DestinationFile"
00112 
00113 #define UNINSTALL_NAV_STR "_"
00114 
00115 
00116 #define UNIX_GLOBAL_FLAG     "MOZILLA_SHARED_REGISTRY"
00117 
00118 /* Platform-dependent declspec for library interface */
00119 #if defined(XP_WIN)
00120   #if defined(WIN32)
00121     #if defined (STANDALONE_REGISTRY)
00122        #define VR_INTERFACE(type)     __declspec(dllexport) type __cdecl
00123     #else
00124        #define VR_INTERFACE(type)     __declspec(dllexport) type __stdcall
00125     #endif
00126 
00127   #else
00128   #define VR_INTERFACE(type)     type _far _pascal _export
00129   #endif
00130 #elif defined XP_MAC
00131   #define VR_INTERFACE(__x)  __declspec(export) __x
00132 #elif defined (HAVE_VISIBILITY_ATTRIBUTE)
00133   #define VR_INTERFACE(type)     __attribute__ ((visibility ("default"))) type
00134 #else
00135   #define VR_INTERFACE(type)     type
00136 #endif
00137 
00138 PR_BEGIN_EXTERN_C
00139 
00140 
00141 
00142 /* ---------------------------------------------------------------------
00143  * Registry API -- General
00144  * ---------------------------------------------------------------------
00145  */
00146 
00147 
00148 /* ---------------------------------------------------------------------
00149  * NR_RegSetBufferSize - Sets the file buffer size
00150  *
00151  * Parameters:
00152  *    hReg       - handle to opened registry
00153  *    bufsize    - size of the new buffer
00154  *
00155  * Output:
00156  * ---------------------------------------------------------------------
00157  *    returns the size of the buffer or -1 for err
00158  */
00159 VR_INTERFACE(int) NR_RegSetBufferSize(
00160          HREG hReg,        /* handle to opened registry */
00161          int  bufsize
00162        );
00163 
00164 
00165 /* ---------------------------------------------------------------------
00166  * NR_RegOpen - Open a netscape XP registry
00167  *
00168  * Parameters:
00169  *    filename   - registry file to open. NULL or ""  opens the standard
00170  *                 local registry.
00171  *    hReg       - OUT: handle to opened registry
00172  *
00173  * Output:
00174  * ---------------------------------------------------------------------
00175  */
00176 VR_INTERFACE(REGERR) NR_RegOpen(
00177          const char *filename, /* reg. file to open (NULL == standard registry) */
00178          HREG *hReg            /* OUT: handle to opened registry */
00179        );
00180 
00181 
00182 /* ---------------------------------------------------------------------
00183  * NR_RegClose - Close a netscape XP registry
00184  *
00185  * Parameters:
00186  *    hReg     - handle of open registry to be closed.
00187  *
00188  * After calling this routine the handle is no longer valid
00189  * ---------------------------------------------------------------------
00190  */
00191 VR_INTERFACE(REGERR) NR_RegClose(
00192          HREG hReg         /* handle of open registry to close */
00193        );
00194 
00195 
00196 /* ---------------------------------------------------------------------
00197  * NR_RegFlush - Manually flush data in a netscape XP registry
00198  *
00199  * Parameters:
00200  *    hReg     - handle of open registry to be flushed.
00201  *
00202  * ---------------------------------------------------------------------
00203  */
00204 VR_INTERFACE(REGERR) NR_RegFlush(
00205          HREG hReg         /* handle of open registry to flush */
00206        );
00207 
00208 
00209 /* ---------------------------------------------------------------------
00210  * NR_RegIsWritable - Check read/write status of open registry
00211  *
00212  * Parameters:
00213  *    hReg     - handle of open registry to query
00214  * Returns:
00215  *    REGERR_OK if writable, REGERR_READONLY if not, possibly
00216  *    other errors for an invalid hReg
00217  * ---------------------------------------------------------------------
00218  */
00219 VR_INTERFACE(REGERR) NR_RegIsWritable(
00220          HREG hReg         /* handle of open registry to query */
00221        );
00222 
00223 VR_INTERFACE(REGERR) NR_RegPack(
00224          HREG hReg,         /* handle of open registry to pack */
00225          void *userData,
00226          nr_RegPackCallbackFunc fn
00227        );
00228 
00229 
00230 /* ---------------------------------------------------------------------
00231  * NR_RegSetUsername - Set the current username
00232  * 
00233  * If the current user profile name is not set then trying to use
00234  * HKEY_CURRENT_USER will result in an error.
00235  *
00236  * Parameters:
00237  *     name     - name of the current user
00238  *
00239  * Output:
00240  * ---------------------------------------------------------------------
00241  */
00242 VR_INTERFACE(REGERR) NR_RegSetUsername(
00243          const char *name  /* name of current user */
00244        );
00245 
00246 
00247 /* ---------------------------------------------------------------------
00248  * NR_RegGetUniqueName
00249  * 
00250  * Returns a unique name that can be used for anonymous key/value names
00251  *
00252  * Parameters:
00253  *     hReg     - handle of open registry
00254  *     outbuf   - where to put the string
00255  *     buflen   - how big the buffer is
00256  * ---------------------------------------------------------------------
00257  */
00258 VR_INTERFACE(REGERR) NR_RegGetUniqueName(
00259          HREG hReg,     /* handle of open registry */
00260          char* outbuf,  /* buffer to hold key name */
00261          uint32 buflen  /* size of buffer */
00262        );
00263 
00264 
00265 /* ---------------------------------------------------------------------
00266  * DO NOT USE -- Will be removed 
00267  * ---------------------------------------------------------------------
00268  */
00269 VR_INTERFACE(REGERR) NR_RegGetUsername(
00270          char **name        /* on return, an alloc'ed copy of the current user name */
00271        );
00272 
00273 
00274 
00275 
00276 
00277 
00278 /* ---------------------------------------------------------------------
00279  * Registry API -- Key Management functions
00280  * ---------------------------------------------------------------------
00281  */
00282 
00283 /* ---------------------------------------------------------------------
00284  * NR_RegAddKey - Add a key node to the registry
00285  *
00286  * Can also be used to find an existing node for convenience.
00287  *
00288  * Parameters:
00289  *    hReg     - handle of open registry
00290  *    key      - registry key obtained from NR_RegGetKey(),
00291  *               or one of the standard top-level keys
00292  *    path     - relative path of key to be added.  Intermediate
00293  *               nodes will be added if necessary.
00294  *    newkey   - If not null returns RKEY of new or found node
00295  * ---------------------------------------------------------------------
00296  */
00297 VR_INTERFACE(REGERR) NR_RegAddKey(
00298          HREG hReg,        /* handle of open registry */
00299          RKEY key,         /* root key */
00300          char *path,       /* relative path of subkey to add */
00301          RKEY *newKey      /* if not null returns newly created key */
00302        );
00303 
00304 
00305 /* ---------------------------------------------------------------------
00306  * NR_RegAddKeyRaw - Add a key node to the registry
00307  *
00308  *      This routine is different from NR_RegAddKey() in that it takes 
00309  *      a keyname rather than a path.
00310  *
00311  * Parameters:
00312  *    hReg     - handle of open registry
00313  *    key      - registry key obtained from NR_RegGetKey(),
00314  *               or one of the standard top-level keys
00315  *    keyname  - name of key to be added. No parsing of this
00316  *               name happens.
00317  *    newkey   - if not null the RKEY of the new key is returned
00318  * ---------------------------------------------------------------------
00319  */
00320 VR_INTERFACE(REGERR) NR_RegAddKeyRaw(
00321          HREG hReg,        /* handle of open registry */
00322          RKEY key,         /* root key */
00323          char *keyname,    /* name of key to add */
00324          RKEY *newKey      /* if not null returns newly created key */
00325        );
00326 
00327 
00328 /* ---------------------------------------------------------------------
00329  * NR_RegDeleteKey - Delete the specified key
00330  *
00331  * Note that delete simply orphans blocks and makes no attempt
00332  * to reclaim space in the file. Use NR_RegPack()
00333  *
00334  * Cannot be used to delete keys with child keys
00335  *
00336  * Parameters:
00337  *    hReg     - handle of open registry
00338  *    key      - starting node RKEY, typically one of the standard ones.
00339  *    path     - relative path of key to delete
00340  * ---------------------------------------------------------------------
00341  */
00342 VR_INTERFACE(REGERR) NR_RegDeleteKey(
00343          HREG hReg,        /* handle of open registry */
00344          RKEY key,         /* root key */
00345          char *path        /* relative path of subkey to delete */
00346        );
00347 
00348 
00349 /* ---------------------------------------------------------------------
00350  * NR_RegDeleteKeyRaw - Delete the specified raw key
00351  *
00352  * Note that delete simply orphans blocks and makes no attempt
00353  * to reclaim space in the file. Use NR_RegPack()
00354  *
00355  * Parameters:
00356  *    hReg     - handle of open registry
00357  *    key      - RKEY or parent to the raw key you wish to delete
00358  *    keyname  - name of child key to delete
00359  * ---------------------------------------------------------------------
00360  */
00361 VR_INTERFACE(REGERR) NR_RegDeleteKeyRaw(
00362          HREG hReg,        /* handle of open registry */
00363          RKEY key,         /* root key */
00364          char *keyname     /* name subkey to delete */
00365        );
00366 
00367 
00368 /* ---------------------------------------------------------------------
00369  * NR_RegGetKey - Get the RKEY value of a node from its path
00370  *
00371  * Parameters:
00372  *    hReg     - handle of open registry
00373  *    key      - starting node RKEY, typically one of the standard ones.
00374  *    path     - relative path of key to find.  (a blank path just gives you
00375  *               the starting key--useful for verification, VersionRegistry)
00376  *    result   - if successful the RKEY of the specified sub-key
00377  * ---------------------------------------------------------------------
00378  */
00379 VR_INTERFACE(REGERR) NR_RegGetKey(
00380          HREG hReg,        /* handle of open registry */
00381          RKEY key,         /* root key */
00382          const char *path, /* relative path of subkey to find */
00383          RKEY *result      /* returns RKEY of specified sub-key */
00384        );
00385 
00386 
00387 /* ---------------------------------------------------------------------
00388  * NR_RegGetKeyRaw - Get the RKEY value of a node from its keyname
00389  *
00390  * Parameters:
00391  *    hReg     - handle of open registry
00392  *    key      - starting node RKEY, typically one of the standard ones.
00393  *    keyname  - keyname of key to find.  (a blank keyname just gives you
00394  *               the starting key--useful for verification, VersionRegistry)
00395  *    result   - if successful the RKEY of the specified sub-key
00396  * ---------------------------------------------------------------------
00397  */
00398 VR_INTERFACE(REGERR) NR_RegGetKeyRaw(
00399          HREG hReg,        /* handle of open registry */
00400          RKEY key,         /* root key */
00401          char *keyname,       /* name of key to get */
00402          RKEY *result      /* returns RKEY of specified sub-key */
00403        );
00404 
00405 
00406 /* ---------------------------------------------------------------------
00407  * NR_RegEnumSubkeys - Enumerate the subkey names for the specified key
00408  *
00409  * Returns REGERR_NOMORE at end of enumeration.
00410  *
00411  * Parameters:
00412  *    hReg     - handle of open registry
00413  *    key      - RKEY of key to enumerate--obtain with NR_RegGetKey()
00414  *    eState   - enumerations state, must contain NULL to start
00415  *    buffer   - location to store subkey names.  Once an enumeration
00416  *               is started user must not modify contents since values
00417  *               are built using the previous contents.
00418  *    bufsize  - size of buffer for names
00419  *    style    - 0 returns direct child keys only, REGENUM_DESCEND
00420  *               returns entire sub-tree
00421  * ---------------------------------------------------------------------
00422  */
00423 VR_INTERFACE(REGERR) NR_RegEnumSubkeys(
00424          HREG    hReg,        /* handle of open registry */
00425          RKEY    key,         /* containing key */
00426          REGENUM *state,      /* enum state, must be NULL to start */
00427          char    *buffer,     /* buffer for entry names */
00428          uint32  bufsize,     /* size of buffer */
00429          uint32  style        /* 0: children only; REGENUM_DESCEND: sub-tree */
00430        );
00431 
00432 
00433 
00434 /* ---------------------------------------------------------------------
00435  * Registry API -- Entry Management functions
00436  * ---------------------------------------------------------------------
00437  */
00438 
00439 
00440 /* ---------------------------------------------------------------------
00441  * NR_RegGetEntryInfo - Get some basic info about the entry data
00442  *
00443  * Parameters:
00444  *    hReg     - handle of open registry
00445  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00446  *    name     - name of entry
00447  *    info     - return: Entry info object
00448  * ---------------------------------------------------------------------
00449  */
00450 VR_INTERFACE(REGERR) NR_RegGetEntryInfo(
00451          HREG    hReg,     /* handle of open registry */
00452          RKEY    key,      /* containing key */
00453          char    *name,    /* entry name */
00454          REGINFO *info     /* returned entry info */
00455        );
00456 
00457        
00458 /* ---------------------------------------------------------------------
00459  * NR_RegGetEntryString - Get the UTF string value associated with the
00460  *                       named entry of the specified key.
00461  *
00462  * Parameters:
00463  *    hReg     - handle of open registry
00464  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00465  *    name     - name of entry
00466  *    buffer   - destination for string
00467  *    bufsize  - size of buffer
00468  * ---------------------------------------------------------------------
00469  */
00470 VR_INTERFACE(REGERR) NR_RegGetEntryString(
00471          HREG   hReg,      /* handle of open registry */
00472          RKEY   key,       /* containing key */
00473          char   *name,     /* entry name */
00474          char   *buffer,   /* buffer to hold value (UTF String) */
00475          uint32 bufsize    /* length of buffer */
00476        );
00477 
00478 /* ---------------------------------------------------------------------
00479  * NR_RegGetEntry - Get the value data associated with the
00480  *                  named entry of the specified key.
00481  *
00482  * Parameters:
00483  *    hReg     - handle of open registry
00484  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00485  *    name     - name of entry
00486  *    buffer   - destination for data
00487  *    size     - in:  size of buffer
00488  *               out: size of actual data (incl. \0 term. for strings)
00489  * ---------------------------------------------------------------------
00490  */
00491 VR_INTERFACE(REGERR) NR_RegGetEntry(
00492          HREG   hReg,      /* handle of open registry */
00493          RKEY   key,       /* containing key */
00494          char   *name,     /* entry name */
00495          void   *buffer,   /* buffer to hold value */
00496          uint32 *size      /* in:length of buffer */
00497        );                  /* out: data length, >>includes<< null terminator*/
00498 
00499 
00500 /* ---------------------------------------------------------------------
00501  * NR_RegSetEntryString - Store a UTF-8 string value associated with the
00502  *                       named entry of the specified key.  Used for
00503  *                       both creation and update.
00504  *
00505  * Parameters:
00506  *    hReg     - handle of open registry
00507  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00508  *    name     - name of entry
00509  *    buffer   - UTF-8 String to store
00510  * ---------------------------------------------------------------------
00511  */
00512 VR_INTERFACE(REGERR) NR_RegSetEntryString(
00513          HREG hReg,        /* handle of open registry */
00514          RKEY key,         /* containing key */
00515          char *name,       /* entry name */
00516          char *buffer      /* UTF String value */
00517        );
00518 
00519 
00520 /* ---------------------------------------------------------------------
00521  * NR_RegSetEntry - Store value data associated with the named entry
00522  *                  of the specified key.  Used for both creation and update.
00523  *
00524  * Parameters:
00525  *    hReg     - handle of open registry
00526  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00527  *    name     - name of entry
00528  *    type     - type of data to be stored
00529  *    buffer   - data to store
00530  *    size     - length of data to store in bytes
00531  * ---------------------------------------------------------------------
00532  */
00533 VR_INTERFACE(REGERR) NR_RegSetEntry(
00534          HREG   hReg,        /* handle of open registry */
00535          RKEY   key,         /* containing key */
00536          char   *name,       /* entry name */
00537          uint16 type,        /* type of value data */
00538          void   *buffer,     /* data buffer */
00539          uint32 size         /* data length in bytes; incl. null term for strings */
00540        );
00541 
00542 
00543 /* ---------------------------------------------------------------------
00544  * NR_RegDeleteEntry - Delete the named entry
00545  *
00546  * Parameters:
00547  *    hReg     - handle of open registry
00548  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00549  *    name     - name of entry
00550  * ---------------------------------------------------------------------
00551  */
00552 VR_INTERFACE(REGERR) NR_RegDeleteEntry(
00553          HREG hReg,        /* handle of open registry */
00554          RKEY key,         /* containing key */
00555          char *name        /* value name */
00556        );
00557 
00558 
00559 /* ---------------------------------------------------------------------
00560  * NR_RegEnumEntries - Enumerate the entry names for the specified key
00561  *
00562  * Returns REGERR_NOMORE at end of enumeration.
00563  *
00564  * Parameters:
00565  *    hReg     - handle of open registry
00566  *    key      - RKEY of key that contains entry--obtain with NR_RegGetKey()
00567  *    eState   - enumerations state, must contain NULL to start
00568  *    buffer   - location to store entry names
00569  *    bufsize  - size of buffer for names
00570  * ---------------------------------------------------------------------
00571  */
00572 VR_INTERFACE(REGERR) NR_RegEnumEntries(
00573          HREG    hReg,        /* handle of open registry */
00574          RKEY    key,         /* containing key */
00575          REGENUM *state,      /* enum state, must be NULL to start */
00576          char    *buffer,     /* buffer for entry names */
00577          uint32  bufsize,     /* size of buffer */
00578          REGINFO *info        /* optional; returns info about entry */
00579        );
00580 
00581 
00582 VR_INTERFACE(void)      NR_ShutdownRegistry(void);
00583 VR_INTERFACE(REGERR)    NR_StartupRegistry(void);
00584 
00585 
00586 PR_END_EXTERN_C
00587 
00588 #endif   /* _NSREG_H_ */
00589 
00590 /* EOF: NSReg.h */
00591