Función CreateWaitableTimerW (synchapi.h)

Artículo
08/26/2023

Crea o abre un objeto de temporizador que se puede esperar.

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

Sintaxis

HANDLE CreateWaitableTimerW(
  [in, optional] LPSECURITY_ATTRIBUTES lpTimerAttributes,
  [in]           BOOL                  bManualReset,
  [in, optional] LPCWSTR               lpTimerName
);

Parámetros

[in, optional] lpTimerAttributes

Puntero a una estructura SECURITY_ATTRIBUTES que especifica un descriptor de seguridad para el nuevo objeto de temporizador y determina si los procesos secundarios pueden heredar el identificador devuelto.

Si lpTimerAttributes es NULL, el objeto de temporizador obtiene un descriptor de seguridad predeterminado y el identificador no se puede heredar. Las ACL del descriptor de seguridad predeterminado para un temporizador proceden del token principal o de suplantación del creador.

[in] bManualReset

Si este parámetro es TRUE, el temporizador es un temporizador de notificación de restablecimiento manual. De lo contrario, el temporizador es un temporizador de sincronización.

[in, optional] lpTimerName

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

Si lpTimerName es NULL, el objeto de temporizador se crea sin un nombre.

Si lpTimerName coincide con el nombre de un evento existente, semáforo, exclusión mutua, trabajo o objeto de asignación de archivos, se produce un error en la función y 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 temporizador. Si el objeto de temporizador con nombre existe 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

El identificador devuelto por CreateWaitableTimer se crea con el derecho de acceso TIMER_ALL_ACCESS ; se puede usar en cualquier función que requiera un identificador para un objeto de temporizador, siempre que se haya concedido acceso al autor de la llamada. Si se crea un temporizador a partir de un servicio o subproceso que suplanta a un usuario diferente, puede aplicar un descriptor de seguridad al temporizador 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 del temporizador en una llamada a una de las funciones de espera.

Varios procesos pueden tener identificadores para el mismo objeto de temporizador, lo que permite el uso del objeto para la sincronización entre procesos.

Un proceso creado por la función CreateProcess puede heredar un identificador a un objeto de temporizador si el parámetro lpTimerAttributes de CreateWaitableTimer habilita la herencia.
Un proceso puede especificar el identificador de objeto del temporizador en una llamada a la función DuplicateHandle . Otro proceso puede usar el identificador resultante.
Un proceso puede especificar el nombre de un objeto de temporizador en una llamada a la función OpenWaitableTimer o CreateWaitableTimer .

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

Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0400 o posterior. Para obtener más información, vea Uso de los encabezados de Windows.

Para asociar un temporizador a una ventana, use la función SetTimer .

Ejemplos

Para ver un ejemplo que usa CreateWaitableTimer, vea Using Waitable Timer Objects.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	synchapi.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll