Funzione ZwOpenEvent (wdm.h)

Articolo
08/08/2023

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 da utilizzare per l'oggetto specificato. Questi attributi includono objectName e gli attributi 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 contiene 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 non corretta. 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 .

Commenti

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

ZwOpenEvent può 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 ZwOpenEvent si verifica in modalità utente, è necessario usare il nome "NtOpenEvent" anziché "ZwOpenEvent".

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