Handler

Handler

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
);

Parameters

fdwControl

[in] Control code. This parameter can be one of the following values.

Control code	Meaning
SERVICE_CONTROL_CONTINUE 0x00000003	Notifies a paused service that it should resume.
SERVICE_CONTROL_INTERROGATE 0x00000004	Notifies a service that it should report its current status information to the service control manager.
SERVICE_CONTROL_NETBINDADD 0x00000007	Notifies a network service that there is a new component for binding. The service should bind to the new component. However, this control code has been deprecated; use Plug and Play functionality instead. Windows NT:  This value is not supported.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Notifies a network service that one of its bindings has been disabled. The service should reread its binding information and remove the binding. However, this control code has been deprecated; use Plug and Play functionality instead. Windows NT:  This value is not supported.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Notifies a network service that a disabled binding has been enabled. The service should reread its binding information and add the new binding. However, this control code has been deprecated; use Plug and Play functionality instead. Windows NT:  This value is not supported.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	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. However, this control code has been deprecated; use Plug and Play functionality instead. Windows NT:  This value is not supported.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifies a service that its startup parameters have changed. The service should reread its startup parameters. Windows NT:  This value is not supported.
SERVICE_CONTROL_PAUSE 0x00000002	Notifies a service that it should pause.
SERVICE_CONTROL_SHUTDOWN 0x00000005	Notifies a service that the system is shutting down so the service can perform cleanup tasks. For more information, see Remarks.
SERVICE_CONTROL_STOP 0x00000001	Notifies a service that it should stop. If a service accepts this control code, it must stop upon receipt. After the SCM sends this control code, it will not send other control codes. Windows XP/2000:  If the service returns NO_ERROR and continues to run, it continues to receive control codes. This behavior changed starting with Windows Server 2003 and Windows XP SP2.

This parameter 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.

Return Values

This function does not return a value.

Remarks

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.

When the service control manager sends a control code to a service, it waits for the handler function to return before sending additional control codes to other services. If the handler function does not return promptly, it may block other services from receiving control codes.

The SERVICE_CONTROL_SHUTDOWN control code should only be processed by services that must absolutely clean up during shutdown, because there is a limited time (about 20 seconds) available for service shutdown. After this time expires, system shutdown proceeds regardless of whether service shutdown is complete. Note that if the system is left in the shutdown state (not restarted or powered down), the service continues to run.

If the service needs more time to clean up, it should send STOP_PENDING status messages, along with a wait hint, so the service controller knows how long to wait before reporting to the system that service shutdown is complete. However, to prevent a service from stopping shutdown, there is a limit to how long the service controller will wait. To change this time limit, modify the WaitToKillServiceTimeout value in the following registry key:

HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Control

Example Code

For an example, see Writing a Control Handler Function.

Requirements

Client	Requires Windows XP, Windows 2000 Professional, or Windows NT Workstation.
Server	Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header	Declared in Winsvc.h; include Windows.h.