CmCallbackGetKeyObjectIDEx 함수(wdm.h)

아티클
03/08/2023

CmCallbackGetKeyObjectIDEx 루틴은 지정된 레지스트리 키 개체와 연결된 고유 식별자 및 개체 이름을 검색합니다.

이 루틴은 Windows 8 시작해서 사용할 수 있습니다. 이전 버전의 Windows에서는 CmCallbackGetKeyObjectID 루틴을 대신 사용합니다. 자세한 내용은 아래 의 설명 섹션을 참조하세요.

구문

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

매개 변수

[in] Cookie

레지스트리 필터 콜백을 수신하기 위한 호출자의 등록을 나타내는 쿠키 값입니다. 드라이버는 이전에 CmRegisterCallback 또는 CmRegisterCallbackEx 루틴 에서 이 쿠키 값을 가져왔습니다.

[in] Object

레지스트리 키 개체에 대한 포인터입니다. 이 매개 변수는 드라이버의 RegistryCallback 콜백 루틴이 REG_XXX_KEY_INFORMATION 구조체 중 하나의 Object 멤버에서 받은 포인터 값입니다.

경고

특정 상황에서 레지스트리 콜백 알림 구조에는 잘못된 NULL이 아닌 개체 포인터가 포함될 수 있습니다. 레지스트리 필터링 드라이버는 이러한 포인터를 이 루틴에 전달해서는 안 됩니다. 자세한 내용은 레지스트리 알림의 잘못된 키 개체 포인터를 참조하세요.

[out, optional] ObjectID

Object가 나타내는 레지스트리 키의 키 식별자에 대한 포인터를 받는 위치에 대한 포인터입니다. 이 식별자는 레지스트리의 모든 키에서 고유합니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 자세한 내용은 아래의 설명 섹션 을 참조하세요.

[out, optional] ObjectName

UNICODE_STRING 구조체에 대한 포인터를 수신하는 위치에 대한 포인터입니다. 이 구조체에는 Object 에서 지정하는 레지스트리 키 개체의 개체 이름이 포함됩니다. 개체 이름은 실제로 개체가 나타내는 레지스트리 키의 전체 경로 이름입니다. 호출자는 CmCallbackReleaseKeyObjectIDEx 루틴을 호출하여 이 구조를 해제합니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 자세한 내용은 설명 부분을 참조하세요.

[in] Flags

예약되어 있습니다. 0으로 설정됩니다.

반환 값

CmCallbackGetKeyObjectIDEx는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음 상태 코드가 포함됩니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	Cookie, Object 또는 Flags 매개 변수가 잘못되었습니다.

설명

드라이버는 ObjectID 또는 ObjectName 매개 변수에 NULL이 아닌 값을 제공하여 CmCallbackGetKeyObjectIDEx를 사용하여 레지스트리 키 식별자, 개체 이름 또는 둘 다를 가져올 수 있습니다.

호출자는 ObjectID 매개 변수를 통해 키 식별자를 가져올 수 있습니다. 두 레지스트리 키 개체가 동일한 레지스트리 키를 나타내는 경우 두 개체에 대한 CmCallbackGetKeyObjectIDEx 에서 가져온 키 식별자는 동일합니다. 레지스트리 키의 이름이 변경되면 CmCallbackGetKeyObjectIDEx 에서 가져온 키 식별자가 변경되지 않습니다. 호출자는 키 식별자를 사용하여 여러 키 개체를 통해 특정 레지스트리 키에 대한 액세스를 안정적으로 추적할 수 있으며 레지스트리 키 이름 변경 내용에서도 추적할 수 있습니다.

호출자는 ObjectName 매개 변수를 통해 개체 이름을 가져올 수 있습니다. 호출자가 CmCallbackReleaseKeyObjectIDEx를 호출하여 구조를 해제할 때까지 개체 이름을 포함하는 UNICODE_STRING 구조체에 대한 스토리지는 유효한 상태로 유지됩니다.

CmCallbackGetKeyObjectIDEx 는 Windows Vista부터 사용할 수 있는 CmCallbackGetKeyObjectID 루틴의 향상된 버전입니다. Windows 8 이전 버전의 Windows에서 실행되는 드라이버는 CmCallbackGetKeyObjectIDEx 대신 CmCallbackGetKeyObjectID를 호출해야 합니다. Windows 8 이상 버전의 Windows에서만 실행되는 드라이버는 CmCallbackGetKeyObjectID 대신 CmCallbackGetKeyObjectIDEx를 호출해야 합니다.

CmCallbackGetKeyObjectIDEx 에는 CmCallbackGetKeyObjectID에서 사용할 수 없는 두 가지 중요한 기능이 있습니다.

먼저 CmCallbackGetKeyObjectIDEx 를 사용하면 레지스트리 필터 드라이버가 ObjectName 구조의 수명을 명시적으로 제어할 수 있습니다. 드라이버는 언제든지 CmCallbackReleaseKeyObjectIDEx 를 호출하여 이 구조를 해제할 수 있습니다. 반면, 드라이버는 CmCallbackGetKeyObjectID에서 받은 ObjectName 구조를 명시적으로 해제할 수 없습니다. 키에 대한 모든 핸들이 닫히면 이 구조체가 자동으로 해제됩니다.

둘째, 레지스트리 필터 드라이버가 CmCallbackGetKeyObjectID 를 호출하여 ObjectName 구조 포인터를 가져온 다음, 이 호출 후에 레지스트리 키의 이름이 변경되면 CmCallbackGetKeyObjectID에 대한 후속 호출은 이전 키 이름이 포함된 ObjectName 구조체의 부실 복사본에 대한 포인터를 가져옵니다. 이 구조체의 부실 복사본은 키에 대한 모든 핸들이 닫을 때까지 유지됩니다. 반면 CmCallbackGetKeyObjectIDEx에서 가져온 ObjectName 구조체에는 항상 최신 키 이름이 포함됩니다.

레지스트리 필터 드라이버에 대한 자세한 내용은 레지스트리 호출 필터링을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 8 시작해서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL