Funzione ZwOpenEvent (wdm.h)

Articolo
12/21/2024

La routine ZwOpenEvent apre un handle a un oggetto evento denominato esistente con l'accesso desiderato specificato.

Sintassi

NTSYSCALLAPI NTSTATUS ZwOpenEvent(
  [out] PHANDLE            EventHandle,
  [in]  ACCESS_MASK        DesiredAccess,
  [in]  POBJECT_ATTRIBUTES ObjectAttributes
);

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] ObjectAttributes

Puntatore alla struttura degli attributi dell'oggetto fornita dal chiamante per l'oggetto specificato. Questi attributi includono il ObjectName e gli attributi di handle, ad esempio. Questo parametro viene inizializzato chiamando la macro InitializeObjectAttributes.

Valore restituito

zwOpenEvent restituisce STATUS_SUCCESS o uno stato di errore appropriato. Questa routine potrebbe restituire uno dei codici di stato di errore seguenti:

Codice restituito	Descrizione
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare le risorse richieste da questa funzione.
STATUS_INVALID_PARAMETER	La struttura ObjectAttributes non è stata specificata o contenuta in un valore di parametro non valido.
STATUS_OBJECT_NAME_INVALID	Il parametro ObjectAttributes contiene un ObjectName nella struttura OBJECT_ATTRIBUTES non valida.
STATUS_OBJECT_PATH_SYNTAX_BAD	Il percorso dell'oggetto contiene una sintassi errata. Ad esempio, il parametro ObjectAttributes non contiene un membro RootDirectory , ma il membro objectName nella struttura OBJECT_ATTRIBUTES è una stringa vuota o non inizia con un carattere OBJECT_NAME_PATH_SEPARATOR.
STATUS_OBJECT_PATH_NOT_FOUND	Il percorso dell'oggetto non è stato trovato, a indicare che non esiste.
STATUS_OBJECT_NAME_NOT_FOUND	Il nome dell'oggetto non è stato trovato, a indicare che l'oggetto non esiste.
STATUS_PRIVILEGE_NOT_HELD	Il chiamante non dispone del privilegio necessario per creare un handle con l'accesso specificato nel parametro DesiredAccess.

Osservazioni

ZwOpenEvent apre un oggetto evento denominato esistente e crea un handle all'oggetto con l'accesso desiderato specificato.

i ZwOpenEvent possono aprire eventi di notifica o sincronizzazione.

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

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.

Se la chiamata alla funzione di ZwOpenEvent viene eseguita in modalità utente, è necessario usare il nome "NtOpenEvent" anziché "ZwOpenEvent".

Per le chiamate da driver in modalità kernel, le NtXxx e ZwXxx versioni di una routine di 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.

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
intestazione	wdm.h (include Wdm.h)
libreria	NtosKrnl.lib
dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
regole di conformità DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)