Fungsi ZwCreateEvent (ntifs.h)

Artikel
07/11/2023

Rutinitas ZwCreateEvent membuat objek peristiwa, mengatur status awal peristiwa ke nilai yang ditentukan, dan membuka handel ke objek dengan akses yang diinginkan yang ditentukan.

Sintaks

NTSYSAPI NTSTATUS ZwCreateEvent(
  [out]          PHANDLE            EventHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in]           EVENT_TYPE         EventType,
  [in]           BOOLEAN            InitialState
);

Parameter

[out] EventHandle

Penunjuk ke variabel yang akan menerima handel objek peristiwa. Handel mencakup informasi pembukuan, seperti jumlah referensi dan konteks keamanan.

[in] DesiredAccess

Nilai ACCESS_MASK yang mewakili jenis akses yang diinginkan untuk objek peristiwa. Tabel berikut ini berisi nilai ACCESS_MASK khusus peristiwa.

Nilai	Akses yang diinginkan
EVENT_QUERY_STATE	Mengkueri status objek peristiwa.
EVENT_MODIFY_STATE	Ubah status objek peristiwa.
EVENT_ALL_ACCESS	Semua kemungkinan hak akses ke objek peristiwa.

[in, optional] ObjectAttributes

Penunjuk ke struktur atribut objek yang disediakan oleh pemanggil yang akan digunakan untuk objek yang ditentukan. Atribut ini akan mencakup ObjectName dan SECURITY_DESCRIPTOR, misalnya. Parameter ini diinisialisasi dengan memanggil makro InitializeObjectAttributes .

[in] EventType

Jenis peristiwa, yang dapat berupa SynchronizationEvent atau NotificationEvent. Nilai-nilai ini termasuk dalam enumerasi EVENT_TYPE , yang didefinisikan dalam file header ntdef.h .

[in] InitialState

Status awal objek peristiwa. Atur ke TRUE untuk menginisialisasi objek peristiwa ke status Sinyal. Atur ke FALSE untuk menginisialisasi objek peristiwa ke status tidak Diberi Sinyal.

Mengembalikan nilai

ZwCreateEvent mengembalikan STATUS_SUCCESS atau status kesalahan yang sesuai. Kemungkinan kode status kesalahan meliputi yang berikut ini:

Menampilkan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	Sumber daya yang diperlukan oleh fungsi ini tidak dapat dialokasikan.
STATUS_INVALID_PARAMETER	Struktur ObjectAttributes yang disediakan berisi nilai parameter yang tidak valid.
STATUS_INVALID_PARAMETER_4	Parameter EventType yang ditentukan tidak valid.
STATUS_OBJECT_NAME_INVALID	Parameter ObjectAttributes berisi ObjectName dalam struktur OBJECT_ATTRIBUTES yang tidak valid.
STATUS_OBJECT_PATH_SYNTAX_BAD	Parameter ObjectAttributes tidak berisi anggota RootDirectory , tetapi anggota ObjectName dalam struktur OBJECT_ATTRIBUTES adalah string kosong atau tidak berisi karakter OBJECT_NAME_PATH_SEPARATOR. Ini menunjukkan sintaks yang salah untuk jalur objek.
STATUS_PRIVILEGE_NOT_HELD	Pemanggil tidak memiliki hak istimewa yang diperlukan untuk membuat handel dengan akses yang ditentukan dalam parameter DesiredAccess .

Keterangan

ZwCreateEvent membuat objek peristiwa, mengatur status awalnya ke nilai yang ditentukan, dan membuka handel ke objek dengan akses yang diinginkan yang ditentukan.

Peristiwa digunakan untuk mengoordinasikan eksekusi. Peristiwa dapat digunakan oleh driver sistem file untuk memungkinkan pemanggil menunggu penyelesaian operasi yang diminta hingga peristiwa yang diberikan diatur ke status Sinyal.

ZwCreateEvent dapat membuat pemberitahuan atau peristiwa sinkronisasi:

Peristiwa pemberitahuan dapat digunakan untuk memberi tahu satu atau beberapa utas eksekusi bahwa suatu peristiwa telah terjadi.
Peristiwa sinkronisasi dapat digunakan dalam serialisasi akses ke perangkat keras antara dua driver yang tidak terkait.

Peristiwa sinkronisasi direset secara otomatis. Ketika peristiwa sinkronisasi diatur ke status Sinyal, satu utas eksekusi yang menunggu peristiwa disinyalkan dirilis, dan peristiwa secara otomatis diatur ulang ke status Not-Signaled.

Tidak seperti peristiwa sinkronisasi, peristiwa pemberitahuan tidak direset secara otomatis. Setelah peristiwa pemberitahuan dalam status Diberi sinyal, peristiwa tersebut tetap dalam status tersebut hingga direset secara eksplisit.

Untuk menyinkronkan pada peristiwa pemberitahuan:

Buat peristiwa pemberitahuan dengan ZwCreateEvent dengan parameter EventType diatur ke NotificationEvent.
Tunggu hingga peristiwa disinyalkan dengan memanggil ZwWaitForSingleObject dengan EventHandle yang dikembalikan oleh ZwCreateEvent. Lebih dari satu utas eksekusi dapat menunggu peristiwa pemberitahuan tertentu disinyalkan. Untuk melakukan polling alih-alih stall, tentukan Batas Waktu nol ke ZwWaitForSingleObject.
Tutup handel ke peristiwa pemberitahuan dengan ZwClose saat akses ke peristiwa tidak lagi diperlukan.

Fungsi ZwCreateEvent dipanggil setelah makro InitializeObjectAttributes digunakan untuk mengatur atribut dalam struktur OBJECT_ATTRIBUTES untuk objek.

Ada dua cara alternatif untuk menentukan nama objek yang diteruskan ke ZwCreateEvent:

Sebagai nama jalur yang sepenuhnya memenuhi syarat, disediakan di anggota ObjectName dari objectAttributes input.
Sebagai nama jalur relatif terhadap direktori yang diwakili oleh handel di anggota RootDirectory dari input ObjectAttributes.

Untuk merilis acara, driver memanggil ZwClose dengan handel peristiwa.

Untuk informasi selengkapnya tentang peristiwa, lihat Objek Peristiwa.

Catatan

Jika panggilan ke rutinitas ZwCreateEvent terjadi dalam mode pengguna, Anda harus menggunakan nama "NtCreateEvent" alih-alih "ZwCreateEvent".

Untuk panggilan dari driver mode kernel, versi NtXxx dan ZwXxx dari rutinitas Windows Native System Services dapat berperilaku berbeda dalam cara mereka menangani dan menafsirkan parameter input. Untuk informasi selengkapnya tentang hubungan antara versi NtXxx dan ZwXxx dari rutinitas, lihat Menggunakan Versi Nt dan Zw dari Rutinitas Layanan Sistem Asli.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP.
Target Platform	Universal
Header	ntifs.h (termasuk Ntifs.h)
Pustaka	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)