Edit

Registry Run-Time Library Routines

  • Article

To manipulate registry entries, drivers can call the RtlXxxRegistryXxx routines, which provide a simpler interface than the ZwXxxKey routines. When doing so, the driver is not required to open and close handles; instead, the driver refers to keys by name.

You pass RelativeTo and Path parameters to each RtlXxxRegistryXxx routine. If RelativeTo is RTL_REGISTRY_ABSOLUTE, Path specifies the full path of the key, beginning with the \Registry root. If RelativeTo is RTL_REGISTRY_HANDLE, Path is actually an open handle. Additional RTL_REGISTRY_XXX values for RelativeTo specify the paths of common roots for the key; in these cases, Path specifies the path relative to that root. For example, RTL_REGISTRY_USER requires that Path be relative to the current user's registry settings. (This value is equivalent to specifying HKEY_CURRENT_USER in a user-mode application.) For a description of all the RTL_REGISTRY_XXX values, see RtlCheckRegistryKey.

The following table list the operations that drivers can perform by calling the RtlXxxRegistryXxx routines.

Operation RtlXxxRegistryXxx routine to call

Create a registry key

RtlCreateRegistryKey

Check whether a registry key exists

RtlCheckRegistryKey

Examine one or more registry-key values

RtlQueryRegistryValues

Write a registry-key value

RtlWriteRegistryValue

Delete a registry-key value

RtlDeleteRegistryValue

The following code example illustrates how to set ValueName for \Registry\Machine\System\KeyName to a ULONG value of 0xFF. Compare this example with the corresponding one in the Registry Key Object Routines section.

NTSTATUS status;
ULONG data = 0xFF;

status = RtlWriteRegistryValue(RTL_REGISTRY_ABSOLUTE,
                               (PWCSTR)L"\\Registry\\Machine\\System\\KeyName",
                               (PWCSTR)L"ValueName",
                               REG_DWORD,
                               &data,
                               sizeof(ULONG));

Although you write fewer lines of code when using the RtlXxxRegistryXxx routines instead of the ZwXxxKey routines, the latter ones are necessary for performing certain operations. For example, no RtlXxxRegistryXxx routine exists that corresponds to ZwEnumerateKey.

If you perform multiple operations on the same key, the ZwXxxKey routines are more efficient—you can use the same open handle for each operation. In contrast, the RtlXxxRegistryXxx routines open and close a new handle for each operation.