Función ZwOpenEvent (wdm.h)

Artículo
12/21/2024

La rutina ZwOpenEvent abre un identificador para un objeto de evento con nombre existente con el acceso deseado especificado.

Sintaxis

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

Parámetros

[out] EventHandle

Puntero a una variable que recibirá el identificador del objeto de evento. El identificador incluye información de contabilidad, como un recuento de referencias y un contexto de seguridad.

[in] DesiredAccess

Valor ACCESS_MASK que representa los tipos de acceso deseados para el objeto de evento. La tabla siguiente contiene los valores de ACCESS_MASK específicos del evento.

Valor	Acceso deseado
EVENT_QUERY_STATE	Consulte el estado del objeto de evento.
EVENT_MODIFY_STATE	Modifique el estado del objeto de evento.
EVENT_ALL_ACCESS	Todos los derechos de acceso posibles al objeto de evento.

[in] ObjectAttributes

Puntero a la estructura de atributos de objeto que el autor de la llamada proporcionó para el objeto especificado. Estos atributos incluirían el ObjectName y los atributos handle, por ejemplo. Este parámetro se inicializa llamando a la macro InitializeObjectAttributes.

Valor devuelto

ZwOpenEvent devuelve STATUS_SUCCESS o un estado de error adecuado. Esta rutina puede devolver uno de los siguientes códigos de estado de error:

Código devuelto	Descripción
STATUS_INSUFFICIENT_RESOURCES	No se pudieron asignar recursos que requiere esta función.
STATUS_INVALID_PARAMETER	El ObjectAttributes estructura no se proporcionó ni contenía un valor de parámetro no válido.
STATUS_OBJECT_NAME_INVALID	El parámetro ObjectAttributes contenía un ObjectName de en la estructura OBJECT_ATTRIBUTES que no era válida.
STATUS_OBJECT_PATH_SYNTAX_BAD	La ruta de acceso del objeto contenía una sintaxis incorrecta. Por ejemplo, el parámetro ObjectAttributes no contiene un miembro RootDirectory, pero el miembro ObjectName de la estructura OBJECT_ATTRIBUTES es una cadena vacía o no comienza con un carácter OBJECT_NAME_PATH_SEPARATOR.
STATUS_OBJECT_PATH_NOT_FOUND	No se encontró la ruta de acceso al objeto, lo que indica que no existe.
STATUS_OBJECT_NAME_NOT_FOUND	No se encontró el nombre del objeto, lo que indica que el objeto no existe.
STATUS_PRIVILEGE_NOT_HELD	El autor de la llamada no tenía el privilegio necesario para crear un identificador con el acceso especificado en el parámetro DesiredAccess.

Observaciones

ZwOpenEvent abre un objeto de evento con nombre existente y crea un identificador para el objeto con el acceso deseado especificado.

ZwOpenEvent puede abrir eventos de notificación o sincronización.

Los eventos se usan para coordinar la ejecución. Los controladores del sistema de archivos pueden usar eventos para permitir que un autor de la llamada espere a que se complete la operación solicitada hasta que el evento especificado esté establecido en el estado Signaled.

Los eventos de notificación se pueden usar para notificar a uno o varios subprocesos de ejecución que se ha producido un evento. Los eventos de sincronización se pueden usar en la serialización del acceso al hardware entre dos controladores no relacionados de otro modo.

Si la llamada a ZwOpenEvent función se produce en modo de usuario, debe usar el nombre "NtOpenEvent" en lugar de "ZwOpenEvent".

En el caso de las llamadas desde controladores en modo kernel, las NtXxx y Zwversiones de Xxx de una rutina de Servicios del sistema nativo de Windows pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones de NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
encabezado de	wdm.h (incluya Wdm.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	PASSIVE_LEVEL
reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)