CreateWatchDogTimer (Windows Embedded CE 6.0)

1/6/2010

This function creates a watchdog timer.

Syntax

HANDLE CreateWatchDogTimer(
  LPCWSTR pszWatchDogName,
  DWORD dwPeriod,
  DWORD dwWait,
  DWORD dwDfltAction,
  DWORD dwParam,
  DWORD dwFlags
);

Parameters

• pszWatchDogName
  [in] Name of the watchdog timer to be created.

• dwPeriod
  [in] Watchdog period, in milliseconds.

• dwWait
  [in] Time to wait, in milliseconds, when the watchdog timer is not refreshed within the watchdog period before the default action is taken.

  This is useful when handling false alarms or saving important information before system reset.

• dwDfltAction
  [in] Default action to be taken when the watchdog timer is not refreshed within dwPeriod.

  The following table describes possible values.

  Value	Description
  WDOG_KILL_PROCESS	Terminate the process to be watched.
  WDOG_NO_DFLT_ACTION	Take no default action.
  WDOG_RESET_DEVICE	Reset the device .

• dwParam
  [in] Parameter to be passed to IOCTL_HAL_REBOOT.

  The OEM adaptation layer (OAL) uses this information to determine whether an immediate system reboot is needed, or to perform a delayed system reboot.

• dwFlags
  [in] Reserved; must be set to zero.

Return Value

A handle to the watchdog timer indicates success. NULL indicates failure.

The returned handle can be used in WaitForSingleObject or WaitForMultipleObjects, and is signaled when the watchdog is not refreshed within the specified watchdog period, dwPeriod. Use the CloseHandle function to release the memory used by the watchdog timer.

If a watchdog timer with the name specified by pszWatchDogName exists, a new handle is returned, and GetLastError returns ERROR_ALREADY_EXISTS. Although the handle returned does not have the same value as the first one, it still references the same underlying object.

Remarks

Watchdog timers are used to make sure critical processes are running as expected. Typically, every critical process creates a watchdog timer and refreshes it by calling the RefreshWatchDogTimer function from time to time to make sure that the watchdog is working correctly.

You can create a monitor process to wait on the watchdog handles to perform actions if the critical processes fail to signal the watchdog timers.

If the critical process fails to refresh its watchdog timer within the watchdog period specified by dwPeriod, the watchdog is signaled.

The monitor process, if it exists, has up to dwWait milliseconds to determine whether it is a false alarm, or save critical information before the default action is taken.

In case of a false alarm, the monitor process should refresh the watchdog to prevent the default action from being taken.

When the default action is taken, the watchdog is considered stopped. That is, the same watchdog timer is not signaled again until it is started again.

Requirements

See Also

Reference

Kernel Functions
OpenWatchDogTimer
StartWatchDogTimer
StopWatchDogTimer
RefreshWatchDogTimer

Concepts

Modified Kernel APIs
Kernel Mode APIs

Other Resources

IOCTL_HAL_REBOOT
WaitForSingleObject
WaitForMultipleObjects
CloseHandle
GetLastError