Using Framework Registry-Key Objects

Framework-based drivers access the registry by using framework registry-key objects. The registry-key object defines methods that enable your driver to create, open, and close registry keys; add and remove registry values; and read or write the data that is assigned to a registry value.

To open a registry key, your driver must call WdfRegistryOpenKey. If the key does not exist, the driver must call WdfRegistryCreateKey, which creates a new key and opens it.

When your driver opens a registry key, the framework creates a registry-key object that represents the opened key and returns an object handle to the driver. The driver must use the object handle to access the key, any subkeys that exist under the key, and any values that exist under the key or its subkeys.

To read the data that is currently assigned to a registry value name, the driver can call one of the following object methods:

WdfRegistryQueryMemory
Retrieves the data that is currently assigned to a value name, stores the data in a framework-allocated buffer, and creates a framework memory object to represent the buffer.

WdfRegistryQueryMultiString
Retrieves the string data that is currently assigned to a multi-string-typed value name, creates a framework string object for each string, and adds each string object to an object collection.

WdfRegistryQueryString
Retrieves the string data that is currently assigned to a string-typed value name and assigns the string to a specified framework string object.

WdfRegistryQueryUnicodeString
Retrieves the string data that is currently assigned to a string-typed value name and copies the string to a specified UNICODE_STRING structure.

WdfRegistryQueryULong
Retrieves the unsigned long word (REG_DWORD) data that is currently assigned to a value name and copies the data to a specified location.

WdfRegistryQueryValue
Retrieves the data that is currently assigned to a value name and copies the data to a driver-supplied buffer.

To write data to a registry value, the driver can call one of the following methods. If the value name already exists, the operating system updates the value's data.

WdfRegistryAssignMemory
Assigns data that is contained in a memory buffer to a specified value name in the registry.

WdfRegistryAssignMultiString
Assigns a set of strings to a specified value name in the registry. The strings are contained in a driver-supplied collection of framework string objects.

WdfRegistryAssignString
Assigns a string to a specified value name in the registry. The string is contained in a framework string object.

WdfRegistryAssignUnicodeString
Assigns a specified Unicode string to a specified value name in the registry.

WdfRegistryAssignULong
Assigns a specified unsigned long word value to a specified value name in the registry.

WdfRegistryAssignValue
Assigns the contents of a driver-supplied data buffer to a specified value name in the registry.

To remove a registry value, the driver must call WdfRegistryRemoveValue. To remove a key, the driver must call WdfRegistryRemoveKey.

To obtain WDM information about the registry, a driver can call WdfRegistryWdmGetHandle, which returns a WDM handle to the registry key that a framework registry-key object represents.

After your driver has finished accessing a registry key, it must call WdfRegistryClose or WdfObjectDelete to close the key and delete the registry-key object.