ObReferenceObjectByPointerWithTag 函式 (wdm.h)

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

語法

NTSTATUS ObReferenceObjectByPointerWithTag(
  [in]           PVOID           Object,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [in]           ULONG           Tag
);

參數

[in] Object

物件的指標。 呼叫端會在建立 物件時，或從先前呼叫 ObReferenceObjectByHandleWithTag 例程開啟對象之後取得這個指標。

[in] DesiredAccess

指定呼叫端要求之物件的存取類型。 此參數是類型 ACCESS_MASK的位掩碼。 此欄位的解譯取決於物件類型。 請勿使用任何一般訪問許可權。

[in, optional] ObjectType

指定物件類型的不透明結構的指標。 此參數指向 OBJECT_TYPE 結構。 將 ObjectType 設定為 NULL 或下列其中一個指標值，這些值會在 Wdm.h 頭檔中宣告：*ExEventObjectType、 *ExSemaphoreObjectType、*IoFileObjectType、*PsProcessType、*PsThreadType、*SeTokenObjectType、*TmEnlistmentObjectType、*TmResourceManagerObjectType、*TmTransactionManagerObjectType 或 *TmTransactionObjectType。 如果 AccessMode 是 KernelMode，此參數可以是 NULL。 如果 ObjectType 不是 NULL，則例程會驗證提供的物件類型是否符合 Handle 參數所指定物件的物件類型。

[in] AccessMode

指出用於存取檢查的存取模式。 將此參數設定為下列其中一個 MODE 列舉值：

• UserMode

• KernelMode

較低層級的驅動程序應該指定 KernelMode。

[in] Tag

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

傳回值

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

備註

這個例程會存取指定對象的驗證。 如果可以授與存取權，例程會遞增對象參考計數。 這個遞增可防止對象在呼叫端使用 物件時遭到刪除。 不再需要物件時，呼叫端應該藉由呼叫 ObDereferenceObjectWithTag 或 ObDereferenceObjectDeferDeleteWithTag 例程來遞減參考計數。

如需對象參考的詳細資訊，請參閱 物件的生命週期。

ObReferenceObjectByPointer 例程類似於 ObReferenceObjectByPointerWithTag，不同之處在於它不會讓呼叫端將自定義卷標寫入物件。 在 Windows 7 和更新版本的 Windows 中， ObReferenceObjectByPointer 一律會將預設卷標值寫入物件 ('tlfD') 。 對 ObReferenceObjectByPointer 的呼叫與呼叫 ObReferenceObjectByPointerWithTag 的效果相同，指定 Tag = 'tlfD'。

若要在 Windows 偵錯工具中檢視對象參考追蹤，請使用 ！obtrace 核心模式調試程式延伸模組。 在 Windows 7 中，如果已啟用對象參考追蹤， 則會增強 ！obtrace 延伸模組以顯示物件參考標記。 根據預設，對象參考追蹤會關閉。 使用 全域旗標編輯器 (Gflags) 來啟用對象參考追蹤。 如需詳細資訊，請參閱 使用標記進行對象參考追蹤。

規格需求

另請參閱

ACCESS_MASK

Object_Type

ObDereferenceObjectDeferDeleteWithTag

ObDereferenceObjectWithTag

ObReferenceObjectByPointer

ZwClose