SetTimer

指定時間でタイムアウトするタイマを生成する。

UINT_PTR SetTimer(HWND hWnd, UINT_PTR nIDEvent, UINT uElapse, TIMERPROC lpTimerFunc);

パラメータ

• hWnd

  タイマに関連付けるウィンドウのハンドルを指定する。このウィンドウは、呼び出し側のスレッドが所有しているものでなければならない。NULLを指定すると、どのウィンドウにも関連付けられていないタイマが作成される。この際、nIDEvent パラメータは0を指定しておくことが望ましい。0以外の値が指定してある場合、hWnd≠NULLで指定したnIDEventと同一の値であると、そのタイマは置き換えられる。

• nIDEvent

  タイマの識別子となる0以外の値を指定する。hWnd パラメータで NULL を指定した場合、nIDEvent パラメータは無視される。
  hWnd パラメータで NULL 以外の値を指定し、hWnd パラメータで指定したウィンドウに、nIDEvent と同じ値のタイマが既に割り当てられている場合、新しいタイマは既存のタイマを置き換える。SetTimer() APIがタイマを置き換えた場合、そのタイマはリセットされる。

• uElapse

  タイムアウト値を、ミリ秒(ms)単位で指定する。

  もし、タイムアウト値としてUSER_TIMER_MINIMUM (0x0000000A)よりも小さな値を指定すると、USER_TIMER_MINIMUMが指定されたものとみなされる。また、タイムアウト値としてUSER_TIMER_MAXIMUM (0x7FFFFFFF)より大きな値を指定すると、USER_TIMER_MAXIMUMが指定されたものとみなされる。

• lpTimerFunc

  タイムアウトが発生したときに呼び出されるTIMERPROC型の関数を指定する。ここにNULLを指定すると、関連付けられたウィンドウのWM_TIMERメッセージが呼び出される。この時、このとき、メッセージ内の MSG 構造体の hwnd メンバに、この関数の hWnd パラメータで指定したハンドルが格納され、wParamにnIDEventで指定した識別値が格納される。

戻り値

hWndにNULLを指定して関数が成功すると、新しいタイマの識別子を表す整数が返される。タイマを破棄するためにKillTimer() APIを呼び出すときに、この値を渡す。
hWndにNULL以外を指定して関数が成功すると、0以外の値が返される。タイマを破棄するためにKillTimer() APIを呼び出すときは、nIDEventに指定した値を渡す。
関数がタイマの作成に失敗すると、0 が返る。拡張エラー情報を取得するには、GetLastError 関数を使用する。

解説

アプリケーションは、ウィンドウプロシージャにWM_TIMERメッセージを処理するcase文を含めるか、タイマ作成時にTimerProcコールバック関数を指定する。

TimerProcコールバック関数を指定した場合も、デフォルトのウィンドウプロシージャがWM_TIMERを処理する動きによりコールバック関数を呼び出す仕組みになっている。従って、WM_TIMERでなくTimerProcを使用する場合であっても、呼び出しスレッドではメッセージのディスパッチ処理を記述すること。

WM_TIMER メッセージの wParam パラメータには、この関数の nIDEvent パラメータで指定した値が格納される。

タイマの識別子である nIDEvent は、関連付けられているウィンドウに特有のものとなる。ウィンドウが異なれば、各ウィンドウに関連付けられているタイマに同じ識別子を割り当てても構わない。それらのタイマは個別のものを意味することになる。

SetTimerは、hWndがNULLの場合にタイマーIDを再利用できる。