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,     // requested control code
  DWORD dwEventType,   // event type
  LPVOID lpEventData,  // event data
  LPVOID lpContext     // user-defined context data
);

Parameters

dwControl

[in] The requested control code. This value can be one of the following control codes.

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 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	Windows 2000: Notifies the service of device events. The service must register to receive these notifications by using the RegisterDeviceNotification function.
SERVICE_CONTROL_HARDWAREPROFILECHANGE	Windows 2000: Notifies the service that the computer's hardware profile has changed.
SERVICE_CONTROL_POWEREVENT	Windows 2000: Notifies the service of system power events.

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.

dwEventType

[in] The type of event that has occurred. If dwControl is SERVICE_CONTROL_POWEREVENT, this parameter can be one of the values specified in the wParam value of the WM_POWERBROADCAST message.

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, or DBT_CUSTOMEVENT.

If dwControl is SERVICE_CONTROL_HARDWAREPROFILECHANGE, this parameter can be one of the following values: DBT_CONFIGCHANGED, DBT_QUERYCHANGECONFIG, or DBT_CONFIGCHANGECANCELED.

Otherwise, this parameter is zero.

lpEventData

[in] Additional device information, if required. The format of this data depends on the value of the dwControl and dwEventType parameters. This data corresponds to the lParam value that applications receive as part of a WM_DEVICECHANGE or WM_POWERBROADCAST message.

lpContext

[in] The 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 rules for this return value are as follows.

• 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.

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

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Winsvc.h; include Windows.h.

See Also

Services Overview, Service Functions, RegisterServiceCtrlHandlerEx, ServiceMain, SetServiceStatus