This is a package which provides a simple registry (similar to the Microsoft Windows registry) for the Rex.
Programs can store and retrieve text strings, 32-bit values and binary buffers using the registry.
The core function is to maintain a database indexed by key name containing the registered values.
Each record has fields for both DWORD values and variable length data. One or other of these fields are used depending on a TYPE field.
Unlike Microsoft's registry, this registry is not actually structured with a containment hierarchy. The keys are just text strings.
There is no user interface to allow editing of the registry. The existing REGmaint program just allows basic database maintenance and REGedit can only handle exporting the whole registry to a memo or importing keys from a memo.
The addin programmer has a choice of two forms of the library to use:
registry.lib
, any required library routines are included
in the addin and no extra programs are required to run it.
Note that if the import or export routines are used then the
GRCLIB and MemoIO libraries must also be linked in.
registry-so.lib
, a minimum amount of code
is included in to the addin and the library routines themselves are accessed from the
registry.rex
and registry2.rex
shareable library addins.
In this case, the GRCLIB library must also be included
in the link.
It is recommended that -lgrclib is used unless the addin already requires the GRCLIB shareable library (-lgrclib-so).
Consumers must both include registry.h and link with either registry.lib or registry-so.lib. The libraries should be put in ../../lib/clibs and linked using -lregistry or -lregistry-so.
There are three functions used to write values into the registry:
int reg_write_sz(char *keyname, char *value)
char *keyname -- registry key text string
char *value -- value to write (zero terminated text string)
return value -- if less than zero, an error code; if greater than or equal to zero, success
int reg_write_dword(char *keyname, unsigned long value)
char *keyname -- registry key text string
unsigned long value -- value to write
return value -- if less than zero, an error code; if greater than or equal to zero, success
Note: if specifying a constant value, it should be a long contant (e.g. "2L").
int reg_write_binary(char *keyname, unsigned char *value, unsigned short length)
char *keyname -- registry key text string
unsigned char *value -- pointer to data to write
unsigned short length -- length of data to write
return value -- if less than zero, an error code; if greater than or equal to zero, success
There are three functions used to read values from the registry:
int reg_read_sz(char *keyname, char *buffer, unsigned short max_length)
char *keyname -- registry key text string
char *buffer -- pointer to buffer to receive text string
unsigned short max_length -- maximum length of data to retrieve (including zero terminator)
return value -- if less than zero, an error code; if greater than or equal to zero, the length of the string actually copied to the buffer
Note 1: if the buffer is long enough, the full string value will be copied to the buffer, including the zero terminator, and the length of the string (excluding the zero terminator) will be returned.
Note 2: if the buffer is not long enough, max_length-1 bytes will be copied, the last byte will be zeroed and the length actually copied (excluding the zero terminator) will be returned.
Note 3: the expression REG_MAX_VALUE+1 can be used to allocate a buffer guaranteed to be long enough for any string value.
int reg_read_dword(char *keyname, unsigned long *p_value)
char *keyname -- registry key text string
unsigned long *p_value -- pointer to long int to receive the value
return value -- if less than zero, an error code; if greater than or equal to zero, success
Note: if an error is returned (in particular, REG_ERR_WRONG_TYPE), the output parameter (pointed to by p_value) may have been modified -- the contents are undefined.
int reg_read_binary(char *keyname, char *buffer, unsigned short max_length)
char *keyname -- registry key text string
char *buffer -- pointer to buffer to receive binary data
unsigned short max_length -- maximum length of data to retrieve
return value -- if less than zero, an error code; if greater than or equal to zero, the length of the data actually copied to the buffer
Note 1: if the buffer is long enough, the full binary value will be copied to the buffer and the length of the data will be returned. The contents of the buffer beyond the copied data are undefined.
Note 2: if the buffer is not long enough, max_length bytes will be copied, and the length actually copied will be returned.
Note 3: the constant REG_MAX_VALUE can be used to allocate a buffer guaranteed to be long enough for any binary value.
int reg_delete(char *keyname)
char *keyname -- prefix of registry keys to be deleted
return value -- if less than zero, an error code; if greater than or equal to zero, success
Note 1: reg_delete will delete all keys which have the specified prefix.
Note 2: if no keys match the prefix, the error REG_ERR_NOT_FOUND will be returned. The caller may or may not consider this an error.
The routines described above assume the database exists. If you want to make sure the database exists, call reg_database_create(). The return value is either an error code (if less than zero) or success (if greater than or equal to zero).
Note that if the database already exists, this routine will return success and will not modify the database.
Future versions of this library may change the database format. To check that the database format is consistent with your version of the library, call reg_version_check(). This returns an error code if the database version is inconsistent.
Note: reg_database_create automatically includes this check so you do not need to call reg_version_check if you have called reg_database_create.
It is possible to import registry values from a Memo. The Memo must have the following format (based on the Microsoft .reg format):
[
.
Note: Microsoft .reg files contain a line containing REGEDIT4
followed by a blank line.
[keyname]
specifies the key prefix for the subsequent
records. Another line of the same form replaces the key for subsequent records.
Note: Microsoft structures keys with \ separating levels. REX supports either \ or / as separator.
name=value
.
These represent the registry entries themselves.
@
or "name-string"
.
@
represents a null name (this corresponds to Microsoft's default value).
name-string can use backslash (\) quoting so "abc\"def"
is a valid name.
The name is appended on to the keyname, separated by a /.
"string-value"
is used for string (SZ) entries.
Unlike for the name, backslash quoting is not used with string values. The last "
on the line is taken as the end of the string -- any previous "
is part of the
value.
dword:hex-long
is used for 32-bit (DWORD) values.
The hex-long is up to 8 hex digits representing the value.
hex:bytes
is used for arbitrary binary values (BINARY).
bytes is a comma separated list of pairs of hex digits -- each pair represents one byte.
The list may be empty.
int reg_import_memo(const char *memo_name)
const char *memo_name
-- name of memo
Any sub-tree of the registry may be exported to a Memo.
The Memo will be in a format compatible with reg_import_memo
and Microsoft's
.reg files.
int reg_export_memo(char *keyname, const char *memo_name)
const char *keyname
-- prefix of keys to export
const char *memo_name
-- name of memo
Copyright (C) 2001, 2002 Graham R. Cobb. The package is distributed under the GPL (see the copyright notices and the COPYING file).
REGISTRY For Rex 6000 is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
REGISTRY For Rex 6000 is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
When the ZIPfile is expanded, it creates the key library files (and several informational files) in the current directory and creates several source subdirectories.
The package itself:
Registry import/export utility.
This utility can be used to import a set of keys and values from a Memo, using the same format as Microsoft's .reg files.
The utility can also export the entire database to a Memo with a fixed name (Registry Export). It cannot export portions of the registry tree nor can it be used to edit the tree.
The utility is linked with the shareable library versions of GRClib, REGISTRY and MemoIO so all these shareable libraries must be loaded.
Registry database maintenance utility. Can be used to create the database, examine the database and delete the database.
Sample addin using the registry.
Add REG_ERR_NO_REGISTRY error if shareable library not loaded. This allows code to try a registry lookup but to react gracefully if the registry library is not loaded.
Link with new FindLib from August 2002 RexDk
Fix unintended dependency on GRCLIB library addin.
Convert to new Rexdk shareable library mechanism.
Add second shareable library.
Add shareable library.
Add import/export.