<< Previous | Next >>

registry_write

int registry_write( RegistryContext * r, char far * section, RegistryEntry far * entries);

Description

Modify the old registry r->old_spec using the specified registry entries, writing the result to r->new_spec. Only entries in the named "section" may be altered. This function also allows entries and sections to be deleted.

The new and old files must be different, since this function depends on reading from the old file, performing the requested modifications, and writing the new file -- this is all done line-by-line. Generally, you will need two resource files which will alternate. Only when the modifications are successfully complete will the old file be deleted. This makes the update process more resistant to corruption caused by e.g., the user turning off the power in the middle of the update. The helper function registry_prep_write() automates this process.The function registry_update() encapsulates the basic registry update process.

NOTE: since this function requires some temporary malloc memory, you should ensure that there is at least _REGBUF_SIZE bytes of available system-space malloc memory. The _REGBUF_SIZE macro defaults to 1025 bytes, but you may override this definition before #use registry.lib.

Registry resources are similar to Windows ".ini" file format. They are ASCII formatted (and thus human readable) and consist of one or more "sections," each of which has zero or more key=value lines. For example:

   

[net settings]
ip=10.10.6.100
ssid=Rabbit
[app settings]
some integer=23
a string=hello world

Each section is headed by a string enclosed in square brackets. Within each section is a list of key strings followed by '=' followed by the value of that entry. The key string is arbitrary except that it cannot start with '[' or contain any '=', null or newline characters. The value string is arbitrary except that newline and null characters are not allowed. Section names are arbitrary except they cannot contain ']', null or newline characters. Spaces are always significant. In particular, don't put spaces on either side of the '=' separator.

If there are duplicate keys in the entries table, then it is undefined which of the entries actually gets stored. Don't do it.

Normally, you do not need to be concerned with the above format rules, since the library functions enforce them.

If you need to store null (binary zero) or newline (binary 0x0A or, in C syntax, "\n") then your application will need to use some sort of convention for escaping such characters, or you can use the REGOPTION_BIN() option which will store the string expanded into ASCII hexadecimal, which is completely safe.

Individual key/value entries may be deleted by specifying the REGOPTION_DELETE flag with the appropriate entries.

Parameters

r

RegistryContext structure, with at least the old_spec and new_spec fields initialized. For example, use registry_prep_write() to set up this structure correctly.

r ->old_spec:

Open resource handle of a readable resource containing the old registry settings. This is read from the current seek position, thus in most cases you will want to call this function with a freshly opened resource handle. This may also be -1, which indicates there is *no* old registry to update, and a new registry will be written to new_spec.

r->new_spec: Open resource handle of a writable resource, to which the old registry (modified with the given settings) will be written. Normally, this should initially be an empty resource file. The new settings will be written starting at the current seek position in this resource.

Note that the resource handles remain open when this function returns.

section

Section name. If NULL or empty string, then the first (anonymous) section of the registry is implied.

entries

List of replacement registry entries. The list MUST be terminated with an entry with the REGOPTION_EOL option.

Caution: If this pointer is NULL, then the entire section is deleted.

Each element in this array is as follows:

typedef struct {
   char far *  key;         // Entry key. Must not contain '=' or newlines, and
                            // must not start with '['.  Must be null-terminated.
   void far *  value;       // Entry value.  Type determined by options.  If the
                            // REGOPTION_STRING option is set, this must
                            // not contain newlines and must be null terminated.
   int  options;            // Entry options and flags:  If value is greater
                            // than zero, then value is an arbitrary binary
                            // value with the specified length.  It will be
                            // stored in the registry with twice that many
                            // ascii hex digits.  If value is <= -10, then it i
                            // ascii string with max length of (-options-8)
                            // Otherwise, this field is a simple enumeration
                            // indicating the data type as follows:
   #define REGOPTION_EOL     0  // End of list
   #define REGOPTION_SHORT (-1) // Signed short (2 byte) - stored as decimal
   #define REGOPTION_LONG  (-2) // Signed long (4 byte) - tored as decimal
   #define REGOPTION_BOOL  (-3) // int (2 byte) - stored as 1 (if non-zero) or 0
   #define REGOPTION_FLOAT (-4) // IEEE float (4 byte)
                                // Only avail if STDIO_DISABLE_FLOATS 
                                // *not* defined, stored in %f format
   #define REGOPTION_RESV5    (-5)
   #define REGOPTION_RESV6    (-6)
   #define REGOPTION_DELETE   (-7) // Delete this entry if found
   #define REGOPTION_NOP      (-8) // No operation: convenience for 
                                   // constructingRegistryEntry lists.
   #define REGOPTION_RESV9    (-9) // For variable length data...


   #define REGOPTION_BIN(len) (len)
   // Binary of given fixed length - stored expanded into ascii hexadecimal.
   // len must be 1.._REGBUF_SIZE/2-M where M is the size of the key plus 2.
   // As a rule of thumb, be careful when len is more than about 256.

   #define REGOPTION_STRING(len) (-8-(len))
   // Null-terminated string up to len chars counting the null terminator - stored as-is.
   //  len must be at least 2. len must not be more than _REGBUF_SIZE-M where M is the
   // size of the key plus 2. As a rule of thumb, be careful when len is more than about 512.

   word work;                  // Work field for registry read/write lib functions
   // May be left uninitialized by the caller unless otherwise noted in the function description.
} RegistryEntry;

Return Value

<0: failure to write or read the resource
 0: success

Library

REGISTRY.LIB

See Also

sspec_open, registry_read, registry_update, registry_get, registry_prep_write, registry_finish_write