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) |