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 SQLESOURCEMANAGER
*TmTransactionManagerObjectType PKTM
*TmTransactionObjectType PKTRANSACTION

指標類型參考的結構不透明，而且驅動程式無法存取結構成員。 因為結構不透明，所以 PEPROCESS 相當於 PKPROCESS，而 PETHREAD 相當於 PKTHREAD。

[out, optional] HandleInformation

驅動程式將此設定為 NULL。

傳回值

如果呼叫成功，ObReferenceObjectByHandle 會傳回STATUS_SUCCESS。 可能的傳回值包括下列錯誤碼：

傳回碼 Description
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 開始提供。
目標平台 Universal
標頭 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫 NtosKrnl.lib
Dll NtosKrnl.exe
IRQL PASSIVE_LEVEL
DDI 合規性規則 HwStorPortProhibitedDIS (storport) 、 IrqlObPassive (wdm) 、 TargetRelationNeedsRef (wdm)

另請參閱

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer