Función SetTimer (winuser.h)

Artículo
04/07/2023

Crea un temporizador con el valor de tiempo de espera especificado.

Sintaxis

UINT_PTR SetTimer(
  [in, optional] HWND      hWnd,
  [in]           UINT_PTR  nIDEvent,
  [in]           UINT      uElapse,
  [in, optional] TIMERPROC lpTimerFunc
);

Parámetros

[in, optional] hWnd

Tipo: HWND

Identificador de la ventana que se va a asociar con el temporizador. Esta ventana debe ser propiedad del subproceso que realiza la llamada. Si se pasa un valor NULL para hWnd junto con un nIDEvent de un temporizador existente, ese temporizador se reemplazará de la misma manera que será un temporizador hWnd no NULL existente.

[in] nIDEvent

Tipo: UINT_PTR

Identificador de temporizador distinto de cero. Si el parámetro hWnd es NULL y nIDEvent no coincide con un temporizador existente, se omite y se genera un nuevo identificador de temporizador. Si el parámetro hWnd no es NULL y la ventana especificada por hWnd ya tiene un temporizador con el valor nIDEvent, el temporizador existente se reemplaza por el nuevo temporizador. Cuando SetTimer reemplaza un temporizador, se restablece el temporizador. Por lo tanto, se enviará un mensaje después de que transcurre el valor de tiempo de espera actual, pero se omite el valor de tiempo de espera establecido anteriormente. Si la llamada no está pensada para reemplazar un temporizador existente, nIDEvent debe ser 0 si hWnd es NULL.

[in] uElapse

Tipo: UINT

El valor del tiempo de espera, en milisegundos.

Si uElapse es menor que USER_TIMER_MINIMUM (0x0000000A), el tiempo de espera se establece en USER_TIMER_MINIMUM. Si uElapse es mayor que USER_TIMER_MAXIMUM (0x7FFFFFFF), el tiempo de espera se establece en USER_TIMER_MAXIMUM.

[in, optional] lpTimerFunc

Tipo: TIMERPROC

Puntero a la función que se va a notificar cuando transcurre el valor de tiempo de espera. Para obtener más información sobre la función, vea TimerProc. Si lpTimerFunc es NULL, el sistema envía un mensaje WM_TIMER a la cola de la aplicación. El miembro hwnd de la estructura MSG del mensaje contiene el valor del parámetro hWnd .

Valor devuelto

Tipo: UINT_PTR

Si la función se ejecuta correctamente y el parámetro hWnd es NULL, el valor devuelto es un entero que identifica el nuevo temporizador. Una aplicación puede pasar este valor a la función KillTimer para destruir el temporizador.

Si la función se ejecuta correctamente y el parámetro hWnd no es NULL, el valor devuelto es un entero distinto de cero. Una aplicación puede pasar el valor del parámetro nIDEvent a la función KillTimer para destruir el temporizador.

Si la función no puede crear un temporizador, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Una aplicación puede procesar WM_TIMER mensajes mediante la inclusión de una instrucción case WM_TIMER en el procedimiento de ventana o mediante la especificación de una función de devolución de llamada TimerProc al crear el temporizador. Cuando se especifica una función de devolución de llamada TimerProc , DispatchMessage llama a la función de devolución de llamada en lugar de llamar al procedimiento de ventana cuando procesa WM_TIMER con un lParam distinto de NULL. Por lo tanto, debe enviar mensajes en el subproceso de llamada, incluso cuando se usa TimerProc en lugar de procesar WM_TIMER.

El parámetro wParam del mensaje WM_TIMER contiene el valor del parámetro nIDEvent .

El identificador del temporizador, nIDEvent, es específico de la ventana asociada. Otra ventana puede tener su propio temporizador que tiene el mismo identificador que un temporizador propiedad de otra ventana. Los temporizadores son distintos.

SetTimer puede reutilizar los identificadores de temporizador en el caso de que hWnd sea NULL.

Antes de usar SetTimer u otras funciones relacionadas con el temporizador, se recomienda establecer la marca de UOI_TIMERPROC_EXCEPTION_SUPPRESSION en false a través de la función SetUserObjectInformationW ; de lo contrario, la aplicación podría comportarse de forma impredecible y podría ser vulnerable a vulnerabilidades de seguridad. Para obtener más información, consulta SetUserObjectInformationW.

Ejemplos

Para obtener un ejemplo, consulte Creación de un temporizador.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-window-l1-1-2 (introducido en Windows 10, versión 10.0.10240)