3.1.4.47 RControlServiceExW (Opnum 51)

  • Article

The RControlServiceExW method<80> receives a control code for a specific service.

 DWORD RControlServiceExW(
   [in] SC_RPC_HANDLE hService,
   [in] DWORD dwControl,
   [in] DWORD dwInfoLevel,
   [in, switch_is(dwInfoLevel)] PSC_RPC_SERVICE_CONTROL_IN_PARAMSW pControlInParams,
   [out, switch_is(dwInfoLevel)] PSC_RPC_SERVICE_CONTROL_OUT_PARAMSW pControlOutParams
 );

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_STOP

0x00000001

Notifies a service to 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.

SERVICE_CONTROL_PAUSE

0x00000002

Notifies a service to 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_CONTINUE

0x00000003

Notifies a paused service to 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 to 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_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_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_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_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_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.

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

dwInfoLevel: The information level for the service control parameters. This MUST be set to 0x00000001.

pControlInParams: A pointer to a SERVICE_CONTROL_STATUS_REASON_IN_PARAMSW (section 2.2.31) structure that contains the reason associated with the SERVICE_CONTROL_STOP control.

pControlOutParams: A pointer to a buffer that contains a SERVICE_CONTROL_STATUS_REASON_OUT_PARAMS (section 2.2.32) structure to receive the current status on the service.

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

Return value/code

Description

0x00000005

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.

0x00000006

ERROR_INVALID_HANDLE

The handle is no longer valid.

0x00000087

ERROR_INVALID_PARAMETER

The requested control code is undefined.

0x00000124

ERROR_INVALID_LEVEL

The dwInfoLevel parameter contains an unsupported level.

0x00001051

ERROR_DEPENDENT_SERVICES_RUNNING

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

0x00001052

ERROR_INVALID_SERVICE_CONTROL

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

0x00001053

ERROR_SERVICE_REQUEST_TIMEOUT

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

0x00001061

ERROR_SERVICE_CANNOT_ACCEPT_CTRL

The requested control code cannot be sent to the service because the state of the service is SERVICE_START_PENDING or SERVICE_STOP_PENDING.

0x00001062

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 Operating System 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 SCM MUST return the current status of the service by setting pControlOutParams after the operation.

The server MUST return the services last known state if dwControl is SERVICE_CONTROL_INTERROGATE and the service is in START_PENDING state.

The server MUST provide information in pControlOutParams.

If dwControl is not equal to SERVICE_CONTROL_STOP, pControlInParams->pszComment MUST be NULL. If not, the server MUST fail the call and return ERROR_INVALID_PARAMETER (87).