Fungsi CreateEventA (synchapi.h)
Membuat atau membuka objek peristiwa bernama atau tidak bernama.
Untuk menentukan masker akses untuk objek, gunakan fungsi CreateEventEx .
Sintaks
HANDLE CreateEventA(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in] BOOL bManualReset,
[in] BOOL bInitialState,
[in, optional] LPCSTR lpName
);
Parameter
[in, optional] lpEventAttributes
Penunjuk ke struktur SECURITY_ATTRIBUTES . Jika parameter ini NULL, handel tidak dapat diwariskan oleh proses turunan.
Anggota lpSecurityDescriptor dari struktur menentukan deskriptor keamanan untuk peristiwa baru. Jika lpEventAttributesadalah NULL, peristiwa tersebut akan mendapatkan pendeskripsi keamanan default. ACL dalam deskriptor keamanan default untuk peristiwa berasal dari token utama atau peniruan dari pembuat.
[in] bManualReset
Jika parameter ini TRUE, fungsi membuat objek peristiwa reset manual, yang memerlukan penggunaan fungsi ResetEvent untuk mengatur status peristiwa ke nonsignaled. Jika parameter ini FALSE, fungsi membuat objek peristiwa reset otomatis, dan sistem secara otomatis mengatur ulang status peristiwa ke nonsignaled setelah satu utas tunggu dirilis.
[in] bInitialState
Jika parameter ini TRUE, status awal objek peristiwa akan disinyalir; jika tidak, itu tidak ditandatangani.
[in, optional] lpName
Nama objek peristiwa. Nama ini terbatas pada MAX_PATH karakter. Perbandingan nama peka huruf besar/kecil.
Jika lpName cocok dengan nama objek peristiwa bernama yang ada, fungsi ini meminta hak akses EVENT_ALL_ACCESS . Dalam hal ini, parameter bManualReset dan bInitialState diabaikan karena telah ditetapkan oleh proses pembuatan. Jika parameter lpEventAttributes bukan NULL, parameter menentukan apakah handel dapat diwariskan, tetapi anggota deskriptor keamanannya diabaikan.
Jika lpNameNULL, objek peristiwa dibuat tanpa nama.
Jika lpName cocok dengan nama jenis objek lain di namespace yang sama (seperti semaphore, mutex, timer yang dapat di tunggu, pekerjaan, atau objek pemetaan file), 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 Namespace Objek.
Nilai kembali
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, hubungi GetLastError.
Keterangan
Handel yang dikembalikan oleh CreateEvent memiliki hak akses EVENT_ALL_ACCESS ; ini dapat digunakan dalam fungsi apa pun yang memerlukan handel ke objek peristiwa, asalkan pemanggil telah diberikan akses. Jika peristiwa dibuat dari layanan atau utas yang meniru pengguna lain, Anda dapat menerapkan pendeskripsi keamanan ke peristiwa saat Anda membuatnya, atau mengubah deskriptor keamanan default untuk proses pembuatan dengan mengubah DACL defaultnya. Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.
Setiap utas proses panggilan dapat menentukan handel objek peristiwa dalam panggilan ke salah satu fungsi tunggu. Fungsi tunggu objek tunggal kembali saat status objek yang ditentukan diberi sinyal. Fungsi tunggu beberapa objek dapat diinstruksikan untuk kembali 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 bInitialState . 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 disinyalir hingga 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.
Ketika status objek peristiwa reset otomatis disinyalir, objek tersebut tetap disinyalir hingga satu utas tunggu dirilis; sistem kemudian secara otomatis mengatur ulang status ke nonsignaled. Jika tidak ada utas yang menunggu, status objek peristiwa tetap diberi sinyal.
Beberapa proses dapat memiliki penanganan objek peristiwa yang sama, memungkinkan penggunaan objek untuk sinkronisasi antarproses. Mekanisme berbagi objek berikut tersedia:
- Proses anak yang dibuat oleh fungsi CreateProcess dapat mewarisi handel ke objek peristiwa jika parameter lpEventAttributes dari pewarisan yang diaktifkan CreateEvent .
- 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 .
Contoh
Untuk contoh yang menggunakan CreateEvent, lihat Menggunakan Objek Peristiwa.
Catatan
Header synchapi.h mendefinisikan CreateEvent 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
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Windows XP [aplikasi desktop | Aplikasi UWP] |
| Server minimum yang didukung | Windows Server 2003 [aplikasi desktop | Aplikasi UWP] |
| Target Platform | Windows |
| Header | synchapi.h (termasuk Windows.h pada Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Pustaka | Kernel32.lib |
| DLL | Kernel32.dll |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk