WdfRegistryCreateKey 함수(wdfregistry.h)
[KMDF 및 UMDF에 적용]
WdfRegistryCreateKey 메서드는 지정된 레지스트리 키를 만들고 열거나 이미 있는 경우 키를 열고 레지스트리 키를 나타내는 프레임워크 레지스트리 키 개체를 만듭니다.
구문
NTSTATUS WdfRegistryCreateKey(
[in, optional] WDFKEY ParentKey,
[in] PCUNICODE_STRING KeyName,
[in] ACCESS_MASK DesiredAccess,
[in] ULONG CreateOptions,
[out, optional] PULONG CreateDisposition,
[in, optional] PWDF_OBJECT_ATTRIBUTES KeyAttributes,
[out] WDFKEY *Key
);
매개 변수
[in, optional] ParentKey
프레임워크 레지스트리 키 개체에 대한 핸들입니다. 이 개체는 드라이버가 연 부모 레지스트리 키를 나타냅니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 매개 변수가 NULL이 아니면 KeyName 에서 지정하는 키가 레지스트리의 이 부모 키 아래에 있어야 합니다. 이 부모 키에 대한 자세한 내용은 설명 섹션을 참조하세요.
[in] KeyName
열 키의 이름을 포함하는 UNICODE_STRING 구조체에 대한 포인터입니다. 키 이름에는 경로 정보가 포함될 수 있습니다. ParentKey가 NULL인 경우 KeyName은 레지스트리 키에 대한 전체 경로를 지정해야 합니다.
[in] DesiredAccess
드라이버가 지정된 레지스트리 키에 대해 요청하는 액세스 권한을 지정하는 ACCESS_MASK 형식의 값입니다. 드라이버가 일반적으로 레지스트리 키에 사용하는 액세스 권한 목록은 Registry-Key 개체에 대한 핸들 열기를 참조하세요. 드라이버는 필요한 액세스 유형만 요청해야 합니다. 예를 들어 드라이버는 레지스트리 키만 읽을지 KEY_ALL_ACCESS 요청하면 안 됩니다.
[in] CreateOptions
하나 이상의 플래그. 이러한 플래그에 대한 자세한 내용은 CreateOptions 매개 변수 또는 ZwCreateKey를 참조하세요.
[out, optional] CreateDisposition
새 키가 만들어지는 경우 REG_CREATED_NEW_KEY 받는 위치에 대한 포인터이거나 기존 키가 열려 있는 경우 REG_OPENED_EXISTING_KEY. 이러한 값은 Wdm.h에 정의되어 있습니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다.
[in, optional] KeyAttributes
새 레지스트리 키 개체에 대한 드라이버 제공 특성을 포함하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.
[out] Key
새 레지스트리 키 개체에 대한 핸들을 수신하는 위치에 대한 포인터입니다.
반환 값
WdfRegistryCreateKey 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 메서드는 다음 값 중 하나를 반환할 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
WdfRegistryCreateKey 가 IRQL = PASSIVE_LEVEL 호출되지 않았습니다. |
|
잘못된 매개 변수가 지정되었습니다. |
|
레지스트리 키 개체를 할당할 수 없습니다. |
|
시스템에서 지정된 액세스 권한을 거부했습니다. |
|
지정된 레지스트리 키가 없습니다. |
WdfRegistryCreateKey 메서드가 반환할 수 있는 다른 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.
이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.
설명
부모 키를 나타내는 레지스트리 키 개체에 대한 핸들을 가져오기 위해 드라이버는 WdfDriverOpenParametersRegistryKey, WdfDeviceOpenRegistryKey 또는 WdfFdoInitOpenRegistryKey를 호출할 수 있습니다.
기본적으로 새 레지스트리 키 개체의 부모는 WdfDriverCreate 메서드가 만드는 프레임워크 드라이버 개체입니다. WDF_OBJECT_ATTRIBUTES 구조체의 ParentObject 멤버를 사용하여 다른 부모를 지정할 수 있습니다. 프레임워크는 부모 개체를 삭제할 때 레지스트리 키 개체를 삭제합니다. 드라이버가 기본 부모를 변경하지 않는 경우 드라이버는 개체 사용을 마쳤을 때 레지스트리 키 개체를 삭제해야 합니다. 그렇지 않으면 I/O 관리자가 드라이버를 언로드할 때까지 레지스트리 키 개체가 유지됩니다.
드라이버가 기본 부모를 변경하지 않으면 드라이버가 개체 사용을 마쳤을 때 WdfRegistryClose 를 호출해야 합니다. 그렇지 않으면 I/O 관리자가 드라이버를 언로드할 때까지 레지스트리 키 개체가 유지됩니다. 또는 드라이버가 WdfObjectDelete 를 호출하여 레지스트리 키 개체를 삭제할 수 있습니다.
레지스트리 키 개체에 대한 자세한 내용은 Framework-Based 드라이버에서 레지스트리 사용을 참조하세요.
예제
다음 코드 예제에서는 드라이버의 소프트웨어 키를 연 다음 드라이버의 소프트웨어 키 아래에 있는 myKeyStr 레지스트리 키를 만들고 엽니다.
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"myKeyStr"
);
status = WdfRegistryCreateKey(
hKey,
&myKeyStr,
KEY_READ,
REG_OPTION_NON_VOLATILE,
NULL,
WDF_NO_OBJECT_ATTRIBUTES,
&subkey
);
}
요구 사항
| 요구 사항 | 값 |
|---|---|
| 대상 플랫폼 | 유니버설 |
| 최소 KMDF 버전 | 1.0 |
| 최소 UMDF 버전 | 2.0 |
| 머리글 | wdfregistry.h(Wdf.h 포함) |
| 라이브러리 | Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF) |
| IRQL | PASSIVE_LEVEL |
| DDI 규정 준수 규칙 | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |