Funzione CreateEventExA (synchapi.h)
Crea o apre un oggetto evento denominato o senza nome e restituisce un handle all'oggetto .
Sintassi
HANDLE CreateEventExA(
[in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
[in, optional] LPCSTR lpName,
[in] DWORD dwFlags,
[in] DWORD dwDesiredAccess
);
Parametri
[in, optional] lpEventAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES . Se lpEventAttributes è NULL, l'handle di eventi non può essere ereditato dai processi figlio.
Il membro lpSecurityDescriptor della struttura specifica un descrittore di sicurezza per il nuovo evento. Se lpEventAttributes è NULL, l'evento ottiene un descrittore di sicurezza predefinito. Gli ACL nel descrittore di sicurezza predefinito per un evento provengono dal token primario o di rappresentazione del creatore.
[in, optional] lpName
Nome dell'oggetto evento. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi fa distinzione tra maiuscole e minuscole.
Se lpName è NULL, l'oggetto evento viene creato senza un nome.
Se lpName corrisponde al nome di un altro tipo di oggetto nello stesso spazio dei nomi (ad esempio un semaforo esistente, mutex, timer waitable, processo o oggetto di mapping di file), la funzione ha esito negativo e la funzione GetLastError restituisce ERROR_INVALID_HANDLE. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.
Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel. Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.
L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.
[in] dwFlags
Questo parametro può essere uno o più dei valori seguenti.
valore | Significato |
---|---|
|
Lo stato iniziale dell'oggetto evento viene segnalato; in caso contrario, non è firmato. |
|
L'evento deve essere reimpostato manualmente usando la funzione ResetEvent . È possibile rilasciare un numero qualsiasi di thread in attesa o thread che iniziano successivamente operazioni di attesa per l'oggetto evento specificato, mentre lo stato dell'oggetto viene segnalato.
Se questo flag non viene specificato, il sistema reimposta automaticamente l'evento dopo il rilascio di un singolo thread in attesa. |
[in] dwDesiredAccess
Maschera di accesso per l'oggetto evento. Per un elenco dei diritti di accesso, vedere Synchronization Object Security and Access Rights.For a list of access rights, see Synchronization Object Security and Access Rights.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è un handle per l'oggetto evento. Se l'oggetto evento denominato esiste prima della chiamata di funzione, la funzione restituisce un handle all'oggetto esistente e GetLastError restituisce ERROR_ALREADY_EXISTS.
Se la funzione ha esito negativo, il valore restituito è NULL. Per informazioni dettagliate sull'errore, chiamare GetLastError.
Commenti
Qualsiasi thread del processo chiamante può specificare l'handle dell'oggetto evento in una chiamata a una delle funzioni di attesa. Le funzioni di attesa a oggetto singolo restituiscono quando viene segnalato lo stato dell'oggetto specificato. È possibile indicare alle funzioni di attesa a più oggetti di restituire uno o quando tutti gli oggetti specificati vengono indicati. Quando viene restituita una funzione di attesa, il thread in attesa viene rilasciato per continuare l'esecuzione.
Lo stato iniziale dell'oggetto evento viene specificato dal parametro dwFlags . Utilizzare la funzione SetEvent per impostare lo stato di un oggetto evento su segnalato. Utilizzare la funzione ResetEvent per reimpostare lo stato di un oggetto evento su non firmato.
Quando viene segnalato lo stato di un oggetto evento di reimpostazione manuale, rimane segnalato fino a quando non viene reimpostato in modo esplicito su non assegnato dalla funzione ResetEvent . È possibile rilasciare un numero qualsiasi di thread in attesa o thread che iniziano successivamente operazioni di attesa per l'oggetto evento specificato, mentre lo stato dell'oggetto viene segnalato.
Più processi possono avere handle dello stesso oggetto evento, consentendo l'uso dell'oggetto per la sincronizzazione tra processi. Sono disponibili i meccanismi di condivisione degli oggetti seguenti:
- Un processo figlio creato dalla funzione CreateProcess può ereditare un handle a un oggetto evento se il parametro lpEventAttributesdell'ereditarietà abilitata per CreateEvent .
- Un processo può specificare l'handle dell'oggetto evento in una chiamata alla funzione DuplicateHandle per creare un handle duplicato che può essere usato da un altro processo.
- Un processo può specificare il nome di un oggetto evento in una chiamata alla funzione OpenEvent o CreateEvent .
Nota
L'intestazione synchapi.h definisce CreateEventEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
Client minimo supportato | Windows Vista [app desktop | App UWP] |
Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
Piattaforma di destinazione | Windows |
Intestazione | synchapi.h (include Windows.h in Windows 7, Windows Server 2008 Windows Server 2008 R2) |
Libreria | Kernel32.lib |
DLL | Kernel32.dll |