Ah, the Registry. This mysterious object that appeared with the introduction of OLE under Windows 3.1. No matter how hard we programmer types were trying to ignore it, it is here to stay; in fact, while we were looking the other way it quietly took over the role of initialization, or INI files, among other things.
But what is it? Perhaps more importantly, what should you, the Win32 programmer, know about it? How can you access and manipulate it from within your applications? These are the questions that I attempt to answer in this chapter.
The Registry is a hierarchically organized store of information. Each entry in this tree-like information structure is called a key. A key may contain any number of subkeys; it can also contain data entries called values. In this form, the Registry stores information about the system, its configuration, hardware devices, and software applications. It also assumes the role of the ubiquitous INI files by providing a place where application-specific settings can be stored.
A Registry key is identified by its name. Keynames consist of printable ASCII characters except the backslash (\), space, and wildcard (* or ?) characters. The use of keynames that begin with a period (.) is reserved. Keynames are not case sensitive.
A value in the Registry is identified by its name. Value names consist of the same characters as keynames. The value itself can be a string, binary data, or a 32-bit unsigned value.
There are some apparent differences between the behavior of the Windows 95 and the Windows NT Registries. The Windows 95 Registry appears to allow for the assignment of a value to a Registry key (as opposed to a value name); this appears as the default value for that key. Upon closer examination, however, one finds that this is a superficial difference. The default value for a key is really a value with an empty name; empty names are also permitted in the Windows NT Registry. Perhaps the only difference is that the value with the empty name appears to be always defined for a key in the Windows 95 Registry, while it must be explicitly created in the Windows NT Registry.
Another apparent difference between the two Registries is the existence of a variety of string types in the Windows NT Registry, whereas Windows 95 appears to support only one string type. But is this really the case? Jumping a bit ahead of myself here, let me show you some of the output created by the Registry reader program that we examine later in this chapter. For example, look at the following output:
Enter key: HKEY_CURRENT_USER\Environment\include
Expandable string: f:\msvc20\include;f:\msvc20\mfc\include
However, if you examine the same value using the Windows 95 Registry Editor, it will appear as a binary value. But this is a shortcoming of the Registry Editor, not the Registry itself.
Table 16.1 contains a list of all value types that can go into the Windows 95 and Windows NT Registries.
Table 16.1. Registry value types.
Raw binary data
Double word in machine format (low-endian on Intel)
Generally, it is not recommended to store items larger than a kilobyte or two in the Registry. For larger items, use a separate file, and use the Registry for storing the filename.
Under Windows 95, Registry values are limited to 64KB in size.
Another consideration when using the Registry is that storing a key generally requires substantially more storage space than storing a value. Whenever possible, organize values under a common key rather than using several keys for the same purpose.
The HKEY_LOCAL_MACHINE key contains entries that describe the computer and its configuration. This includes information about the processor, system board, memory, and installed hardware and software.
The HKEY_CLASSES_ROOT key is the root key for information relating to document types and OLE types. This key is a subordinate key to HKEY_LOCAL_MACHINE. (It is equivalent to HKEY_LOCAL_MACHINE\SOFTWARE\Classes.) Information that is stored here is used by shell applications such as the Program Manager, File Manager, or the Explorer, and by OLE applications.
The HKEY_USERS key serves as the root key for the default user preference settings as well as individual user preferences.
The HKEY_CLASSES_USER key is the root key for information relating to the preferences of the current (logged in) user.
Under Windows 95, there are two additional predefined keys. The HKEY_CURRENT_CONFIG key contains information about the current system configuration settings. This key is equivalent to a subkey (such as 0001) of the key HKEY_LOCAL_MACHINE\Config.
The HKEY_DYN_DATA key provides access to dynamic status information, such as information about plug and play devices.
The predefined keys and their relationships are illustrated in Figure 16.1.
The Registry can be manually edited using the Registry Editor. This program is named regedt32.exe under Windows NT and regedit.exe under Windows 95. The Windows NT program regedit.exe is a version of the Registry Editor that offers behavior similar to the 16-bit Windows Registry Editor. This program is not very useful when editing the Registry as it only sees a subset of Registry keys.
Figure 16.2 shows the Windows 95 Registry Editor in operation.
Needless to say, using the Registry Editor is a last resort solution. Programmers may need to frequently access the Registry this way (for example, to remove keys that have been placed there by misbehaving applications that are under development). However, end users should never be required to manually change Registry settings.
Many Registry settings are controlled implicitly through configuration applications such as the Control Panel. Other Registry settings are created during application installation. OLE applications that have been created using AppWizard update their Registry settings every time they run.
Keys in HKEY_LOCAL_MACHINE contain information about the computer's software and hardware configuration. Of these, the Config and Enum subkeys are specific to Windows 95 and its plug and play capabilities. The Config subkey is where Windows 95 stores various hardware configurations; the Enum subkey contains Windows 95 bus enumerators that build the tree of hardware devices.
Both Windows 95 and Windows NT maintain the System subkey under HKEY_LOCAL_MACHINE. The System\CurrentControlSet subkey contains configuration information for services and device drivers.
Other subkeys in HKEY_LOCAL_MACHINE include Software and Classes. The Software subkey is where information about installed software packages can be found. The Classes subkey is where HKEY_CLASSES_ROOT points to.
The Software subtree is of peculiar interest to application programmers. This is where you should store configuration and installation information specific to your application. Microsoft recommends that you build a series of subtrees under HKEY_LOCAL_MACHINE\Software. These subkeys should represent your company name, the name of your product, and the product's version number:
What you store under such a key is entirely application-dependent. Note that you should not store anything here that is user-specific; user-specific information pertinent to your application should be organized under a subkey of HKEY_CURRENT_USER.
This key actually has a curious, unexpected role under Windows 95. I presume the reason is to maintain compatibility with 32-bit debuggers originally written for Windows NT, but debugger information stored under the key
The HKEY_CLASSES_ROOT key contains two types of subkeys: subkeys that correspond to filename extensions and class definition subkeys.
A filename extension subkey has a name that corresponds to the filename extension (such as .doc). The key typically contains one unnamed value, which holds the name of the class definition subkey.
A class definition subkey describes the behavior of a document class. The information stored here includes data on shell and OLE-related properties.
A subkey under HKEY_CLASSES_ROOT is CLSID. This is the place where OLE class identifiers are stored.
When you create an MFC application using the Visual C++ AppWizard, a series of subkeys that are to be installed under HKEY_CLASSES_ROOT are also created. These identify the document type and filename extension of your new application and also its OLE properties such as the OLE class identifier. For example, creating an MFC application named Test with a file extension .tst for its document files yielded the following Registry entries under HKEY_CLASSES_ROOT:
The key HKEY_USERS contains a subkey named .Default and zero or more subkeys corresponding to users on the system. The .Default subkey corresponds to the default user profile. Other entries correspond to profiles of existing users.
The HKEY_CURRENT_USER key corresponds to the profile of the currently logged in user. This key has several subkeys, some common to both Windows 95 and Windows NT, some specific to one or the other.
Application configuration information specific to the current user should be stored under the subkey Software. Information should be organized by keys corresponding to company name, product name, and product version number. For example, user settings for Microsoft Excel 5.0 can be found under the key
The user's settings and preferences for Windows, its components, and applets can be found under the key
In new applications, the Registry should be used instead of INI files. This is obvious; but what about old applications, how would they behave under 32-bit Windows?
As it turns out, their behavior is different under Windows NT and Windows 95. In order to maintain maximum backward compatibility, Windows 95 still maintains INI files, such as a win.ini file or a system.ini file. These files do not exist under Windows NT. Instead, Windows NT maps these files to the Registry.
Which files are mapped and which are not is determined by the settings under the key
This key contains a subkey for every mapped INI file. Values under such a subkey correspond to sections in the INI file and typically point to other keys in the Registry.
The mapping of INI files affects the operation of functions such as ReadProfileString or WriteProfileString. If a mapping exists for the specified INI file, these functions will read from and write to the Registry as opposed to an actual INI file.
All access to the Registry is performed through handles. In order to access a key in the Registry, applications must use a handle to an existing, open key. There are several predefined key handles that are assumed to be always open. These handles include the following: HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, HKEY_CURRENT_USER.
A Registry key is accessed through the function RegOpenKeyEx. For example, in order to obtain a handle to the Registry key HKEY_LOCAL_MACHINE\Software, one would issue the following call:
To access a subkey under the key HKEY_LOCAL_MACHINE\Software, it is necessary to call RegOpenKeyEx again. For example, to obtain a handle to HKEY_LOCAL_MACHINE\Software\Classes, one would have to issue the following two calls:
A Registry value can be retrieved by calling the RegQueryValueEx function. Before this function can be called, the appropriate subkey must be opened using RegOpenKey.
RegQueryValueEx offers a mechanism that enables applications to find out the memory requirements for storing a value before the value is actually retrieved. If you call this function with a NULL pointer passed as the data buffer pointer, the function will return the requested length of the data buffer without actually copying any data. Thus, it is possible to call RegQueryValueEx twice: first to obtain the length of the buffer, and next to actually copy the data, as in the following example:
Applications can also create a new subkey in the Registry. The RegCreateKeyEx function creates the new key, opens it, and obtains a key handle. This function can also be used to open existing keys; thus it is ideal in situations when the application wishes to access a key whether it already exists or notduring an installation procedure, for example.
Under Windows NT, when creating a new key, the application also assigns security attributes to it. The key's security attributes determine who can access the key for reading and writing. Security information can be obtained about an open key using RegGetKeySecurity and set using RegSetKeySecurity (that is, if the application has the necessary privileges).
There are several other functions that assist in dealing with the Registry efficiently. For example, the RegEnumKeyEx and RegEnumValue functions can be used to enumerate the subkeys and values under a specific Registry key. Registry keys can be deleted using the RegDeleteKey function. Several other functions exist to deal with saving and loading subkeys, connecting to remote Registries, and performing other administrative functions.
To demonstrate the use of the Registry from application programs, I decided to create a simple command-line program to read Registry settings. This program is shown in Listing 16.1. To compile this program from the command line, you must specify the advanced API library: cl readreg.cpp advapi32.lib.
This program demonstrates many aspects of handling the Registry. Execution begins in the main function where the program immediately enters a forever loop (terminate the program by hitting Ctrl+C). After displaying a prompt and reading in a Registry key typed by the user, the program first checks for the presence of the name of any of the top-level keys in the string the user typed. If such a keyname is found, the program begins an iteration.
The string typed by the user is expected to contain backslash characters as key delimiters. In the iteration part, subsequent strings are extracted from the input string using the strcspn function. The iteration proceeds until the last string is extracted, which is assumed to be a value name. The iteration allows for empty (zero-length) names for both keys and values.
During the iteration, a key handle is obtained through RegOpenKeyEx for every string extracted from the user input. If obtaining the key handle fails (presumably because the user specified an invalid key) the iteration stops with an error. However, if the iteration succeeds, the value corresponding to the last extracted string is retrieved by calling RegQueryValueEx. This function is in fact called twice: once to determine the amount of memory required to store the data and a second time to actually retrieve the data.
The value is printed in the printval function. This function takes a pointer to the value and takes the value's type and its length, from which it produces formatted output.
Here is some sample output produced by this program:
Enter key: HKEY_CURRENT_USER\Software\Microsoft\Hover!\HighScoreNames
String 0: Viktor
String 1: Steve
String 2: John
String 3: Patrick
String 4: Jennifer
String 5: Julie
String 6: Jon
String 7: Tony
String 8: Larry
String 9: Harley
Enter key: HKEY_LOCAL_MACHINE\Enum\Monitor\Default_Monitor\0001\ConfigFlags
00 00 00 00
Enter key: HKEY_CURRENT_USER\Environment\include
Expandable string: f:\msvc20\include;f:\msvc20\mfc\include
You may even find this program useful when trying to determine the exact type of a value in the Registry, above and beyond the information provided by the Registry Editor. With some work, the program could be modified to have the capability to actually write to the Registry as well.
The Registry is a place where Windows and applications can store configuration data. The Registry is a tree-like, hierarchically organized information store. Registry entries, or keys, are identified by a name and may contain any number of subkeys or values.
At the top level of the Registry are the root keys HKEY_USERS and HKEY_LOCAL_MACHINE. Other predefined keys include HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_CURRENT_CONFIG, and HKEY_DYN_DATA.
A Registry value can be a 4-byte integer, a string or a series of strings, or arbitrary binary data. Registry values are usually created by application programs, installation procedures, or configuration utilities such as the Control Panel. However, the Registry can also be manually edited using the Registry Editor.
Applications typically store configuration information under HKEY_LOCAL_MACHINE\Software, and user-specific data under HKEY_CURRENT_USER\Software. In both cases, subkeys should be created to correspond to a company name, product name, and product version number.
Additionally, applications that manage specific document types created a filename extension and a class definition entry under HKEY_CLASSES_ROOT. OLE applications also store OLE information here.
The Win32 API provides a series of functions for applications to access the Registry. Using one of the predefined Registry keys, applications can access any subkey for reading and writing, query values, and set values. Applications can also create new keys or delete existing keys.