Fungsi ObReferenceObjectByPointerWithTag (wdm.h)

Artikel
03/18/2023

Rutinitas ObReferenceObjectByPointerWithTag meningkatkan jumlah referensi objek yang ditentukan, dan menulis nilai tag empat byte ke objek untuk mendukung pelacakan referensi objek.

Sintaks

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

Parameter

[in] Object

Penunjuk ke objek . Penelepon mendapatkan pointer ini baik ketika membuat objek, atau dari panggilan sebelumnya ke rutinitas ObReferenceObjectByHandleWithTag setelah membuka objek.

[in] DesiredAccess

Menentukan jenis akses ke objek yang diminta pemanggil. Parameter ini adalah bitmask jenis ACCESS_MASK. Interpretasi bidang ini tergantung pada jenis objek. Jangan gunakan hak akses generik apa pun.

[in, optional] ObjectType

Penunjuk ke struktur buram yang menentukan jenis objek. Parameter ini menunjuk ke struktur OBJECT_TYPE . Atur ObjectType ke NULL atau ke salah satu nilai pointer berikut, yang dinyatakan dalam file header Wdm.h: *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType, atau *TmTransactionObjectType. Parameter ini bisa NULL jika AccessMode adalah KernelMode. Jika ObjectType bukan NULL, rutin memverifikasi bahwa jenis objek yang disediakan cocok dengan jenis objek objek yang ditentukan parameter Handle .

[in] AccessMode

Menunjukkan mode akses yang akan digunakan untuk pemeriksaan akses. Atur parameter ini ke salah satu nilai enumerasi MODE berikut:

UserMode
KernelMode

Driver tingkat bawah harus menentukan KernelMode.

[in] Tag

Menentukan nilai tag kustom empat byte. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

ObReferenceObjectByPointerWithTag mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan meliputi yang berikut ini:

Menampilkan kode	Deskripsi
STATUS_OBJECT_TYPE_MISMATCH	Parameter ObjectType menentukan jenis objek yang salah untuk objek yang dituju parameter Objek , atau ObjectType adalah NULL tetapi AccessMode adalah UserMode.

Keterangan

Rutinitas ini melakukan validasi akses objek yang ditentukan. Jika akses dapat diberikan, rutinitas akan menaikkan jumlah referensi objek. Kenaikan ini mencegah objek dihapus saat pemanggil menggunakan objek . Ketika objek tidak lagi diperlukan, pemanggil harus mengurangi jumlah referensi dengan memanggil rutinitas ObDereferenceObjectWithTag atau ObDereferenceObjectDeferDeleteWithTag .

Untuk informasi selengkapnya tentang referensi objek, lihat Siklus Hidup Objek.

Rutinitas ObReferenceObjectByPointer mirip dengan ObReferenceObjectByPointerWithTag, kecuali bahwa itu tidak memungkinkan penelepon untuk menulis tag kustom ke objek. Di Windows 7 dan versi Windows yang lebih baru, ObReferenceObjectByPointer selalu menulis nilai tag default ('tlfD') ke objek. Panggilan ke ObReferenceObjectByPointer memiliki efek yang sama dengan panggilan ke ObReferenceObjectByPointerWithTag yang menentukan Tag = 'tlfD'.

Untuk melihat jejak referensi objek di alat penelusuran kesalahan Windows, gunakan ekstensi debugger !obtrace kernel-mode. Di Windows 7, ekstensi !obtrace ditingkatkan untuk menampilkan tag referensi objek, jika pelacakan referensi objek diaktifkan. Secara default, pelacakan referensi objek dinonaktifkan. Gunakan Global Flags Editor (Gflags) untuk mengaktifkan pelacakan referensi objek. Untuk informasi selengkapnya, lihat Pelacakan Referensi Objek dengan Tag.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows 7 dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Universal
Header	wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport)