Fungsi ObReferenceObjectByHandle (wdm.h)
Rutinitas ObReferenceObjectByHandle menyediakan validasi akses pada handel objek, dan, jika akses dapat diberikan, mengembalikan penunjuk yang sesuai ke isi objek.
Sintaks
NTSTATUS ObReferenceObjectByHandle(
[in] HANDLE Handle,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_TYPE ObjectType,
[in] KPROCESSOR_MODE AccessMode,
[out] PVOID *Object,
[out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);
Parameter
[in] Handle
Menentukan handel terbuka untuk objek.
[in] DesiredAccess
Menentukan jenis akses yang diminta ke objek. Interpretasi bidang ini tergantung pada jenis objek. Jangan gunakan hak akses generik apa pun. Untuk informasi selengkapnya, lihat ACCESS_MASK.
[in, optional] ObjectType
Penunjuk ke jenis objek. ObjectType dapat berupa *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType, atau *TmTransactionObjectType.
Jika ObjectType bukan NULL, sistem operasi memverifikasi bahwa jenis objek yang disediakan cocok dengan jenis objek objek yang ditentukan Handel .
[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.
[out] Object
Arahkan ke variabel yang menerima penunjuk ke isi objek. Tabel berikut ini berisi jenis penunjuk.
| 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 ini ke NULL.
Nilai kembali
ObReferenceObjectByHandle mengembalikan STATUS_SUCCESS jika panggilan berhasil. Nilai yang mungkin dikembalikan termasuk kode kesalahan berikut:
| Menampilkan kode | Deskripsi |
|---|---|
| STATUS_OBJECT_TYPE_MISMATCH | Parameter ObjectType menentukan jenis objek yang salah untuk objek yang diidentifikasi oleh parameter Handel . |
| STATUS_ACCESS_DENIED | Pemanggil tidak dapat diberikan hak akses yang diminta ke objek. |
| STATUS_INVALID_HANDLE | Parameter Handle bukan handel objek yang valid. |
Keterangan
Penunjuk ke isi objek diambil dari entri tabel objek dan dikembalikan ke pemanggil dengan menggunakan parameter Objek .
Jika AccessMode adalah UserMode, akses yang diminta dibandingkan dengan akses yang diberikan untuk objek. Jika AccessMode adalah KernelMode, handel harus berasal dari ruang alamat kernel.
Dimulai dengan Windows 7, jika AccessMode adalah KernelMode dan handel diterima dari ruang alamat pengguna, Driver Verifier mengeluarkan bugcheck C4, subkode F6.
Jika panggilan berhasil, penunjuk ke isi objek dikembalikan ke pemanggil dan jumlah referensi penunjuk bertambah. Meningkatkan jumlah ini mencegah objek dihapus saat penunjuk sedang direferensikan. Pemanggil harus mengurangi jumlah referensi dengan ObDereferenceObject segera setelah dilakukan dengan objek .
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Tersedia dimulai dengan Windows 2000. |
| Target Platform | Universal |
| Header | wdm.h (termasuk Wdm.h, Ntddk.h, Ntifs.h) |
| Pustaka | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| Aturan kepatuhan DDI | HwStorPortProhibitedDDIs(storport), IrqlObPassive(wdm), TargetRelationNeedsRef(wdm) |