Función CreateEventExA (synchapi.h)

  • Artículo

Crea o abre un objeto de evento con nombre o sin nombre y devuelve un identificador al objeto .

Sintaxis

HANDLE CreateEventExA(
  [in, optional] LPSECURITY_ATTRIBUTES lpEventAttributes,
  [in, optional] LPCSTR                lpName,
  [in]           DWORD                 dwFlags,
  [in]           DWORD                 dwDesiredAccess
);

Parámetros

[in, optional] lpEventAttributes

Puntero a una estructura de SECURITY_ATTRIBUTES . Si lpEventAttributes es NULL, los procesos secundarios no pueden heredar el identificador de eventos.

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, 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 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, 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 usuarios 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.

[in] dwFlags

Este parámetro puede ser uno o más de los siguientes valores.

Valor Significado
CREATE_EVENT_INITIAL_SET
0x00000002
 Se señala el estado inicial del objeto de evento; de lo contrario, no tiene signo.
CREATE_EVENT_MANUAL_RESET
0x00000001
 El evento debe restablecerse manualmente mediante la función ResetEvent . 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.

Si no se especifica esta marca, el sistema restablece automáticamente el evento después de liberar un único subproceso en espera.

[in] dwDesiredAccess

Máscara de acceso para el objeto de evento. Para obtener una lista de los derechos de acceso, vea Synchronization Object Security and Access Rights.

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 a la función, la función devuelve un identificador al objeto existente y GetLastError devuelve ERROR_ALREADY_EXISTS.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Cualquier subproceso del proceso de llamada puede especificar el identificador de objeto de evento en una llamada a una de las funciones de espera. Las funciones de espera de objeto único 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 señalizan todos los objetos especificados. Cuando se devuelve una función wait, se libera el subproceso en espera para continuar su ejecución.

El parámetro dwFlags especifica el estado inicial del objeto de evento. Use la función SetEvent 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 a sin signo.

Cuando se señala el estado de un objeto de evento de restablecimiento manual, permanece señalado hasta que se restablece explícitamente a no asignado por la función ResetEvent . 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.

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 la herencia habilitada para 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 la función OpenEvent o 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.

Nota

El encabezado synchapi.h define CreateEventEx 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 Convenciones para prototipos de función.

Requisitos

   
Cliente mínimo compatible Windows Vista [aplicaciones de escritorio | aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 [aplicaciones de escritorio | aplicaciones para UWP]
Plataforma de destino Windows
Encabezado synchapi.h (incluye Windows.h en Windows 7, Windows Server 2008 Windows Server 2008 R2)
Library Kernel32.lib
Archivo DLL Kernel32.dll

Vea también

CloseHandle

Objetos de evento

Nombres de objeto

Funciones de sincronización