mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-12-05 03:54:35 +00:00
351 lines
24 KiB
C++
351 lines
24 KiB
C++
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
|
|
/*
|
|
* The contents of this file are subject to the Netscape Public License
|
|
* Version 1.0 (the "NPL"); you may not use this file except in
|
|
* compliance with the NPL. You may obtain a copy of the NPL at
|
|
* http://www.mozilla.org/NPL/
|
|
*
|
|
* Software distributed under the NPL is distributed on an "AS IS" basis,
|
|
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
|
|
* for the specific language governing rights and limitations under the
|
|
* NPL.
|
|
*
|
|
* The Initial Developer of this code under the NPL is Netscape
|
|
* Communications Corporation. Portions created by Netscape are
|
|
* Copyright (C) 1998 Netscape Communications Corporation. All Rights
|
|
* Reserved.
|
|
*/
|
|
#ifndef __nsIRegistry_h
|
|
#define __nsIRegistry_h
|
|
|
|
#include "nsISupports.h"
|
|
|
|
// {5D41A440-8E37-11d2-8059-00600811A9C3}
|
|
#define NS_IREGISTRY_IID { 0x5d41a440, 0x8e37, 0x11d2, { 0x80, 0x59, 0x0, 0x60, 0x8, 0x11, 0xa9, 0xc3 } }
|
|
#define NS_REGISTRY_PROGID "component://netscape/registry"
|
|
#define NS_REGISTRY_CLASSNAME "Mozilla Registry"
|
|
|
|
// {D1B54831-AC07-11d2-805E-00600811A9C3}
|
|
#define NS_IREGISTRYNODE_IID { 0xd1b54831, 0xac07, 0x11d2, { 0x80, 0x5e, 0x0, 0x60, 0x8, 0x11, 0xa9, 0xc3 } }
|
|
// {5316C380-B2F8-11d2-A374-0080C6F80E4B}
|
|
#define NS_IREGISTRYVALUE_IID { 0x5316c380, 0xb2f8, 0x11d2, { 0xa3, 0x74, 0x0, 0x80, 0xc6, 0xf8, 0xe, 0x4b } }
|
|
|
|
|
|
class nsIEnumerator;
|
|
|
|
/*-------------------------------- nsIRegistry ---------------------------------
|
|
| This interface provides access to a tree of arbitrary values. |
|
|
| |
|
|
| Each node of the tree contains either a value or a subtree or both. |
|
|
| |
|
|
| The value at any of these leaf nodes can be any of these "primitive" types: |
|
|
| o string (null terminated UTF string) |
|
|
| o array of 32-bit integers |
|
|
| o arbitrary array of bytes |
|
|
| o file identifier |
|
|
| Of course, since you can store an arbitrary array of bytes, you can put |
|
|
| any data you like into a registry (although you have the burden of |
|
|
| encoding/decoding your data in that case). |
|
|
| |
|
|
| Each branch of the tree is labelled with a string "key." The entire path |
|
|
| from a given point of the tree to another point further down can be |
|
|
| presented as a single string composed of each branch's label, concatenated |
|
|
| to the next, with an intervening forward slash ('/'). The term "key" |
|
|
| refers to both specific tree branch labels and to such concatenated paths. |
|
|
| |
|
|
| The branches from a given node must have unique labels. Distinct nodes can |
|
|
| have branches with the same label. |
|
|
| |
|
|
| For example, here's a small registry tree: |
|
|
| | |
|
|
| /\ |
|
|
| / \ |
|
|
| / \ |
|
|
| / \ |
|
|
| "Classes" "Users" |
|
|
| / \ |
|
|
| / \ |
|
|
| / ["joe"] |
|
|
| / / \ |
|
|
| | / \ |
|
|
| /\ / \ |
|
|
| / \ "joe" "bob" |
|
|
| / \ / \ |
|
|
| / \ |
|
|
| "{xxxx-xx-1}" "{xxxx-xx-2}" ["c:/joe"] ["d:/Robert"] |
|
|
| | | |
|
|
| /\ /\ |
|
|
| / \ / \ |
|
|
| / \ / \ |
|
|
| "Library" "Version" "Library" "Version" |
|
|
| / \ / \ |
|
|
| ["foo.dll"] 2 ["bar.dll"] 1 |
|
|
| |
|
|
| In this example, there are 2 keys under the root: "Classes" and "Users". |
|
|
| The first denotes a subtree only (which has two subtrees, ...). The second |
|
|
| denotes both a value ["joe"] and two subtrees labelled "joe" and "bob". |
|
|
| The value at the node "/Users" is ["joe"], at "/Users/bob" is ["d:/Robert"]. |
|
|
| The value at "/Classes/{xxxx-xx-1}/Version" is 2. |
|
|
| |
|
|
| The registry interface provides functions that let you navigate the tree |
|
|
| and manipulate it's contents. |
|
|
| |
|
|
| Please note that the registry itself does not impose any structure or |
|
|
| meaning on the contents of the tree. For example, the registry doesn't |
|
|
| control whether the value at the key "/Users" is the label for the subtree |
|
|
| with information about the last active user. That meaning is applied by |
|
|
| the code that stores these values and uses them for that purpose. |
|
|
| |
|
|
| [Any resemblence between this example and actual contents of any actual |
|
|
| registry is purely coincidental.] |
|
|
------------------------------------------------------------------------------*/
|
|
struct nsIRegistry : public nsISupports {
|
|
/*------------------------------ Constants ---------------------------------
|
|
| The following enumerated types and values are used by the registry |
|
|
| interface. |
|
|
--------------------------------------------------------------------------*/
|
|
typedef enum {
|
|
String = 1,
|
|
Int32,
|
|
Bytes,
|
|
File
|
|
} DataType;
|
|
|
|
/*-------------------------------- Types -----------------------------------
|
|
| The following data types are used by this interface. All are basically |
|
|
| opaque types. You obtain objects of these types via certain member |
|
|
| function calls and re-use them later (without having to know what they |
|
|
| contain). |
|
|
| |
|
|
| Key - Placeholder to represent a particular node in a registry |
|
|
| tree. There are 3 enumerated values that correspond to |
|
|
| specific nodes: |
|
|
| Common - Where most stuff goes. |
|
|
| Users - Special subtree to hold info about |
|
|
| "users"; if you don't know what goes |
|
|
| here, don't mess with it. |
|
|
| CurrentUser - Subtree under Users corresponding to |
|
|
| whatever user is designed the "current" |
|
|
| one; see note above. |
|
|
| You can specify any of these enumerated values as "keys" |
|
|
| on any member function that takes a nsRegistry::Key. |
|
|
| ValueInfo - Structure describing a registry value. |
|
|
--------------------------------------------------------------------------*/
|
|
typedef uint32 Key;
|
|
|
|
enum { Users = 1, Common = 2, CurrentUser = 3 };
|
|
|
|
struct ValueInfo {
|
|
DataType type;
|
|
uint32 length;
|
|
};
|
|
|
|
static const nsIID& GetIID() { static nsIID iid = NS_IREGISTRY_IID; return iid; }
|
|
|
|
/*--------------------------- Opening/Closing ------------------------------
|
|
| These functions open the specified registry file (Open() with a non-null |
|
|
| argument) or the default "standard" registry file (Open() with a null |
|
|
| argument or OpenDefault()). |
|
|
| |
|
|
| Once opened, you can access the registry contents via the read/write |
|
|
| or query functions. |
|
|
| |
|
|
| The registry file will be closed automatically when the registry object |
|
|
| is destroyed. You can close the file prior to that by using the |
|
|
| Close() function. |
|
|
--------------------------------------------------------------------------*/
|
|
NS_IMETHOD Open( const char *regFile = 0 ) = 0;
|
|
NS_IMETHOD OpenDefault() = 0;
|
|
NS_IMETHOD Close() = 0;
|
|
|
|
/*----------------------- Reading/Writing Values ---------------------------
|
|
| These functions read/write the registry values at a given node. |
|
|
| |
|
|
| All functions require you to specify where in the registry key to |
|
|
| get/set the value. The location is specified using two components: |
|
|
| o A "base key" indicating where to start from; this is a value of type |
|
|
| nsIRegistry::Key. You use either one of the special "root" key |
|
|
| values or a subkey obtained via some other member function call. |
|
|
| o A "relative path," expressed as a sequence of subtree names |
|
|
| separated by forward slashes. This path describes how to get from |
|
|
| the base key to the node at which you want to store the data. This |
|
|
| component can be a null pointer which means the value goes directly |
|
|
| at the node denoted by the base key. |
|
|
| |
|
|
| When you request a value of a given type, the data stored at the |
|
|
| specified node must be of the type requested. If not, an error results. |
|
|
| |
|
|
| GetString - Obtains a newly allocated copy of a string type value. The |
|
|
| caller is obligated to free the returned string using |
|
|
| PR_Free. |
|
|
| SetString - Stores the argument string at the specified node. |
|
|
| GetInt - Obtains an int32 value at the specified node. The result |
|
|
| is returned into an int32 location you specify. |
|
|
| SetInt - Stores a given int32 value at a node. |
|
|
| GetBytes - Obtains a byte array value; this returns both an allocated |
|
|
| array of bytes and a length (necessary because there may be |
|
|
| embedded null bytes in the array). You must free the |
|
|
| resulting array using PR_Free. |
|
|
| SetBytes - Stores a given array of bytes; you specify the bytes via a |
|
|
| pointer and a length. |
|
|
| GetIntArray - Obtains the array of int32 values stored at a given node. |
|
|
| The result is composed of two values: a pointer to an |
|
|
| array of integer values (which must be freed using |
|
|
| PR_Free) and the number of elements in that array. |
|
|
| SetIntArray - Stores a set of int32 values at a given node. You must |
|
|
| provide a pointer to the array and the number of entries. |
|
|
--------------------------------------------------------------------------*/
|
|
NS_IMETHOD GetString( Key baseKey, const char *path, char **result ) = 0;
|
|
NS_IMETHOD SetString( Key baseKey, const char *path, const char *value ) = 0;
|
|
NS_IMETHOD GetInt( Key baseKey, const char *path, int32 *result ) = 0;
|
|
NS_IMETHOD SetInt( Key baseKey, const char *path, int32 value ) = 0;
|
|
NS_IMETHOD GetBytes( Key baseKey, const char *path, void **result, uint32 *len ) = 0;
|
|
NS_IMETHOD SetBytes( Key baseKey, const char *path, void *value, uint32 len ) = 0;
|
|
NS_IMETHOD GetIntArray( Key baseKey, const char *path, int32 **result, uint32 *len ) = 0;
|
|
NS_IMETHOD SetIntArray( Key baseKey, const char *path, const int32 *value, uint32 len ) = 0;
|
|
|
|
/*------------------------------ Navigation --------------------------------
|
|
| These functions let you navigate through the registry tree, querying |
|
|
| its contents. |
|
|
| |
|
|
| As above, all these functions requires a starting tree location ("base |
|
|
| key") specified as a nsIRegistry::Key. Some also require a path |
|
|
| name to locate the registry node location relative to this base key. |
|
|
| |
|
|
| AddSubtree - Adds a new registry subtree at the specified |
|
|
| location. Returns the resulting key in |
|
|
| the location specified by the third argument |
|
|
| (unless that pointer is 0). |
|
|
| AddSubtreeRaw - Adds a new registry subtree at the specified |
|
|
| location. Returns the resulting key in |
|
|
| the location specified by the third argument |
|
|
| (unless that pointer is 0). |
|
|
| Does not interpret special chars in key names. |
|
|
| |
|
|
| RemoveSubtree - Removes the specified registry subtree or |
|
|
| value at the specified location. |
|
|
| RemoveSubtreeRaw - Removes the specified registry subtree or |
|
|
| value at the specified location. |
|
|
| Does not interpret special chars in key names. |
|
|
| |
|
|
| GetSubtree - Returns a nsIRegistry::Key that can be used |
|
|
| to refer to the specified registry location. |
|
|
| GetSubtreeRaw - Returns a nsIRegistry::Key that can be used |
|
|
| to refer to the specified registry location. |
|
|
| Does not interpret special chars in key names. |
|
|
| |
|
|
| EnumerateSubtrees - Returns a nsIEnumerator object that you can |
|
|
| use to enumerate all the subtrees descending |
|
|
| from a specified location. You must free the |
|
|
| enumerator via Release() when you're done with |
|
|
| it. |
|
|
| EnumerateAllSubtrees - Like EnumerateSubtrees, but will recursively |
|
|
| enumerate lower-level subtrees, too. |
|
|
| GetValueInfo - Returns a uint32 value that designates the type |
|
|
| of data stored at this location in the registry; |
|
|
| the possible values are defined by the enumerated |
|
|
| type nsIRegistry::DataType. |
|
|
| GetValueLength - Returns a uint32 value that indicates the length |
|
|
| of this registry value; the length is the number |
|
|
| of characters (for Strings), the number of bytes |
|
|
| (for Bytes), or the number of int32 values (for |
|
|
| Int32). |
|
|
| EnumerateValues - Returns a nsIEnumerator that you can use to |
|
|
| enumerate all the value nodes descending from |
|
|
| a specified location. |
|
|
--------------------------------------------------------------------------*/
|
|
NS_IMETHOD AddSubtree( Key baseKey, const char *path, Key *result ) = 0;
|
|
NS_IMETHOD RemoveSubtree( Key baseKey, const char *path ) = 0;
|
|
NS_IMETHOD GetSubtree( Key baseKey, const char *path, Key *result ) = 0;
|
|
|
|
NS_IMETHOD AddSubtreeRaw( Key baseKey, const char *keyname, Key *result ) = 0;
|
|
NS_IMETHOD RemoveSubtreeRaw( Key baseKey, const char *keyname ) = 0;
|
|
NS_IMETHOD GetSubtreeRaw( Key baseKey, const char *keyname, Key *result ) = 0;
|
|
|
|
NS_IMETHOD EnumerateSubtrees( Key baseKey, nsIEnumerator **result ) = 0;
|
|
NS_IMETHOD EnumerateAllSubtrees( Key baseKey, nsIEnumerator **result ) = 0;
|
|
|
|
NS_IMETHOD GetValueType( Key baseKey, const char *path, uint32 *result ) = 0;
|
|
NS_IMETHOD GetValueLength( Key baseKey, const char *path, uint32 *result ) = 0;
|
|
|
|
NS_IMETHOD EnumerateValues( Key baseKey, nsIEnumerator **result ) = 0;
|
|
|
|
/*------------------------------ User Name ---------------------------------
|
|
| These functions manipulate the current "user name." This value controls |
|
|
| the behavior of certain registry functions (namely, ?). |
|
|
| |
|
|
| GetCurrentUserName allocates a copy of the current user name (which the |
|
|
| caller should free using PR_Free). |
|
|
--------------------------------------------------------------------------*/
|
|
NS_IMETHOD GetCurrentUserName( char **result ) = 0;
|
|
NS_IMETHOD SetCurrentUserName( const char *name ) = 0;
|
|
|
|
/*------------------------------ Utilities ---------------------------------
|
|
| Various utility functions: |
|
|
| |
|
|
| Pack() is used to compress the contents of an open registry file. |
|
|
--------------------------------------------------------------------------*/
|
|
NS_IMETHOD Pack() = 0;
|
|
|
|
}; // nsIRegistry
|
|
|
|
/*------------------------------ nsIRegistryNode -------------------------------
|
|
| This interface is implemented by all the objects obtained from the |
|
|
| nsIEnumerators that nsIRegistry provides when you call either of the |
|
|
| subtree enumeration functions EnumerateSubtrees or EnumerateAllSubtrees. |
|
|
| |
|
|
| You can call this function to get the name of this subtree. This is the |
|
|
| relative path from the base key from which you got this interface. |
|
|
| |
|
|
| GetName - Returns the path name of this node; this is the relative path |
|
|
| from the base key from which this subtree was obtained. The |
|
|
| function allocates a copy of the name; the caller must free it |
|
|
| using PR_Free. |
|
|
------------------------------------------------------------------------------*/
|
|
struct nsIRegistryNode : public nsISupports {
|
|
NS_IMETHOD GetName( char **result ) = 0;
|
|
}; // nsIRegistryNode
|
|
|
|
/*------------------------------ nsIRegistryValue ------------------------------
|
|
| This interface is implemented by the objects obtained from the |
|
|
| nsIEnumerators that nsIRegistry provides when you call the |
|
|
| EnumerateValues function. An object supporting this interface is |
|
|
| returned when you call the CurrentItem() function on that enumerator. |
|
|
| |
|
|
| You use the member functions of this interface to obtain information |
|
|
| about each registry value. |
|
|
| |
|
|
| GetName - Returns the path name of this node; this is the relative |
|
|
| path\ from the base key from which this value was obtained. |
|
|
| The function allocates a copy of the name; the caller must |
|
|
| subsequently free it via PR_Free. |
|
|
| GetValueType - Returns (into a location provided by the caller) the type |
|
|
| of the value; the types are defined by the enumerated |
|
|
| type nsIRegistry::DataType. |
|
|
| GetValueLength - Returns a uint32 value that indicates the length |
|
|
| of this registry value; the length is the number |
|
|
| of characters (for Strings), the number of bytes |
|
|
| (for Bytes), or the number of int32 values (for |
|
|
| Int32). |
|
|
------------------------------------------------------------------------------*/
|
|
struct nsIRegistryValue : public nsISupports {
|
|
NS_IMETHOD GetName( char **result ) = 0;
|
|
NS_IMETHOD GetValueType( uint32 *result ) = 0;
|
|
NS_IMETHOD GetValueLength( uint32 *result ) = 0;
|
|
}; // nsIRegistryEntry
|
|
|
|
|
|
/*------------------------------- Error Codes ----------------------------------
|
|
------------------------------------------------------------------------------*/
|
|
#define NS_ERROR_REG_BADTYPE NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 1 )
|
|
#define NS_ERROR_REG_NO_MORE NS_ERROR_GENERATE_SUCCESS( NS_ERROR_MODULE_REG, 2 )
|
|
#define NS_ERROR_REG_NOT_FOUND NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 3 )
|
|
#define NS_ERROR_REG_NOFILE NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 4 )
|
|
#define NS_ERROR_REG_BUFFER_TOO_SMALL NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 5 )
|
|
#define NS_ERROR_REG_NAME_TOO_LONG NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 6 )
|
|
#define NS_ERROR_REG_NO_PATH NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 7 )
|
|
#define NS_ERROR_REG_READ_ONLY NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 8 )
|
|
#define NS_ERROR_REG_BAD_UTF8 NS_ERROR_GENERATE_FAILURE( NS_ERROR_MODULE_REG, 9 )
|
|
|
|
#endif
|