WdfRegistryOpenKey function (wdfregistry.h)
[Applies to KMDF and UMDF]
The WdfRegistryOpenKey method opens a specified registry key and creates a framework registry-key object that represents the registry key.
Syntax
NTSTATUS WdfRegistryOpenKey(
[in, optional] WDFKEY ParentKey,
[in] PCUNICODE_STRING KeyName,
[in] ACCESS_MASK DesiredAccess,
[in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
[out] WDFKEY *Key
);
Parameters
[in, optional] ParentKey
A handle to a framework registry-key object. This object represents a parent registry key that the driver has opened. This parameter is optional and can be NULL. If the parameter is not NULL, the key that KeyName specifies must reside under this parent key in the registry. For more information about this parent key, see the Remarks section.
[in] KeyName
A pointer to a UNICODE_STRING structure that contains the name of the key to be opened. The key name can include path information. If ParentKey is NULL, KeyName must specify a complete path to a registry key. For examples, see the Remarks section.
[in] DesiredAccess
An ACCESS_MASK-typed value that specifies access rights that the driver is requesting for the specified registry key. For a list of access rights that drivers typically use for registry keys, see Opening a Handle to a Registry-Key Object. Your driver must ask for only the types of access that it needs. For example, the driver must not ask for KEY_ALL_ACCESS if it will only read the registry key.
[in, optional] KeyAttributes
A pointer to a WDF_OBJECT_ATTRIBUTES structure that contains driver-supplied attributes for the new registry-key object. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.
[out] Key
A pointer to a location that receives a handle to the new registry-key object.
Return value
WdfRegistryOpenKey returns STATUS_SUCCESS if the operation succeeds. Otherwise, the method might return one of the following values:
Return code | Description |
---|---|
|
WdfRegistryOpenKey was not called at IRQL = PASSIVE_LEVEL. |
|
An invalid parameter was specified. |
|
A registry-key object could not be allocated. |
|
The system denied the specified access rights. |
|
The specified registry key does not exist. |
For a list of other return values that the WdfRegistryOpenKey method might return, see Framework Object Creation Errors.
This method also might return other NTSTATUS values.
Remarks
To obtain a handle to a registry-key object that represents a parent key, your driver can call WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey, or WdfFdoInitOpenRegistryKey.
The string format specified in the KeyName parameter depends on whether the caller is a KMDF driver or a UMDF driver. For example, to open the following path:
HKLM\System\CurrentControlSet\Control
Your driver might use this conditional logic:
#ifdef _KERNEL_MODE
#define CONTROL_KEY_FULL_PATH L"\\Registry\\Machine\\System\\CurrentControlSet\\Control "
#else
#define CONTROL_KEY_FULL_PATH L"System\\CurrentControlSet\\Control\\"
#endif
When the driver has finished using a registry key that it opens with WdfRegistryOpenKey, the driver must call WdfRegistryClose.
For more information about registry-key objects, see Using the Registry in Framework-Based Drivers.
Examples
The following code example opens a driver's software key, and then it opens the MySubKey registry key, which is located under the driver's software key.
WDFKEY hKey, subkey;
NTSTATUS status;
UNICODE_STRING myKeyStr;
status = WdfDeviceOpenRegistryKey(
device,
PLUGPLAY_REGKEY_DRIVER,
KEY_READ,
WDF_NO_OBJECT_ATTRIBUTES,
&hKey
);
if (NT_SUCCESS(status)){
RtlInitUnicodeString(
&myKeyStr,
L"MySubKey"
);
status = WdfRegistryOpenKey(
hKey,
&myKeyStr,
KEY_READ,
WDF_NO_OBJECT_ATTRIBUTES,
&subkey
);
}
Requirements
Requirement | Value |
---|---|
Target Platform | Universal |
Minimum KMDF version | 1.0 |
Minimum UMDF version | 2.0 |
Header | wdfregistry.h (include Wdf.h) |
Library | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
DDI compliance rules | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |