共用方式為


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

指定要用於存取檢查的存取模式。 它必須是 UserModeKernelMode。 驅動程序應該一律指定 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 參數傳回給呼叫端。

如果 AccessModeUserMode,則要求的存取權會與物件的授與存取權進行比較。 如果 AccessModeKernelMode,句柄應該源自核心地址空間。

從 Windows 7 開始,如果 AccessModeKernelMode ,而且從使用者位址空間收到句柄, 驅動程式驗證程式 會發出錯誤檢查 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