Makro ObDereferenceObjectWithTag (wdm.h)

Artikel
03/18/2023

ObDereferenceObjectWithTag secara rutin mengurangi jumlah referensi objek yang ditentukan, dan menulis nilai tag empat byte ke objek untuk mendukung pelacakan referensi objek.

Sintaks

void ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

Parameter

[in] a

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

[in] t

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

Nilai kembali

Tidak ada

Keterangan

ObDereferenceObjectWithTag mengembalikan nilai yang dicadangkan untuk penggunaan sistem. Driver harus memperlakukan nilai ini sebagai VOID.

Driver mode kernel memanggil rutinitas ini untuk mengurangi jumlah referensi objek satu per satu. Jika objek dibuat sebagai sementara (yaitu, bendera OBJ_PERMANENT tidak ditentukan saat objek dibuat), dan jumlah referensi mencapai nol, manajer objek akan menghapus objek.

Ketika jumlah referensi untuk objek mencapai nol, komponen mode kernel dapat menghapus objek. Namun, driver hanya dapat menghapus objek yang dibuatnya, dan driver tidak boleh mencoba menghapus objek apa pun yang tidak dibuatnya.

Objek bersifat permanen jika dibuat dengan bendera atribut objek OBJ_PERMANENT yang ditentukan. (Untuk informasi selengkapnya tentang atribut objek, lihat InitializeObjectAttributes.) Objek permanen dibuat dengan jumlah referensi awal satu, sehingga objek tidak dihapus ketika driver menghapus referensi terakhirnya ke objek.

Untuk menyiapkan objek permanen yang akan dihapus, driver dapat memanggil rutinitas ZwMakeTemporaryObject untuk membuat objek bersifat sementara. Driver seharusnya hanya menghapus objek permanen yang dibuatnya. Gunakan langkah-langkah berikut untuk menghapus objek permanen:

Panggil ObDereferenceObjectWithTag.
Dapatkan handel ke objek . Jika perlu, panggil rutinitas ZwOpenXxx atau ZwCreateXxx yang sesuai untuk mendapatkan handel objek.
Panggil ZwMakeTemporaryObject dengan handel yang diperoleh di langkah 2.
Panggil ZwClose dengan handel yang diperoleh di langkah 2.

Jika penghapusan langsung objek oleh utas saat ini dapat menyebabkan kebuntuan, jangan panggil ObDereferenceObjectWithTag untuk mendereferensikan objek. Sebagai gantinya, panggil rutinitas ObDereferenceObjectDeferDeleteWithTag untuk mendereferensikan objek.

Misalnya, kebuntuan seperti itu dapat terjadi jika ObDereferenceObjectWithTag digunakan untuk mendereferensikan objek Kernel Transaction Manager (KTM) ketika driver tingkat yang lebih tinggi pada tumpukan driver memegang kunci.

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

Rutinitas ObDereferenceObject mirip dengan ObDereferenceObjectWithTag, kecuali bahwa itu tidak memungkinkan pemanggil untuk menulis tag kustom ke objek. Di Windows 7 dan versi Windows yang lebih baru, ObDereferenceObject selalu menulis nilai tag default ('tlfD') ke objek. Panggilan ke ObDereferenceObject memiliki efek yang sama dengan panggilan ke ObDereferenceObjectWithTag 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 Editor Bendera Global (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	Desktop
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)