ObReferenceObjectByHandleWithTag 函式 (wdm.h)
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) |