HandlerEx

HandlerEx

A HandlerEx function is an application-defined callback function used with the RegisterServiceCtrlHandlerEx function. A service program can use it as the control handler function of a particular service.

The LPHANDLER_FUNCTION_EX type defines a pointer to this function. HandlerEx is a placeholder for the application-defined name.

This function supersedes the Handler control handler function used with the RegisterServiceCtrlHandler function. A service can use either control handler, but the new control handler supports user-defined context data and additional extended control codes.

DWORD WINAPI HandlerEx(
  DWORD dwControl,
  DWORD dwEventType,
  LPVOID lpEventData,
  LPVOID lpContext
);

Parameters

dwControl

[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 to 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. Applications should use Plug and Play functionality instead.
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. Applications should use Plug and Play functionality instead.
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. Applications should use Plug and Play functionality instead.
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. Applications should use Plug and Play functionality instead.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifies a service that service-specific startup parameters have changed. The service should reread its startup parameters.
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 the Remarks section of this topic.
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 one of the following extended control codes. Note that these control codes are not supported by the Handler function.

Control Code	Meaning
SERVICE_CONTROL_DEVICEEVENT 0x0000000B	Notifies a service of device events. (The service must have registered to receive these notifications using the RegisterDeviceNotification function.)
SERVICE_CONTROL_HARDWAREPROFILECHANGE 0x0000000C	Notifies a service that the computer's hardware profile has changed.
SERVICE_CONTROL_POWEREVENT 0x0000000D	Notifies a service of system power events.
SERVICE_CONTROL_SESSIONCHANGE 0x0000000E	Notifies a service of session change events. Windows 2000:  This value is not supported.

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.

dwEventType

[in] Type of event that has occurred. This parameter is used if dwControl is SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT, or SERVICE_CONTROL_SESSIONCHANGE. Otherwise, it is zero.

If dwControl is SERVICE_CONTROL_DEVICEEVENT, this parameter can be one of the following values:

• DBT_DEVICEARRIVAL
• DBT_DEVICEREMOVECOMPLETE
• DBT_DEVICEQUERYREMOVE
• DBT_DEVICEQUERYREMOVEFAILED
• DBT_DEVICEREMOVEPENDING
• DBT_CUSTOMEVENT

If dwControl is SERVICE_CONTROL_HARDWAREPROFILECHANGE, this parameter can be one of the following values:

• DBT_CONFIGCHANGED
• DBT_QUERYCHANGECONFIG
• DBT_CONFIGCHANGECANCELED

If dwControl is SERVICE_CONTROL_POWEREVENT, this parameter can be one of the values specified in the wParam parameter of the WM_POWERBROADCAST message.

If dwControl is SERVICE_CONTROL_SESSIONCHANGE, this parameter can be one of the values specified in the wParam parameter of the WM_WTSSESSION_CHANGE message.

lpEventData

[in] Additional device information, if required. The format of this data depends on the value of the dwControl and dwEventType parameters. If dwEventType is SERVICE_CONTROL_DEVICEEVENT, this data corresponds to the lParam parameter that applications receive as part of a WM_DEVICECHANGE message. If dwEventType is SERVICE_CONTROL_POWEREVENT, this data corresponds to the lParam parameter that applications receive as part of a WM_POWERBROADCAST message. If dwEventType is SERVICE_CONTROL_SESSIONCHANGE, this parameter is a WTSSESSION_NOTIFICATION structure.

lpContext

[in] User-defined data passed from RegisterServiceCtrlHandlerEx. When multiple services share a process, the lpContext parameter can help identify the service.

Return Values

The return value for this function depends on the control code received. The following list identifies the rules for this return value:

• If your service does not handle the control, return ERROR_CALL_NOT_IMPLEMENTED.
• If your service handles SERVICE_CONTROL_DEVICEEVENT, return NO_ERROR to grant the request and an error code to deny the request.
• If your service handles SERVICE_CONTROL_HARDWAREPROFILECHANGE, return NO_ERROR to grant the request and an error code to deny the request.
• If your service handles SERVICE_CONTROL_POWEREVENT, return NO_ERROR to grant the request and an error code to deny the request.
• For all other control codes your service handles, return NO_ERROR.

Remarks

When a service is started, its ServiceMain function should immediately call the RegisterServiceCtrlHandlerEx function to specify a HandlerEx function to process control requests. To specify the control codes to be accepted, use the SetServiceStatus and RegisterDeviceNotification functions.

The control dispatcher in the main thread of a service 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 SetServiceStatus 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 waits. To change this time limit, modify the WaitToKillServiceTimeout value in the following registry key:

HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Control

Be sure to handle Plug and Play device events as quickly as possible; otherwise, the system may become unresponsive. If your event handler is to perform an operation that may block execution (such as I/O), it is best to start another thread to perform the operation asynchronously.

Requirements

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