3.1.4.22 RChangeServiceConfigA (Opnum 23)

  • Article

The RChangeServiceConfigA method changes a service's configuration parameters in the SCM database.

 DWORD RChangeServiceConfigA(
   [in] SC_RPC_HANDLE hService,
   [in] DWORD dwServiceType,
   [in] DWORD dwStartType,
   [in] DWORD dwErrorControl,
   [in, string, unique, range(0, SC_MAX_PATH_LENGTH)] 
     LPSTR lpBinaryPathName,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     LPSTR lpLoadOrderGroup,
   [in, out, unique] LPDWORD lpdwTagId,
   [in, unique, size_is(dwDependSize)] 
     LPBYTE lpDependencies,
   [in, range(0, SC_MAX_DEPEND_SIZE)] 
     DWORD dwDependSize,
   [in, string, unique, range(0, SC_MAX_ACCOUNT_NAME_LENGTH)] 
     LPSTR lpServiceStartName,
   [in, unique, size_is(dwPwSize)] 
     LPBYTE lpPassword,
   [in, range(0, SC_MAX_PWD_SIZE)] 
     DWORD dwPwSize,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     LPSTR lpDisplayName
 );

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

dwServiceType: A Type value for the service record (section 3.1.1) that specifies the type of service. This MUST be one of the following values.

Value

Meaning

SERVICE_KERNEL_DRIVER

0x00000001

A driver service. These are services that manage devices on the system.

SERVICE_FILE_SYSTEM_DRIVER

0x00000002

A file system driver service. These are services that manage file systems on the system.

SERVICE_WIN32_OWN_PROCESS

0x00000010

Service that runs in its own process.

SERVICE_WIN32_SHARE_PROCESS

0x00000020

Service that shares a process with other services.

SERVICE_NO_CHANGE

0xFFFFFFFF

Service type does not change.

The following flag can also be combined with the value passed in dwServiceType.

Value

Meaning

SERVICE_INTERACTIVE_PROCESS

0x00000100

The service can interact with the desktop.

dwStartType: A Start value for the service record (section 3.1.1) that specifies when to start the service. This MUST be one of the following values.

Value

Meaning

SERVICE_BOOT_START

0x00000000

Starts the driver service when the system boots up. This value is valid only for driver services.

SERVICE_SYSTEM_START

0x00000001

Starts the driver service when the system boots up. This value is valid only for driver services. The services marked SERVICE_SYSTEM_START are started after all SERVICE_BOOT_START services have been started.

SERVICE_AUTO_START

0x00000002

Starts the service automatically during system startup.

SERVICE_DEMAND_START

0x00000003

Starts the service when a client requests the SCM to start the service.

SERVICE_DISABLED

0x00000004

Service cannot be started.

SERVICE_NO_CHANGE

0xFFFFFFFF

Service start type does not change.

dwErrorControl: An ErrorControl value for the service record (section 3.1.1) that specifies the severity of the error if the service fails to start and determines the action that the SCM takes. This MUST be one of the following values.

Value

Meaning

SERVICE_ERROR_IGNORE

0x00000000

The SCM ignores the error and continues the startup operation.

SERVICE_ERROR_NORMAL

0x00000001

The SCM logs the error, but continues the startup operation.

SERVICE_ERROR_SEVERE

0x00000002

The SCM logs the error. If the last-known good configuration is being started, the startup operation continues. Otherwise, the system is restarted with the last-known good configuration.

SERVICE_ERROR_CRITICAL

0x00000003

The SCM SHOULD log the error if possible. If the last-known good configuration is being started, the startup operation fails. Otherwise, the system is restarted with the last-known good configuration.

SERVICE_NO_CHANGE

0xFFFFFFFF

Service error control type does not change.

lpBinaryPathName: An ImagePath value for the service record (section 3.1.1) as a pointer to a null-terminated ANSI string that contains the fully qualified path to the service binary file. The path MAY include arguments. If the path contains a space, it MUST be quoted so that it is correctly interpreted. For example, "d:\\my share\\myservice.exe" is specified as "\"d:\\my share\\myservice.exe\"".

lpLoadOrderGroup: A Group value for the service record (section 3.1.1) as a pointer to a null-terminated ANSI string that names the load ordering group of which this service is a member.

Specify NULL or an empty string if the service does not belong to a load-ordering group.

lpdwTagId: A Tag value for the service record (section 3.1.1) as a pointer to a variable that receives a tag value. The value is unique to the group specified in the lpLoadOrderGroup parameter.

lpDependencies: DependOnSize and DependOnGroup values for the service record (section 3.1.1) as a pointer to an array of null-separated names of services or load ordering groups that MUST start before this service. The array is doubly null-terminated. Load ordering group names are prefixed with a "+" character (to distinguish them from service names). If the pointer is NULL or if it points to an empty string, the service has no dependencies. Cyclic dependency between services is not allowed. The character set is ANSI. Dependency on a service means that this service can only run if the service it depends on is running. Dependency on a group means that this service can run if at least one member of the group is running after an attempt to start all members of the group.

dwDependSize: The size, in bytes, of the string specified by the lpDependencies parameter.

lpServiceStartName: An ObjectName value for the service record (section 3.1.1) as a pointer to a null-terminated ANSI string that specifies the name of the account under which the service runs.

lpPassword: A Password value for the service record (section 3.1.1) as a pointer to a null-terminated ANSI string that contains the password of the account whose name was specified by the lpServiceStartName parameter.

dwPwSize: The size, in bytes, of the password specified by the lpPassword parameter.

lpDisplayName: A DisplayName value for the service record (section 3.1.1) as a pointer to a null-terminated ANSI string that contains the display name that applications can use to identify the service for its users.

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 SERVICE_CHANGE_CONFIG access right had not been granted to the caller when the RPC context handle to the service record was created.

6

ERROR_INVALID_HANDLE

The handle specified is invalid.

87

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

1057

ERROR_INVALID_SERVICE_ACCOUNT

The user account name specified in the lpServiceStartName parameter does not exist.

1059

ERROR_CIRCULAR_DEPENDENCY

A circular service dependency was specified.

1078

ERROR_DUPLICATE_SERVICE_NAME

The lpDisplayName matches either the ServiceName or the DisplayName of another service record in the service control manager database.

1072

ERROR_SERVICE_MARKED_FOR_DELETE

The RDeleteService has been called for the service record identified by the hService parameter.

1115

ERROR_SHUTDOWN_IN_PROGRESS

The system is shutting down.

In response to this request from the client, for a successful operation the server MUST update, using the values from the appropriate parameters of the client request, the service record identified by the hService parameter in the SCM database:

  • If the client passes NULL for lpBinaryPathName, the server MUST keep the existing ImagePath value.

  • If the client passes NULL for lpLoadOrderGroup, the server MUST keep the existing ServiceGroup value.

  • If the client passes NULL for lpdwTagId, the server MUST keep the existing Tag value.

  • If the client passes NULL for lpDependencies, the server MUST keep the existing DependOnService and DependOnGroup values.

  • If the client passes NULL for lpServiceStartName, the server MUST keep the existing ObjectName value.

  • If the client passes NULL for lpPassword, the server MUST keep the existing Password value.

  • If the client passes NULL for lpDisplayName, the server MUST keep the existing DisplayName value.

If the original service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS, the server MUST fail the call if dwServiceType is set to SERVICE_FILE_SYSTEM_DRIVER or SERVICE_KERNEL_DRIVER.<44>

If dwServiceType is set to SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS combined with the SERVICE_INTERACTIVE_PROCESS bit and the ObjectName field of the service record is not equal to LocalSystem, the server MUST fail the request with ERROR_INVALID_PARAMETER.

If the service has a PreferredNode setting and the client requested a change in service type other than SERVICE_WIN32_OWN_PROCESS, the server MUST fail the call with ERROR_INVALID_PARAMETER (87).

If the service is a member of a load-order group and has a start type of delayed autostart (see section 2.2.33), then the server MUST fail the call with ERROR_INVALID_PARAMETER (87).

If lpdwTagId has a valid value and lpLoadOrderGroup is either NULL or an empty string, then the server MUST return ERROR_INVALID_PARAMETER.

The server MUST use the process described in Conversion Between ANSI and Unicode String Formats (section 3.1.7) to convert a string to the appropriate format.

For service record changes to apply to the running service, the service MUST be stopped and started back up, except in the case of lpDisplayName. Changes to lpDisplayName take effect immediately.

If lpBinaryPathName contains arguments, the server MUST pass these arguments to the service entry point.