Funzione CreateEventW (synchapi.h)

Articolo
08/26/2023

Crea o apre un oggetto evento denominato o senza nome.

Per specificare una maschera di accesso per l'oggetto, usare la funzione CreateEventEx .

Sintassi

HANDLE CreateEventW(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCWSTR               lpName
);

Parametri

[in, optional] lpEventAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES . Se questo parametro è NULL, l'handle 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 dell'autore.

[in] bManualReset

Se questo parametro è TRUE, la funzione crea un oggetto evento di reimpostazione manuale, che richiede l'uso della funzione ResetEvent per impostare lo stato dell'evento su nonsignaled. Se questo parametro è FALSE, la funzione crea un oggetto evento di reimpostazione automatica e il sistema reimposta automaticamente lo stato dell'evento in modo non firmato dopo il rilascio di un singolo thread in attesa.

[in] bInitialState

Se questo parametro è TRUE, lo stato iniziale dell'oggetto evento viene segnalato; in caso contrario, non è firmato.

[in, optional] lpName

Nome dell'oggetto evento. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi è distinzione tra maiuscole e minuscole.

Se lpName corrisponde al nome di un oggetto evento denominato esistente, questa funzione richiede il diritto di accesso EVENT_ALL_ACCESS . In questo caso, i parametri bManualReset e bInitialState vengono ignorati perché sono già stati impostati dal processo di creazione. Se il parametro lpEventAttributes non è NULL, determina se l'handle può essere ereditato, ma il membro del descrittore di sicurezza viene ignorato.

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, un mutex, un timer in attesa, un processo o un oggetto mapping 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.

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 alla 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

L'handle restituito da CreateEvent ha il diritto di accesso EVENT_ALL_ACCESS ; può essere usato in qualsiasi funzione che richiede un handle a un oggetto evento, purché il chiamante abbia concesso l'accesso. Se un evento viene creato da un servizio o da un thread che rappresenta un utente diverso, è possibile applicare un descrittore di sicurezza all'evento quando lo si crea o modificare il descrittore di sicurezza predefinito per il processo di creazione modificando l'elenco dati predefinito. Per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.

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 singolo oggetto restituiscono quando viene segnalato lo stato dell'oggetto specificato. Le funzioni di attesa a più oggetti possono essere indicate per restituire quando uno o quando vengono segnalati tutti gli oggetti specificati. 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 bInitialState . 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 in modo non firmato.

Quando lo stato di un oggetto evento di reimpostazione manuale viene segnalato, rimane segnalato fino a quando non viene reimpostato in modo esplicito alla funzione ResetEvent . È possibile rilasciare qualsiasi numero di thread in attesa o thread che iniziano successivamente le operazioni di attesa per l'oggetto evento specificato, mentre lo stato dell'oggetto viene segnalato.

Quando viene segnalato lo stato di un oggetto evento di reimpostazione automatica, rimane segnalato fino a quando non viene rilasciato un singolo thread in attesa; il sistema reimposta quindi automaticamente lo stato su non firmato. Se non c'è alcun thread in attesa, lo stato dell'oggetto evento resta 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 in un oggetto evento se il parametro lpEventAttributes dell'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 .

Usare la funzione CloseHandle per chiudere l'handle. Il sistema chiude automaticamente l'handle al termine del processo. L'oggetto evento viene eliminato quando l'ultimo handle è stato chiuso.

Esempio

Per un esempio che usa CreateEvent, vedere Uso di oggetti evento.

Nota

L'intestazione synchapi.h definisce CreateEvent 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 di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	synchapi.h (includere Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Libreria	Kernel32.lib
DLL	Kernel32.dll