Handler

A Handler function is a function that a service process specifies as the control handling function of a particular service. The function can have any application-defined name.

VOID WINAPI Handler(

DWORD fdwControl // requested control code
);  

Parameters

fdwControl

Indicates the requested control code. This value can be one of the standard control codes in the table, or it can be a user-defined control code in the range of 128 to 255, inclusive. For user-defined control codes, the service defines the action associated with the control code.

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 immediately report 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. Due to extremely limited time available for shutdown, this control should only be used by services that absolutely need to shut down ¾ for instance, when the eventlog service needs to clear a dirty bit in the files that it maintains, or when the server service needs to shut down so that network connections aren't made when the system is in the shutdown state.

If the service takes time to shut down, and sends out STOP_PENDING status messages, it is highly recommended that these messages include a waithint so that the service controller will know how long to wait before indicating to the system that service shutdown is complete. The system gives the service control manager a limited amount of time (about 20 seconds) to complete service shutdown, after which time system shutdown proceeds regardless of whether service shutdown is complete.


Return Values

This function does not return a value.

Remarks

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

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

See Also

RegisterServiceCtrlHandler, ServiceMain, SetServiceStatus