Handler info  Overview  Group

A Handler function is a function that a service program specifies as the control handler function of a particular Win32-based service. Handler is a placeholder for the application-defined name.

VOID WINAPI Handler(

Parameters

fdwControl

Specifies the requested control code. This value can be one of the standard control codes in the following table:

Value	Meaning
SERVICE_CONTROL_STOP	Requests the service to stop.
SERVICE_CONTROL_PAUSE	Requests the service to pause.
SERVICE_CONTROL_ CONTINUE	Requests the paused service to resume.
SERVICE_CONTROL_ INTERROGATE	Requests the service to update immediately its current status information to the service control manager.
SERVICE_CONTROL_ SHUTDOWN	Requests the service to perform cleanup tasks, because the system is shutting down.

This value can also be a user-defined control code, as described in the following table:

Value	Meaning
Range 128 to 255.	The service defines the action associated with the control code. The hService handle must have SERVICE_USER_DEFINED_CONTROL access.

Return Values

This function does not return a value.

Remarks

When a Win32-based service is started, its ServiceMain function should immediately call the RegisterServiceCtrlHandler function to specify a Handler function to process control requests.

The control dispatcher in the main thread of a Win32-based service process invokes the control handler function for the specified service whenever it receives a control request from the service control manager. After processing the control request, the control handler must call the SetServiceStatus function to report its current status to the service control manager.

The SERVICE_CONTROL_SHUTDOWN control should only be processed by services that must absolutely clean up during shutdown, because there is an extremely limited time (about 20 seconds) available for service shutdown. After this time expires, system shutdown proceeds regardless of whether service shutdown is complete. If the service needs to take more time to shut down, it should send out STOP_PENDING status messages, along with a waithint, so that the service controller knows how long to wait before reporting to the system that service shutdown is complete. For example, the eventlog service needs to clear a dirty bit in the files that it maintains, and the server service needs to shut down so that network connections aren’t made when the system is in the shutdown state.

See Also

RegisterServiceCtrlHandler, ServiceMain, SetServiceStatus

  .