Función CreateWaitableTimerW (synchapi.h)
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 de 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 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 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 de .
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 lpTimerAttributes parámetro 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.
Para compilar una aplicación que use esta función, defina _WIN32_WINNT como 0x0400 o posterior. Para obtener más información, vea Using the Windows Headers.
Para asociar un temporizador a una ventana, use la función SetTimer.
Ejemplos
Para obtener un ejemplo que usa createWaitableTimer, vea Using Waitable Timer Objects.
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) |
| biblioteca de |
Kernel32.lib |
| DLL de |
Kernel32.dll |