ObReferenceObjectByHandleWithTag 函式 (wdm.h)

發行項
02/27/2024

ObReferenceObjectByHandleWithTag 例程會遞增指定句柄所識別對象的參考計數，並將四位元組標記值寫入物件，以支援對象參考追蹤。

語法

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

指定四位元組的自訂標籤值。如需詳細資訊，請參閱接下來的＜備註＞一節。

[out] Object

變數的指標，例程會將指標寫入物件。下表列出可能 ObjectType 參數值所指定的 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。

傳回值

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

傳回碼	Description
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) 來啟用對象參考追蹤。如需詳細資訊，請參閱對象參考追蹤與標記。

規格需求

需求	值
最低支援的用戶端	適用於 Windows 7 和更新版本的 Windows 作業系統。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h、Fltkernel.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDIS (storport)