Funzione ZwCreateEvent (ntifs.h)

Articolo
07/11/2023

La routine ZwCreateEvent crea un oggetto evento, imposta lo stato iniziale dell'evento sul valore specificato e apre un handle all'oggetto con l'accesso desiderato specificato.

Sintassi

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

Parametri

[out] EventHandle

Puntatore a una variabile che riceverà l'handle dell'oggetto evento. L'handle include informazioni sulla contabilità, ad esempio un conteggio dei riferimenti e un contesto di sicurezza.

[in] DesiredAccess

Valore ACCESS_MASK che rappresenta i tipi di accesso desiderati per l'oggetto evento. La tabella seguente contiene i valori di ACCESS_MASK specifici dell'evento.

Valore	Accesso desiderato
EVENT_QUERY_STATE	Eseguire una query sullo stato dell'oggetto evento.
EVENT_MODIFY_STATE	Modificare lo stato dell'oggetto evento.
EVENT_ALL_ACCESS	Tutti i diritti di accesso possibili all'oggetto evento.

[in, optional] ObjectAttributes

Puntatore alla struttura degli attributi dell'oggetto fornita dal chiamante da utilizzare per l'oggetto specificato. Questi attributi includono objectName e il SECURITY_DESCRIPTOR, ad esempio. Questo parametro viene inizializzato chiamando la macro InitializeObjectAttributes .

[in] EventType

Tipo dell'evento, che può essere SynchronizationEvent o NotificationEvent. Questi valori appartengono all'enumerazione EVENT_TYPE , definita nel file di intestazione ntdef.h .

[in] InitialState

Stato iniziale dell'oggetto evento. Impostare su TRUE per inizializzare l'oggetto evento sullo stato Signaled. Impostare su FALSE per inizializzare l'oggetto evento sullo stato not-Signaled.

Valore restituito

ZwCreateEvent restituisce STATUS_SUCCESS o uno stato di errore appropriato. I codici di stato di errore possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare le risorse richieste da questa funzione.
STATUS_INVALID_PARAMETER	La struttura ObjectAttributes fornita contiene un valore di parametro non valido.
STATUS_INVALID_PARAMETER_4	Il parametro EventType specificato non è valido.
STATUS_OBJECT_NAME_INVALID	Il parametro ObjectAttributes contiene un ObjectName nella struttura OBJECT_ATTRIBUTES non valida.
STATUS_OBJECT_PATH_SYNTAX_BAD	Il parametro ObjectAttributes non contiene un membro RootDirectory , ma il membro ObjectName nella struttura OBJECT_ATTRIBUTES è una stringa vuota o non contiene un carattere OBJECT_NAME_PATH_SEPARATOR. Indica una sintassi non corretta per il percorso dell'oggetto.
STATUS_PRIVILEGE_NOT_HELD	Il chiamante non dispone del privilegio necessario per creare un handle con l'accesso specificato nel parametro DesiredAccess .

Commenti

ZwCreateEvent crea un oggetto evento, imposta lo stato iniziale sul valore specificato e apre un handle all'oggetto con l'accesso desiderato specificato.

Gli eventi vengono usati per coordinare l'esecuzione. Gli eventi possono essere usati dai driver del file system per consentire a un chiamante di attendere il completamento dell'operazione richiesta fino a quando l'evento specificato non viene impostato sullo stato Segnalato.

ZwCreateEvent può creare eventi di notifica o sincronizzazione:

Gli eventi di notifica possono essere usati per notificare a uno o più thread di esecuzione che si è verificato un evento.
Gli eventi di sincronizzazione possono essere usati nella serializzazione dell'accesso all'hardware tra due driver altrimenti non correlati.

Un evento di sincronizzazione viene reimpostato automaticamente. Quando un evento di sincronizzazione è impostato sullo stato Segnalato, viene rilasciato un singolo thread di esecuzione in attesa del rilascio dell'evento e l'evento viene reimpostato automaticamente sullo stato Not-Signaled.

A differenza di un evento di sincronizzazione, un evento di notifica non viene reimpostato automaticamente. Quando un evento di notifica è nello stato Segnalato, rimane in tale stato fino a quando non viene reimpostato in modo esplicito.

Per eseguire la sincronizzazione in un evento di notifica:

Creare l'evento di notifica con ZwCreateEvent con il parametro EventType impostato su NotificationEvent.
Attendere che l'evento venga segnalato chiamando ZwWaitForSingleObject con EventHandle restituito da ZwCreateEvent. Più di un thread di esecuzione può attendere che venga segnalato un determinato evento di notifica. Per eseguire il polling invece di stallo, specificare un timeout pari a zero su ZwWaitForSingleObject.
Chiudere l'handle all'evento di notifica con ZwClose quando l'accesso all'evento non è più necessario.

La funzione ZwCreateEvent viene chiamata dopo l'utilizzo della macro InitializeObjectAttributes per impostare gli attributi nella struttura OBJECT_ATTRIBUTES per l'oggetto.

Esistono due modi alternativi per specificare il nome dell'oggetto passato a ZwCreateEvent:

Come pathname completo, fornito nel membro ObjectName dell'oggetto ObjectAttributes di input.
Come pathname relativo alla directory rappresentata dall'handle nel membro RootDirectory dell'oggetto ObjectAttributes di input.

Per rilasciare l'evento, un driver chiama ZwClose con l'handle dell'evento.

Per altre informazioni sugli eventi, vedere Oggetti evento.

Nota

Se la chiamata alla routine ZwCreateEvent viene eseguita in modalità utente, è consigliabile usare il nome "NtCreateEvent" anziché "ZwCreateEvent".

Per le chiamate da driver in modalità kernel, le versioni NtXxx e ZwXxx di una routine di Servizi di sistema nativi di Windows possono comportarsi in modo diverso nel modo in cui gestiscono e interpretano i parametri di input. Per altre informazioni sulla relazione tra le versioni NtXxx e ZwXxx di una routine, vedere Using Nt and Zw Versions of the Native System Services Routines .For more information about the Nt Xxx and Zw versions of the Native System Services Routines.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP.
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)