ObReferenceObjectByHandleWithTag 함수(wdm.h)

아티클
08/08/2023

ObReferenceObjectByHandleWithTag 루틴은 지정된 핸들로 식별되는 개체의 참조 수를 증가시키고 개체 참조 추적을 지원하기 위해 개체에 4바이트 태그 값을 씁니다.

구문

NTSTATUS ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

매개 변수

[in] Handle

개체에 대한 열린 핸들을 지정합니다.

[in] DesiredAccess

호출자가 요청하는 개체에 대한 액세스 유형을 지정합니다. 이 매개 변수는 ACCESS_MASK 형식의 비트 마스크입니다. 이 필드의 해석은 개체 형식에 따라 달라집니다. 일반 액세스 권한을 사용하지 마세요.

[in, optional] ObjectType

개체 형식을 지정하는 불투명 구조체에 대한 포인터입니다. 이 매개 변수는 OBJECT_TYPE 구조를 가리킵니다. ObjectType을 NULL로 설정하거나 Wdm.h 헤더 파일에 선언된 다음 포인터 값 중 하나로 설정합니다. *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType 또는 *TmTransactionObjectType. ObjectType이 NULL이 아닌 경우 루틴은 제공된 개체 형식이 Handle 매개 변수가 지정하는 개체의 개체 형식과 일치하는지 확인합니다.

[in] AccessMode

액세스 검사 사용할 액세스 모드를 지정합니다. UserMode 또는 KernelMode여야 합니다. 드라이버는 항상 사용자 주소 공간에서 수신하는 핸들에 대해 UserMode 를 지정해야 합니다.

[in] Tag

4 바이트 사용자 지정 태그 값을 지정합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[out] Object

루틴이 개체에 대한 포인터를 쓰는 변수에 대한 포인터입니다. 다음 표에서는 가능한 ObjectType 매개 변수 값으로 지정된 Object 포인터 형식을 나열합니다.

ObjectType 매개 변수	개체 포인터 형식
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHORE
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS 또는 PKPROCESS
*PsThreadType	PETHREAD 또는 PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*TmTransactionManagerObjectType	PKTM
*TmTransactionObjectType	PKTRANSACTION

포인터 형식이 참조하는 구조체는 불투명하며 드라이버는 구조체 멤버에 액세스할 수 없습니다. 구조체가 불투명하기 때문에 PEPROCESS는 PKPROCESS와 동일하고 PETHREAD는 PKTHREAD와 동일합니다.

[out, optional] HandleInformation

드라이버는 이 매개 변수를 NULL로 설정합니다.

반환 값

ObReferenceObjectByHandleWithTag 는 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 오류 반환 값에는 다음이 포함됩니다.

반환 코드	설명
STATUS_OBJECT_TYPE_MISMATCH	ObjectType 매개 변수는 Handle 매개 변수로 식별되는 개체의 잘못된 개체 형식을 지정합니다.
STATUS_ACCESS_DENIED	호출자에게 개체에 대한 필수 액세스 권한이 없습니다.
STATUS_INVALID_HANDLE	지정한 핸들이 잘못되었습니다.

설명

이 루틴은 지정된 개체 핸들의 유효성 검사에 액세스합니다. 액세스 권한을 부여할 수 있는 경우 루틴은 개체 참조 수를 증가시키고 호출자에 대한 개체 포인터를 제공합니다. 이 증가는 호출자가 개체를 사용하는 동안 개체가 삭제되지 않도록 합니다. 개체가 더 이상 필요하지 않은 경우 호출자는 ObDereferenceObjectWithTag 또는 ObDereferenceObjectDeferDeleteWithTag 루틴을 호출하여 참조 수를 감소시켜야 합니다.

개체 참조에 대한 자세한 내용은 개체의 수명 주기를 참조하세요.

ObReferenceObjectByHandleWithTag 는 Handle 매개 변수로 지정된 개체 핸들을 닫거나 무효화하지 않습니다. 핸들이 더 이상 필요하지 않은 경우 호출자는 ZwClose 루틴을 호출하여 핸들을 닫을 수 있습니다.

AccessMode 매개 변수 값이 KernelMode이면 요청된 액세스가 항상 허용됩니다. AccessMode가 UserMode인 경우 요청된 액세스는 호출자가 개체에 대한 액세스 권한과 비교됩니다. 최상위 드라이버만 AccessMode 매개 변수의 UserMode 값을 안전하게 지정할 수 있습니다.

Windows 7부터 AccessMode 가 KernelMode 이고 사용자 주소 공간에서 핸들이 수신되는 경우 드라이버 검증 도구 는 버그 검사 C4, F6 하위 코드를 발급합니다.

ObReferenceObjectByHandle 루틴은 호출자가 개체에 사용자 지정 태그를 쓸 수 있도록 설정하지 않는다는 점을 제외하고 ObReferenceObjectByHandleWithTag와 유사합니다. Windows 7 이상 버전의 Windows에서 ObReferenceObjectByHandle 은 항상 개체에 기본 태그 값('tlfD')을 씁니다. ObReferenceObjectByHandle에 대한 호출은 Tag = 'tlfD'를 지정하는 ObReferenceObjectByHandleWithTag 호출과 동일한 효과를 집니다.

Windows 디버깅 도구에서 개체 참조 추적을 보려면 !obtrace 커널 모드 디버거 확장을 사용합니다. 개체 참조 추적을 사용하는 경우 !obtrace 확장이 개체 참조 태그를 표시하도록 향상되었습니다. 기본적으로 개체 참조 추적은 꺼져 있습니다. Gflags( Global Flags Editor )를 사용하여 개체 참조 추적을 사용하도록 설정합니다. 자세한 내용은 태그를 사용하는 개체 참조 추적을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 운영 체제의 Windows 7 이상 버전에서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport)