Función CreateEventA (synchapi.h)

Artículo
11/20/2024

Crea o abre un objeto de evento con nombre o sin nombre.

Para especificar una máscara de acceso para el objeto, use la función CreateEventEx.

Sintaxis

HANDLE CreateEventA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in]           BOOL                  bManualReset,
  [in]           BOOL                  bInitialState,
  [in, optional] LPCSTR                lpName
);

Parámetros

[in, optional] lpEventAttributes

Puntero a una estructura SECURITY_ATTRIBUTES. Si este parámetro es NULL, los procesos secundarios no pueden heredar el identificador.

El miembro lpSecurityDescriptor de la estructura especifica un descriptor de seguridad para el nuevo evento. Si lpEventAttributes es NULL, el evento obtiene un descriptor de seguridad predeterminado. Las ACL del descriptor de seguridad predeterminado para un evento proceden del token principal o de suplantación del creador.

[in] bManualReset

Si este parámetro es TRUE, la función crea un objeto de evento de restablecimiento manual, que requiere el uso de la función ResetEvent para establecer el estado del evento en no asignado. Si este parámetro es FALSE, la función crea un objeto de evento de restablecimiento automático y el sistema restablece automáticamente el estado del evento a no asignado después de que se haya liberado un único subproceso en espera.

[in] bInitialState

Si este parámetro es TRUE, se señala el estado inicial del objeto de evento; de lo contrario, no está asignado.

[in, optional] lpName

Nombre del objeto de evento. El nombre está limitado a MAX_PATH caracteres. La comparación de nombres distingue mayúsculas de minúsculas.

Si lpName coincide con el nombre de un objeto de evento con nombre existente, esta función solicita el derecho de acceso EVENT_ALL_ACCESS. En este caso, los parámetros bManualReset de y bInitialState se omiten porque ya se han establecido mediante el proceso de creación. Si el parámetro lpEventAttributes no es NULL, determina si se puede heredar el identificador, pero se omite su miembro de descriptor de seguridad.

Si lpName es null, el objeto de evento se crea sin un nombre.

Si lpName coincide con el nombre de otro tipo de objeto en el mismo espacio de nombres (por ejemplo, un semáforo existente, una exclusión mutua, un temporizador de espera, un trabajo o un objeto de asignación de archivos), se produce un error en la función y la función GetLastError devuelve ERROR_INVALID_HANDLE. Esto ocurre porque estos objetos comparten el mismo espacio de nombres.

El nombre puede tener un prefijo "Global" o "Local" para crear explícitamente el objeto en el espacio de nombres global o de sesión. El resto del nombre puede contener cualquier carácter excepto el carácter de barra diagonal inversa (\). Para obtener más información, vea espacios de nombres de objeto kernel. El cambio rápido de usuario se implementa mediante sesiones de Terminal Services. Los nombres de objeto de kernel deben seguir las directrices descritas para Terminal Services para que las aplicaciones puedan admitir varios usuarios.

El objeto se puede crear en un espacio de nombres privado. Para obtener más información, vea Espacios de nombres de objeto.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador para el objeto de evento. Si el objeto de evento con nombre existía antes de la llamada de función, la función devuelve un identificador al objeto existente y GetLastError devuelve ERROR_ALREADY_EXISTS.

Si se produce un error en la función, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Observaciones

El identificador devuelto por CreateEvent tiene el derecho de acceso EVENT_ALL_ACCESS; se puede usar en cualquier función que requiera un identificador para un objeto de evento, siempre que se haya concedido acceso al autor de la llamada. Si se crea un evento a partir de un servicio o un subproceso que suplanta a un usuario diferente, puede aplicar un descriptor de seguridad al evento al crearlo o cambiar el descriptor de seguridad predeterminado para el proceso de creación cambiando su DACL predeterminada. Para obtener más información, vea Seguridad de objetos de sincronización y derechos de acceso.

Cualquier subproceso del proceso de llamada puede especificar el identificador de objeto de evento en una llamada a una de las funciones de espera de . Las funciones de espera de un solo objeto devuelven cuando se señala el estado del objeto especificado. Se pueden indicar a las funciones de espera de varios objetos que devuelvan cuando se indique cualquiera o cuando se señalen todos los objetos especificados. Cuando se devuelve una función de espera, se libera el subproceso en espera para continuar su ejecución.

El parámetro bInitialState especifica el estado inicial del objeto de evento. Use la función setEvent de para establecer el estado de un objeto de evento en señalizado. Use la función ResetEvent para restablecer el estado de un objeto de evento en no asignado.

Cuando se señala el estado de un objeto de evento de restablecimiento manual, permanece señalado hasta que la función ResetEvent restablece explícitamente. Se puede liberar cualquier número de subprocesos en espera o subprocesos que, posteriormente, inicien operaciones de espera para el objeto de evento especificado, mientras se señala el estado del objeto.

Cuando se señala el estado de un objeto de evento de restablecimiento automático, permanece señalado hasta que se libera un único subproceso en espera; A continuación, el sistema restablece automáticamente el estado en no asignado. Si no hay subprocesos en espera, el estado del objeto de evento permanece señalado.

Varios procesos pueden tener identificadores del mismo objeto de evento, lo que permite el uso del objeto para la sincronización entre procesos. Están disponibles los siguientes mecanismos de uso compartido de objetos:

Un proceso secundario creado por la función CreateProcess puede heredar un identificador a un objeto de evento si el parámetro lpEventAttributes de herencia habilitada CreateEvent.
Un proceso puede especificar el identificador de objeto de evento en una llamada a la función DuplicateHandle para crear un identificador duplicado que otro proceso pueda usar.
Un proceso puede especificar el nombre de un objeto de evento en una llamada a openEvent o función CreateEvent.

Use la función CloseHandle para cerrar el identificador. El sistema cierra el identificador automáticamente cuando finaliza el proceso. El objeto de evento se destruye cuando se ha cerrado su último identificador.

Ejemplos

Para obtener un ejemplo que usa CreateEvent, vea Using Event Objects.

Nota

El encabezado synchapi.h define CreateEvent como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [aplicaciones de escritorio \| Aplicaciones para UWP]
servidor mínimo admitido	Windows Server 2003 [aplicaciones de escritorio \| Aplicaciones para UWP]
de la plataforma de destino de	Windows
encabezado de	synchapi.h (incluya Windows.h en Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll