<< Previous | Next >>

registry_prep_read

int registry_prep_read( RegistryContext * r, char * basename, ServerContext * context);

Description

Prepare for reading a registry. This function helps organize registry resources in order to create a robust registry.

Most applications will use the sequence of functions:

   

registry_prep_read()
registry_read() and/or registry_enumerate()
registry_finish_read()

or simply

   

registry_get()

Registry updates require reading from an old registry, editing it, then writing the modified result to a new registry resource. This requires two resources to be open. Normally, the "old" registry will be deleted once the update is successful. If there is a power outage or reset during this process, it is possible for two registry files to exist when the system is restarted. This causes problems, since one of the registries may be corrupt. This API imposes a naming convention on the old/new resources so that a non-corrupt registry can always be found.

The algorithm used appends an extension to the basename resource name. The extension is ".1", ".2" or ".3". The "current" registry resource will cycle through these extensions. It is assumed that exactly 0, 1 or 2 of these resources will exist at any time. This means that at least one of the possible resource names will not exist. (If all three exist, then the behavior is undefined, since the resources must have been created outside the registry system. The application is responsible for ensuring this does not happen, otherwise the ability to find a non-corrupt registry will be compromised).

If none of the resources exist, then this indicates a brand new registry. If exactly one exists, then this is the old (and presumed non-corrupt) registry. If two exist, it is assumed that one of the resources is OK and the other corrupt. Since there are only 3 possible extensions, and they increment in wrap-around fashion, the "lowest" numbered extension is assumed to be the non-corrupt one, with "lowest" being in the sense of modulo 3. This is summarized in the following table:

Existing Extensions	Assumed Non-corrupt
-	None, new registry
1	1
2	2
3	3
1,2	1 (2 will be deleted)
2,3	2 (3 will be deleted)
1,3	3 (1 will be deleted)
1,2,3	Should not happen - will arbitrarily pick 1 and delete 2,3.

In the case that more than one registry extension was found, the presumed corrupt resource is automatically deleted to clean up the registry.

Parameters

r

RegistryContext structure. This is used to pass information in a consistent manner between the major registry API functions. It may be passed uninitialized to this function. This function fills in the r->old_spec field to indicate the open resource which will be used by registry_read(). The value may also be set to -1 if there was an error or no existing resource could be located.

basename

Base name (including path) of the registry This should NOT include any extension (e.g. ".foo") since the extension is manipulated by this function. In practice, this will need to be a resource name on non-volatile storage, which supports names with extensions. In practice, this limits the appropriate filesystem to FAT filesystem only. For example

registry_prep_read("/A/myreg", &spec);

will select from a set of registry files called /A/myreg.1, /A/myreg.2, /A/myreg.3 of which, normally, only one will exist at any time.

context

ServerContext struct. E.g. from http_getContext().

Return Value

<0: General failure, code will be negative of one of the codes in ERRNO.LIB.
0: there is currently no resource of the given name. This is not necessarily an error, since it will be returned if the registry has not yet been created.
1,2,3: An existing presumed non-corrupt resource has been opened. The numeric return code indicates which of the extensions was located.

Library

register.lib

See Also

registry_read, registry_finish_read, registry_prep_write, registry_write, registry_finish_write, registry_enumerate, registry_update, registry_get