Handler
A Handler
function is a function that a service process specifies as the control handling
function of a particular service. The function can have any application-defined
name.
VOID WINAPI Handler(
|
DWORD fdwControl |
// requested
control code |
|
); |
|
Parameters
fdwControl
Indicates the
requested control code. This value can be one of the standard control codes in
the table, or it can be a user-defined control code in the range of 128 to 255,
inclusive. For user-defined control codes, the service defines the action
associated with the control code.
|
Value |
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 immediately report 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.
Due to extremely limited time available for shutdown, this control should
only be used by services that absolutely need to shut down for
instance, when the eventlog service needs to clear a dirty bit in the files
that it maintains, or when the server service needs to shut down so that
network connections aren t made when the system is in the shutdown state. If the
service takes time to shut down, and sends out STOP_PENDING status messages,
it is highly recommended that these messages include a waithint so that the
service controller will know how long to wait before indicating to the system
that service shutdown is complete. The system gives the service control
manager a limited amount of time (about 20 seconds) to complete service
shutdown, after which time system shutdown proceeds regardless of whether
service shutdown is complete. |
|
Return Values
This function
does not return a value.
Remarks
When a Win32
service is started, its ServiceMain function should immediately call the
RegisterServiceCtrlHandler function to specify a Handler function
to handle control requests.
Whenever it
receives a control request from the service control manager, the control
dispatcher in the main thread of a Win32 service process invokes the control
handler function for the specified service. After handling the control request,
the control handler must call the SetServiceStatus function to report
its current status to the service control manager.
See Also