ObReferenceObjectByHandle 함수(wdm.h)

  • 아티클

ObReferenceObjectByHandle 루틴은 개체 핸들에 대한 액세스 유효성 검사를 제공하며, 액세스 권한을 부여할 수 있는 경우 개체 본문에 해당하는 포인터를 반환합니다.

구문

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

매개 변수

[in] Handle

개체의 열린 핸들을 지정합니다.

[in] DesiredAccess

개체에 대한 요청된 액세스 유형을 지정합니다. 이 필드의 해석은 개체 형식에 따라 달라집니다. 일반 액세스 권한은 사용하지 마세요. 자세한 내용은 ACCESS_MASK 참조하세요.

[in, optional] ObjectType

개체 형식에 대한 포인터입니다. ObjectType 은 *ExEventObjectType일 수 있습니다. *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType 또는 *TmTransactionObjectType.

ObjectType이 NULL이 아닌 경우 운영 체제는 제공된 개체 형식이 Handle이 지정하는 개체의 개체 형식과 일치하는지 확인합니다.

[in] AccessMode

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

[out] 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로 설정합니다.

반환 값

ObReferenceObjectByHandle 은 호출이 성공하면 STATUS_SUCCESS 반환합니다. 가능한 반환 값에는 다음과 같은 오류 코드가 포함됩니다.

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

설명

개체 본문에 대한 포인터는 개체 테이블 항목에서 검색되고 Object 매개 변수를 통해 호출자에게 반환됩니다.

AccessMode가 UserMode인 경우 요청된 액세스는 개체에 대해 부여된 액세스 권한과 비교됩니다. AccessMode가 KernelMode인 경우 핸들은 커널 주소 공간에서 발생해야 합니다.

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

호출이 성공하면 개체 본문에 대한 포인터가 호출자에게 반환되고 포인터 참조 수가 증가합니다. 이 개수를 증가하면 포인터가 참조되는 동안 개체가 삭제되지 않습니다. 호출자는 개체를 사용하여 수행되는 즉시 ObDereferenceObject 를 사용하여 참조 수를 감소시켜야 합니다.

요구 사항

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

추가 정보

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer