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 메서드가 반환할 수 있는 다른 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.

이 메서드는 다른 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
                                  );
}

요구 사항

추가 정보

ACCESS_MASK

RtlInitUnicodeString

UNICODE_STRING

WDF_OBJECT_ATTRIBUTES

WdfDeviceOpenRegistryKey

WdfDriverCreate

WdfDriverOpenParametersRegistryKey

WdfFdoInitOpenRegistryKey

WdfRegistryOpenKey

ZwCreateKey