CreateEvent

Crea un objeto evento con o sin nombre.

Sintaxis

HANDLE CreateEvent(
    LPSECURITY_ATTRIBUTES lpEventAttributes,  // dirección de atributos de seguridad
    BOOL bManualReset,   // flag para eventos de reset manual
    BOOL bInitialState,  // flag para estado inicial
    LPCTSTR lpName       // dirección del nombre de objeto evento
   );

Parámetros:

lpEventAttributes: apunta a una estructura SECURITY_ATTRIBUTES que especifica los atributos de seguridad para el objeto evento.

Si lpEventAttributes es NULL, el objeto evento se crea con el descriptor de seguridad por defecto y el manipulador resultante no es heredable.

bManualReset: especifica si se creará un objeto evento de reset manual o automático. Si es TRUE, entonces debe usarse la función ResetEvent para resetear manualmente el estado a "no señalizado". Si es FALSE, Windows resetea automáticamente el estado a "no señalizado" después de se realice un sencillo hilo de espera.

bInitialState: especifica el estado inicial del objeto evento. Si es TRUE, el estado inicial es "señalizado"; en caso contrario será "no señalizado".

lpName: apunta a una cadena terminada en cero que especifica el nombre del objeto evento. El nombre está limitado a MAX_PATH caracteres y puede contener cualquier carácter excepto el carácter de separador de camino, la barra descendente (\). Las comparaciones de nombres son sensibles al tipo, distinguen mayúsculas y minúsculas.

Si lpName coincide con algún nombre de un objeto evento con nombre existente, esta función pide acceso EVENT_ALL_ACCESS al objeto existente. En este caso, los parámetros bManualReset y bInitialState se ignoran porque ya han sido puestos por el proceso creado. Si el parámetro lpEventAttributes no es NULL, determina si el manipulador puede o no ser heredado, pero su miembro descriptor de seguridad se ignora.

Si lpName es NULL, el objeto evento se crea sin nombre.

Si lpName coincide con el nombre de cualquier objeto semáforo, mutex o file-mapping existente, la función falla y GetLastError devuelve ERROR_INVALID_HANDLE. Esto ocurre porque los objetos evento, mutex, semáforo y file-mapping comparten el mismo espacio de nombres.

Valor de retorno

Si la función tiene éxito, el valor de retorno es un manipulador de un objeto evento. Si el objeto evento con nombre existía antes de la llamada a la función, la función GetLastError devuelve ERROR_ALREADY_EXISTS. En otro caso, GetLastError devuelve cero.

Si la función falla, el valor de retorno es NULL. Para obtener información adicional sobre el error, llamar a GetLastError.

Observaciones

El manipulador devuelto por CreateEvent tiene acceso EVENT_ALL_ACCESS al nuevo objeto evento y puede ser usado por cualquier función que necesite un manipulador a un objeto evento.

Cualquier hilo del proceso que llama puede especificar el manipulador de objeto evento en una llamada a una de las funciones de espera (MsgWaitForMultipleObjects, WaitForSingleObject, WaitForMultipleObjects, WaitForSingleObjectEx o WaitForMultipleObjectsEx). Las funciones de espera de un objeto vuelven cuando el estado del objeto especificado es señalizado. Las funciones de espera de múltiples objetos pueden ser configuradas para volver tanto cuando uno de los objetos especificados o cuando todos ellos son señalizados. Cuando una función de espera retorna, se permite al hilo de espera continuar su ejecución.

El estado inicial del objeto evento se especifica mediante el parámetro bInitialState. Se usa la función SetEvent para poner el estado de un objeto evento a "señalizado". La función ResetEvent se usa para resetear el estado de un objeto evento a "no señalizado".

Cuando el estado de un objeto evento de reset manual es "señalizado", permanece en ese estado hasta que se resetee explícitamente mediante la función ResetEvent. Cualquier número de hilos en espera, o de hilos que subsecuentemente comiencen operaciones de espera para el objeto evento especificado, puede ser liberado mientras el estado del objeto es "señalizado".

Cuando el estado de un objeto evento de reset automático es "señalizado", permanece en ese estado hasta que se libere un hilo que espere un sólo evento; el sistema entonces resetea automáticamente el estado a "no señalizado". Si no hay hilos esperando, el estado del objeto evento permanece "señalizado".

Varios procesos pueden tener manipuladores para el mismo objeto evento, permitiendo usar el objeto para sincronizaciones entre procesos. Están disponibles los siguientes mecanismos de compartir objetos:

• Un proceso hijo creado mediante CreateProcess puede heredar un manipulador de un objeto evento si el parámetro lpEventAttributes de CreateEvent permite la herencia.
• Un proceso puede especificar el manipulador de objeto evento en una llamada a la función DuplicateHandle para crear un duplicado del manipulador que puede ser usado por otro proceso.
• Un proceso puede especificar el nombre de un objeto evento en una llamada a OpenEvent o CreateEvent.

Usar la función CloseHandle para cerrar el manipulador. El sistema cierra el manipulador automáticamente cuando el proceso termina. El objeto evento se destruye cuando el último manipulador ha sido cerrado.