Share via

3.1.4.2 RControlService (Opnum 1)

  • Article

The RControlService method receives a control code for a specific service handle, as specified by the client.

 DWORD RControlService(
   [in] SC_RPC_HANDLE hService,
   [in] DWORD dwControl,
   [out] LPSERVICE_STATUS lpServiceStatus
 );

hService: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the service record that MUST have been created previously using one of the open methods specified in section 3.1.4.

dwControl: Requested control code. MUST be one of the following values.

Value

Meaning

SERVICE_CONTROL_CONTINUE

0x00000003

Notifies a paused service that it SHOULD resume. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_PAUSE_CONTINUE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_INTERROGATE

0x00000004

Notifies a service that it SHOULD report its current status information to the SCM. The SERVICE_INTERROGATE access right MUST have been granted to the caller when the RPC control handle to the service record was created.

SERVICE_CONTROL_NETBINDADD

0x00000007

Notifies a service that there is a new component for binding. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_NETBINDCHANGE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_NETBINDDISABLE

0x0000000A

Notifies a network service that one of its bindings has been disabled. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_NETBINDCHANGE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_NETBINDENABLE

0x00000009

Notifies a network service that a disabled binding has been enabled. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_NETBINDCHANGE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_NETBINDREMOVE

0x00000008

Notifies a network service that a component for binding has been removed. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_NETBINDCHANGE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_PARAMCHANGE

0x00000006

Notifies a service that its startup parameters have changed. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_PARAMCHANGE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_PAUSE

0x00000002

Notifies a service that it SHOULD pause. The SERVICE_PAUSE_CONTINUE access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_PAUSE_CONTINUE bit set in the ServiceStatus.dwControlsAccepted field of the service record.

SERVICE_CONTROL_STOP

0x00000001

Notifies a service that it SHOULD stop. The SERVICE_STOP access right MUST have been granted to the caller when the RPC control handle to the service record was created. The service record MUST have the SERVICE_ACCEPT_STOP bit set in the ServiceStatus.dwControlsAccepted field of the service record.

Services can define their own codes in the range 128-255.

lpServiceStatus: Pointer to a SERVICE_STATUS (section 2.2.47) structure that receives the latest service status information. The returned information reflects the most recent status that the service reported to the SCM.

Return Values: The method returns 0x00000000 (ERROR_SUCCESS) on success; otherwise, it returns one of the following error codes.

Return value/code

Description

5

ERROR_ACCESS_DENIED

The required access right had not been granted to the caller when the RPC context handle to the service record was created.

1051

ERROR_DEPENDENT_SERVICES_RUNNING

The service cannot be stopped because other running services are dependent on it.

6

ERROR_INVALID_HANDLE

The handle is no longer valid.

87

ERROR_INVALID_PARAMETER

The requested control code is undefined

1052

ERROR_INVALID_SERVICE_CONTROL

The requested control code is not valid, or it is unacceptable to the service.

1053

ERROR_SERVICE_REQUEST_TIMEOUT

The process for the service was started, but it did not respond within an implementation-specific time-out.<35>

1061

ERROR_SERVICE_CANNOT_ACCEPT_CTRL

The requested control code cannot be sent to the service because the ServiceStatus.dwCurrentState in the service record is SERVICE_START_PENDING or SERVICE_STOP_PENDING.

1062

ERROR_SERVICE_NOT_ACTIVE

The service has not been started, or the ServiceStatus.dwCurrentState in the service record is SERVICE_STOPPED.

1115

ERROR_SHUTDOWN_IN_PROGRESS

The system is shutting down.

In response to this request from the client, for a successful operation, the SCM MUST send the control specified in the dwControl parameter to the service created for the service record identified by the hService parameter of the client request if the type of the service record is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS.

If the type of the service record is SERVICE_KERNEL_DRIVER or SERVICE_FILESYSTEM_DRIVER, and dwControl parameter is not SERVICE_CONTROL_INTERROGATE or SERVICE_CONTROL_STOP, the SCM MUST fail the request with ERROR_INVALID_SERVICE_CONTROL.

If the type of the service record is SERVICE_KERNEL_DRIVER or SERVICE_FILESYSTEM_DRIVER, the SCM MUST query the current status of the driver from the IO manager and set the ServiceStatus.dwCurrentState of the service record to SERVICE_RUNNING if driver is loaded and SERVICE_STOPPED if it is not.

If the dwControl is not SERVICE_CONTROL_INTERROGATE and type of the service record is SERVICE_KERNEL_DRIVER or SERVICE_FILESYSTEM_DRIVER and the driver is managed by the PnP subsystem, the SCM MUST fail the request with ERROR_INVALID_SERVICE_CONTROL.

If the ServiceStatus.dwControlsAccepted field of the service record does not have a required SERVICE_ACCEPT_xxx bit set, the SCM MUST fail the request with ERROR_INVALID_SERVICE_CONTROL.

In response to this request from the client, for a successful operation the server MUST set the ServiceStatus from the service record identified by the hService parameter of the request in the lpServiceStatus parameter.

The server SHOULD fill in the lpServiceStatus structure only when RControlService returns one of the following error codes: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL, ERROR_DEPENDENT_SERVICES_RUNNING, or ERROR_SERVICE_NOT_ACTIVE.