Fungsi ObReferenceObjectByHandleWithTag (wdm.h)

Artikel
02/27/2024

Rutinitas ObReferenceObjectByHandleWithTag meningkatkan jumlah referensi objek yang diidentifikasi oleh handel yang ditentukan, dan menulis nilai tag empat byte ke objek untuk mendukung pelacakan referensi objek.

Sintaks

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
);

Parameter

[in] Handle

Menentukan handel terbuka untuk 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. Jika ObjectType bukan NULL, rutin memverifikasi bahwa jenis objek yang disediakan cocok dengan jenis objek objek yang ditentukan parameter Handle .

[in] AccessMode

Menentukan mode akses yang akan digunakan untuk pemeriksaan akses. Ini harus Berupa UserMode atau KernelMode. Driver harus selalu menentukan UserMode untuk handel yang mereka terima dari ruang alamat pengguna.

[in] Tag

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

[out] Object

Penunjuk ke variabel di mana rutinitas menulis pointer ke objek . Tabel berikut ini mencantumkan jenis penunjuk Objek yang ditunjuk oleh nilai parameter ObjectType yang mungkin.

Parameter ObjectType	Jenis penunjuk objek
*ExEventObjectType	PKEVENT
*ExSemaphoreObjectType	PKSEMAPHORE
*IoFileObjectType	PFILE_OBJECT
*PsProcessType	PEPROCESS atau PKPROCESS
*PsThreadType	PETHREAD atau PKTHREAD
*SeTokenObjectType	PACCESS_TOKEN
*TmEnlistmentObjectType	PKENLISTMENT
*TmResourceManagerObjectType	PKRESOURCEMANAGER
*TmTransactionManagerObjectType	PKTM
*TmTransactionObjectType	TRANSAKSI PK

Struktur referensi jenis pointer buram, dan driver tidak dapat mengakses anggota struktur. Karena strukturnya buram, PEPROCESS setara dengan PKPROCESS, dan PETHREAD setara dengan PKTHREAD.

[out, optional] HandleInformation

Driver mengatur parameter ini ke NULL.

Nilai kembali

ObReferenceObjectByHandleWithTag 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 diidentifikasi oleh parameter Handle .
STATUS_ACCESS_DENIED	Pemanggil tidak memiliki hak akses yang diperlukan ke objek.
STATUS_INVALID_HANDLE	Handel yang ditentukan tidak valid.

Keterangan

Rutinitas ini melakukan validasi akses dari handel objek yang ditentukan. Jika akses dapat diberikan, rutinitas akan menaikkan jumlah referensi objek dan menyediakan penunjuk objek ke pemanggil. 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.

ObReferenceObjectByHandleWithTag tidak menutup atau membatalkan handel objek yang ditentukan oleh parameter Handle . Ketika handel tidak lagi diperlukan, penelepon dapat menutup handel dengan memanggil rutinitas ZwClose .

Jika nilai parameter AccessMode adalah KernelMode, akses yang diminta selalu diizinkan. Jika AccessMode adalah UserMode, akses yang diminta dibandingkan dengan hak akses yang dimiliki pemanggil ke objek . Hanya driver tingkat tertinggi yang dapat dengan aman menentukan nilai UserMode untuk parameter AccessMode .

Dimulai dengan Windows 7, jika AccessMode adalah KernelMode dan handel diterima dari ruang alamat pengguna, Driver Verifier mengeluarkan bugcheck C4, subkode F6.

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

Untuk melihat jejak referensi objek di alat penelusuran kesalahan Windows, gunakan ekstensi debugger !obtrace kernel-mode. 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	PASSIVE_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport)