Fungsi CreateEventExA (synchapi.h)

Membuat atau membuka objek peristiwa bernama atau tidak bernama dan mengembalikan handel ke objek.

Sintaksis

HANDLE CreateEventExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Parameter

[in, optional] lpEventAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES. Jika lpEventAttributesNULL, penanganan aktivitas tidak dapat diwariskan oleh proses anak.

lpSecurityDescriptor anggota struktur menentukan pendeskripsi keamanan untuk peristiwa baru. Jika lpEventAttributesNULL, peristiwa tersebut akan mendapatkan pendeskripsi keamanan default. ACL dalam deskriptor keamanan default untuk peristiwa berasal dari token utama atau peniruan identitas pembuat.

[in, optional] lpName

Nama objek peristiwa. Nama ini terbatas pada karakter MAX_PATH. Perbandingan nama peka huruf besar/kecil.

Jika lpNamenull, objek peristiwa dibuat tanpa nama.

Jika lpName cocok dengan nama jenis objek lain di namespace yang sama (seperti semaphore, mutex, timer, pekerjaan, atau objek pemetaan file yang ada), fungsi gagal dan fungsi GetLastError mengembalikan ERROR_INVALID_HANDLE. Ini terjadi karena objek ini memiliki namespace yang sama.

Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuat objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Untuk informasi selengkapnya, lihat Namespace Objek Kernel. Peralihan pengguna cepat diimplementasikan menggunakan sesi Layanan Terminal. Nama objek kernel harus mengikuti panduan yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

Objek dapat dibuat di namespace privat. Untuk informasi selengkapnya, lihat Object Namespaces.

[in] dwFlags

Parameter ini bisa 0 atau salah satu nilai berikut.

Nilai	Arti
CREATE_EVENT_INITIAL_SET 0x00000002	Status awal objek peristiwa disinyalir; jika tidak, itu tidak ditandatangani.
CREATE_EVENT_MANUAL_RESET 0x00000001	Peristiwa harus diatur ulang secara manual menggunakan fungsi ResetEvent. Sejumlah utas tunggu, atau utas yang kemudian memulai operasi tunggu untuk objek peristiwa yang ditentukan, dapat dirilis saat status objek diberi sinyal. Jika bendera ini tidak ditentukan, sistem secara otomatis mengatur ulang peristiwa setelah merilis satu utas tunggu.

[in] dwDesiredAccess

Masker akses untuk objek peristiwa. Untuk daftar hak akses, lihat Synchronization Object Security and Access Rights.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah handel ke objek peristiwa. Jika objek peristiwa bernama ada sebelum panggilan fungsi, fungsi mengembalikan handel ke objek yang ada dan GetLastError mengembalikan ERROR_ALREADY_EXISTS.

Jika fungsi gagal, nilai yang dikembalikan adalah NULL. Untuk mendapatkan informasi kesalahan yang diperluas, panggil GetLastError.

Komentar

Setiap utas proses panggilan dapat menentukan handel objek peristiwa dalam panggilan ke salah satu fungsi tunggu . Fungsi tunggu objek tunggal kembali ketika status objek yang ditentukan disinyalir. Fungsi tunggu beberapa objek dapat diinstruksikan untuk mengembalikan baik ketika salah satu atau ketika semua objek yang ditentukan diberi sinyal. Saat fungsi tunggu kembali, utas tunggu dirilis untuk melanjutkan eksekusinya.

Status awal objek peristiwa ditentukan oleh parameter dwFlags. Gunakan fungsi SetEvent untuk mengatur status objek peristiwa ke sinyal. Gunakan fungsi ResetEvent untuk mengatur ulang status objek peristiwa ke nonsignaled.

Ketika status objek peristiwa reset manual diberi sinyal, objek tersebut tetap diberi sinyal sampai secara eksplisit diatur ulang ke nonsignaled oleh fungsi ResetEvent. Sejumlah utas tunggu, atau utas yang kemudian memulai operasi tunggu untuk objek peristiwa yang ditentukan, dapat dirilis saat status objek diberi sinyal.

Beberapa proses dapat memiliki penanganan objek peristiwa yang sama, memungkinkan penggunaan objek untuk sinkronisasi antarproses. Mekanisme berbagi objek berikut tersedia:

• Proses turunan yang dibuat oleh fungsi CreateProcess dapat mewarisi handel ke objek peristiwa jika lpEventAttributes parameter pewarisan CreateEvent diaktifkan.
• Proses dapat menentukan handel objek peristiwa dalam panggilan ke fungsi DuplicateHandle untuk membuat handel duplikat yang dapat digunakan oleh proses lain.
• Proses dapat menentukan nama objek peristiwa dalam panggilan ke fungsi OpenEvent atau CreateEvent.

Gunakan fungsi CloseHandle untuk menutup handel. Sistem menutup handel secara otomatis ketika proses berakhir. Objek peristiwa dihancurkan ketika handel terakhirnya telah ditutup.

Nota

Header synchapi.h mendefinisikan CreateEventEx sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows Vista [aplikasi desktop | Aplikasi UWP]
server minimum yang didukung	Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Platform Target	Windows
Header	synchapi.h (termasuk Windows.h pada Windows 7, Windows Server 2008 Windows Server 2008 R2)
Pustaka	Kernel32.lib
DLL	Kernel32.dll

Lihat juga

closeHandle

Objek Peristiwa

Nama Objek

Fungsi Sinkronisasi