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(
|
DWORD fdwControl |
// requested control code |
|
); |
|
Value |
Meaning |
|
SERVICE_CONTROL_STOP |
Requests the service to stop. |
|
SERVICE_CONTROL_PAUSE |
Requests the service to pause. |
|
SERVICE_CONTROL_ |
Requests the paused service to resume. |
|
SERVICE_CONTROL_ |
Requests the service to update immediately its current status information to the service control manager. |
|
SERVICE_CONTROL_ |
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. |
This function does not return a value.
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.