Funzione ZwCreateEvent (ntifs.h)

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:

  1. Creare l'evento di notifica con ZwCreateEvent con il parametro EventType impostato su NotificationEvent.

  2. 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 per ZwWaitForSingleObject.

  3. 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 Windows Native System Services 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 NtXxx versions of the Native System Services Routines.

Requisiti

   
Client minimo supportato Disponibile a partire da 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)

Vedi anche

ACCESS_MASK

InitializeObjectAttributes

IoCreateNotificationEvent

IoCreateSynchronizationEvent

KeClearEvent

KeResetEvent

KeSetEvent

KeWaitForSingleObject

Uso delle versioni Nt e Zw delle routine native di Servizi di sistema

ZwClose

ZwSetEvent

ZwWaitForSingleObject