Fungsi ObCloseHandle (wdm.h)

Artikel
03/08/2023

Rutinitas ObCloseHandle menutup handel objek.

Sintaks

NTSTATUS ObCloseHandle(
  [in] HANDLE          Handle,
  [in] KPROCESSOR_MODE PreviousMode
);

Parameter

[in] Handle

Handel ke objek yang disediakan sistem dari semua jenis.

[in] PreviousMode

Menentukan mode prosesor sebelumnya dari utas yang membuka handel. Untuk menutup handel kernel, atur parameter ini ke KernelMode. Untuk menutup handel pengguna, atur parameter ini ke UserMode. Untuk informasi selengkapnya tentang kedua jenis handel ini, lihat Keterangan.

Nilai kembali

ObCloseHandle mengembalikan STATUS_SUCCESS jika panggilan berhasil. Kemungkinan nilai pengembalian kesalahan mencakup kode NTSTATUS berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_HANDLE	Handel bukan handel yang valid.
STATUS_HANDLE_NOT_CLOSABLE	Utas panggilan tidak memiliki izin untuk menutup handel.

Keterangan

Driver mode kernel memanggil ObCloseHandle untuk menutup handel ke semua jenis objek yang dibuat oleh kernel Windows. Driver harus menutup setiap handel yang terbuka segera setelah handel tidak lagi diperlukan.

Setelah ObCloseHandle menutup handel objek, pemanggil harus memperlakukan handel sebagai tidak valid dan menghindari penggunaan handel untuk mengakses objek. Namun, handel lain mungkin tetap terbuka pada objek yang sama. Selama panggilan ObCloseHandle , sistem mengurangi jumlah handel untuk objek dan memeriksa apakah objek dapat dihapus. Sistem tidak menghapus objek sampai semua handel objek ditutup dan semua penunjuk yang dihitung referensi ke objek dilepaskan.

Parameter PreviousMode menentukan apakah handel yang akan ditutup adalah handel kernel atau handel pengguna. Untuk menutup handel kernel, atur PreviousMode ke KernelMode. Untuk menutup handel pengguna, atur PreviousMode ke UserMode.

Handel kernel adalah handel yang dibuka oleh utas sistem, atau oleh driver mode kernel yang menetapkan atribut OBJ_KERNEL_HANDLE ke handel. (Misalnya, lihat deskripsi OBJ_KERNEL_HANDLE di ZwCreateFile.) Jika driver mode kernel membuka handel untuk penggunaan privatnya, dan driver ini berjalan dalam konteks utas mode pengguna, driver harus membuka handel dengan atribut OBJ_KERNEL_HANDLE. Atribut ini memastikan bahwa handel tidak dapat diakses oleh aplikasi mode pengguna.

Handel pengguna adalah handel yang dibuka oleh aplikasi mode pengguna, atau oleh driver mode kernel yang berjalan dalam konteks utas mode pengguna tetapi tidak membuka handel dengan atribut OBJ_KERNEL_HANDLE. Jika driver membuat handel pengguna untuk digunakan oleh aplikasi mode pengguna, tetapi terjadi kesalahan yang mengharuskan driver untuk menutup handel atas nama aplikasi, driver dapat memanggil ObCloseHandle untuk menutup handel.

Rutinitas ZwClose mirip dengan ObCloseHandle tetapi hanya dapat menutup handel kernel. Panggilan ZwClose(hObject), yang menutup kernel handle hObject, memiliki efek yang sama dengan panggilan ObCloseHandle(hObject, KernelMode). Untuk informasi selengkapnya tentang menutup handel kernel, lihat ZwClose.

Untuk menentukan apakah handel adalah handel kernel atau handel pengguna, driver yang menerima handel dapat memanggil rutinitas ExGetPreviousMode . Atau, driver dapat membaca bidang RequestorMode dari struktur IRP yang menjelaskan permintaan I/O. Manajer I/O mengatur bidang RequestorMode ke mode prosesor sebelumnya dari utas yang meminta operasi I/O.

Penelepon ObCloseHandle tidak boleh berasumsi bahwa rutinitas ini secara otomatis menunggu semua operasi I/O yang tertunda selesai sebelum kembali.

Untuk informasi selengkapnya, lihat Penanganan Objek.

ObCloseHandle tidak dideklarasikan dalam file header sebelum Windows 7. Untuk menggunakan rutinitas ini di driver Anda, sertakan deklarasi fungsi berikut dalam kode driver Anda:

#if (NTDDI_VERSION < NTDDI_WIN7)
NTKERNELAPI
NTSTATUS
  ObCloseHandle(
    __in HANDLE Handle,
    __in KPROCESSOR_MODE PreviousMode
    );
#endif

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Header	wdm.h
Pustaka	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL

Lihat juga