3.1.4.8 RSetServiceStatus (Opnum 7)

  • Article

The RSetServiceStatus method updates the SCM status information for the calling service.

 DWORD RSetServiceStatus(
   [in] SC_RPC_HANDLE hServiceStatus,
   [in] LPSERVICE_STATUS lpServiceStatus
 );

hServiceStatus: 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. The SERVICE_SET_STATUS access right MUST have been granted to the caller when the RPC context handle was created.

lpServiceStatus: Pointer to the SERVICE_STATUS (section 2.2.47) structure that contains the latest status information for 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

6

ERROR_INVALID_HANDLE

Either the handle is no longer valid or the SERVICE_SET_STATUS access rights had not been granted to the caller when the RPC context handle was created.

13

ERROR_INVALID_DATA

The data provided in the lpServiceStatus parameter is invalid.

The server MUST return ERROR_INVALID_DATA (13) if the following conditions are not true:

  • lpServiceStatus->dwCurrentState MUST be one of the following values:

    • SERVICE_STOPPED

    • SERVICE_START_PENDING

    • SERVICE_STOP_PENDING

    • SERVICE_RUNNING

    • SERVICE_CONTINUE_PENDING

    • SERVICE_PAUSE_PENDING

    • SERVICE_PAUSED

  • Only one of the following bits can be set if the SERVICE_INTERACTIVE_PROCESS bit is set in lpServiceStatus->dwServiceType:

    • SERVICE_WIN32_OWN_PROCESS

    • SERVICE_WIN32_SHARE_PROCESS

    • SERVICE_WIN32

  • Only one of the following bits can be set if the SERVICE_INTERACTIVE_PROCESS bit is not set in lpServiceStatus->dwServiceType:

    • SERVICE_DRIVER

    • SERVICE_WIN32

    • SERVICE_WIN32_OWN_PROCESS

    • SERVICE_WIN32_SHARE_PROCESS

  • If any bits other than these are set in lpServiceStatus->dwControlsAccepted:

    • SERVICE_ACCEPT_STOP

    • SERVICE_ACCEPT_PAUSE_CONTINUE

    • SERVICE_ACCEPT_SHUTDOWN

    • SERVICE_ACCEPT_PRESHUTDOWN

    • SERVICE_ACCEPT_PARAMCHANGE

    • SERVICE_ACCEPT_HARDWAREPROFILECHANGE

    • SERVICE_ACCEPT_NETBINDCHANGE

    • SERVICE_ACCEPT_POWEREVENT

    • SERVICE_ACCEPT_SESSIONCHANGE

In response to this request from the service, for a successful operation the server MUST update the ServiceStatus with the status specified by the service in the lpServiceStatus parameter in the service record identified by the hServiceStatus parameter of the client request.

In response to this request from the service, for a successful operation the server MUST transition the service for the service record identified by the hService parameter to a new state if the current value of ServiceStatus.dwCurrentState in the service record ServiceState is different from lpServiceStatus->dwCurrentState (section 3.1.1).