| Platform SDK: DLLs, Processes, and Threads |
A Handler function is an application-defined callback function used with the RegisterServiceCtrlHandler function. A service program uses it as the control handler function of a particular service. The LPHANDLER_FUNCTION type defines a pointer to this function. Handler is a placeholder for the application-defined name.
This function has been superseded by the HandlerEx control handler function used with the RegisterServiceCtrlHandlerEx function. A service can use either control handler, but the new control handler supports user-defined context data and additional extended control codes.
VOID WINAPI Handler( DWORD fdwControl // requested control code );
| Control code | 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.
For more information, see Remarks. |
| SERVICE_CONTROL_PARAMCHANGE | Windows 2000: Notifies the service that service-specific startup parameters have changed. The service should reread its startup parameters. |
| SERVICE_CONTROL_NETBINDADD | Windows 2000: Notifies a network service that there is a new component for binding. The service should bind to the new component. |
| SERVICE_CONTROL_NETBINDREMOVE | Windows 2000: Notifies a network service that a component for binding has been removed. The service should reread its binding information and unbind from the removed component. |
| SERVICE_CONTROL_NETBINDENABLE | Windows 2000: Notifies a network service that a disabled binding has been enabled. The service should reread its binding information and add the new binding. |
| SERVICE_CONTROL_NETBINDDISABLE | Windows 2000: Notifies a network service that one of its bindings has been disabled. The service should reread its binding information and remove the binding. |
This value can also be a user-defined control code, as described in the following table.
| Control code | Meaning |
|---|---|
| Range 128 to 255. | The service defines the action associated with the control code. |
This function does not return a value.
When a 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 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 wait hint, so that the service controller knows how long to wait before reporting to the system that service shutdown is complete. For example, the server service needs to shut down so that network connections are not made when the system is in the shutdown state.
Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in Winsvc.h; include Windows.h.
Services Overview, Service Functions, HandlerEx, RegisterServiceCtrlHandler, ServiceMain, SetServiceStatus