The ChangeServiceConfig function changes the configuration parameters of a service.
BOOL ChangeServiceConfig(
| SC_HANDLE hService, | // handle to service |
| DWORD dwServiceType, | // type of service |
| DWORD dwStartType, | // when to start service |
| DWORD dwErrorControl, | // severity if service fails to start |
| LPCTSTR lpBinaryPathName, | // pointer to service binary file name |
| LPCTSTR lpLoadOrderGroup, | // pointer to load ordering group name |
| LPDWORD lpdwTagId, | // pointer to variable to get tag identifier |
| LPCTSTR lpDependencies, | // pointer to array of dependency names |
| LPCTSTR lpServiceStartName, | // pointer to account name of service |
| LPCTSTR lpPassword, | // pointer to password for service account |
| LPCTSTR lpDisplayName | // pointer to display name |
| ); |
Parameters
hService
Identifies the service. This handle is returned by the OpenService or CreateService function and must have SERVICE_CHANGE_CONFIG access.
dwServiceType
A set of bit flags that specify the type of service. Specify SERVICE_NO_CHANGE if you are not changing the existing service type; otherwise, specify one of the following service type flags to indicate the service type. In addition, if you specify either of the SERVICE_WIN32 flags, you can also specify the SERVICE_INTERACTIVE_PROCESS flag to enable the service process to interact with the desktop.
| Value | Meaning |
| SERVICE_WIN32_OWN_PROCESS | A service type flag that specifies a Win32 service that runs in its own process. |
| SERVICE_WIN32_SHARE_PROCESS | A service type flag that specifies a Win32 service that shares a process with other services. |
| SERVICE_KERNEL_DRIVER | A service type flag that specifies a Windows NT device driver. |
| SERVICE_FILE_SYSTEM_DRIVER | A service type flag that specifies a Windows NT file system driver. |
| SERVICE_INTERACTIVE_PROCESS | A flag that enables a Win32 service process to interact with the desktop. |
dwStartType
Specifies when to start the service. This value can be the service type SERVICE_NO_CHANGE if the existing start type is not modified, or one of the following values can be specified:
| Value | Meaning |
| SERVICE_BOOT_START | Specifies a device driver started by the operating system loader. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER. |
| SERVICE_SYSTEM_START | Specifies a device driver started by the IoInitSystem function. This value is valid only if the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER. |
| SERVICE_AUTO_START | Specifies a device driver or Win32 service started by the service control manager automatically during system startup. |
| SERVICE_DEMAND_START | Specifies a device driver or Win32 service started by the service control manager when a process calls the StartService function. |
| SERVICE_DISABLED | Specifies a device driver or Win32 service that can no longer be started. |
dwErrorControl
Specifies the severity of the error if this service fails to start during startup, and determines the action taken by the startup program if failure occurs. One of the following values can be specified:
| Value | Meaning |
| SERVICE_ERROR_IGNORE | The startup (boot) program logs the error but continues the startup operation. |
| SERVICE_ERROR_NORMAL | The startup program logs the error and puts up a message box pop-up but continues the startup operation. |
| SERVICE_ERROR_SEVERE | The startup program 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 | The startup program logs 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 | The existing StartType value is not to be changed. |
lpBinaryPathName
Pointer to a null-terminated string that contains the fully qualified path to the service binary file. If the pointer is NULL, the path is not modified.
lpLoadOrderGroup
Pointer to a null-terminated string that names the load ordering group of which this service is a member. If the pointer is NULL, the group is not modified. If it points to an empty string, the service does not belong to a group.
The registry has a list of load ordering groups located at
HKEY_LOCAL_MACHINES\System\CurrentControlSet
\Control\ServiceGroupOrder.
The startup program uses this list to load groups of services in a specified order with respect to the other groups in the list. You can place a service in a group so that another service can depend on the group.
The order in which a service starts is determined by the following criteria:
1.The order of groups in the registry's load-ordering group list. Services in groups in the load-ordering group list are started first, followed by services in groups not in the load-ordering group list, and then services that do not belong to a group.
2.The service's dependencies listed in the lpDependencies parameter and the dependencies of other services dependent on the service.
lpdwTagId
Pointer to a 32-bit variable that receives a unique tag value for this service in the group specified in the lpLoadOrderGroup parameter. If no tag is requested, this parameter can be NULL.
You can use a tag for ordering service startup within a load ordering group by specifying a tag order vector in the registry located at
HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Control\GroupOrderList.
Tags are only evaluated for SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER type services that have SERVICE_BOOT_START or SERVICE_SYSTEM_START start types.
lpDependencies
Pointer to an array of null-separated names of services or load ordering groups that must start before this service. The array is double null-terminated. If the pointer is NULL, the dependencies are not modified. If it points to an empty string, the service has no dependencies. If a group name is specified, it must be prefixed by the SC_GROUP_IDENTIFIER character (defined in the WINSVC.H files) to differentiate it from a service name, because services and service groups share the same name space. 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.
lpServiceStartName
Pointer to a null-terminated string. If NULL is specified, the name is not modified. If the service type is SERVICE_WIN32_OWN_PROCESS, this name is the account name in the form of "DomainName\Username", which the service process will be logged on as when it runs. If the account belongs to the built-in domain, ".\Username" can be specified. Services of type SERVICE_WIN32_SHARE_PROCESS are not allowed to specify an account other than LocalSystem.
If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this name is the Windows NT driver object name (that is, \FileSystem\Rdr or \Driver\Xns), which the input and output (I/O) system uses to load the device driver. If NULL is specified, the driver is run with a default object name created by the I/O system, based on the service name.
lpPassword
Pointer to a null-terminated string that contains the password to the account name specified by the lpServiceStartName parameter if the service type is SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS. If the pointer is NULL, the password is not modified. If it points to an empty string, the service has no password. If the service type is SERVICE_KERNEL_DRIVER or SERVICE_FILE_SYSTEM_DRIVER, this parameter is ignored.
lpDisplayName
Pointer to a null-terminated string that is to be used by user interface programs to identify the service. This string has a maximum length of 256 characters. The name is case-preserved in the Service Control Manager. Display name comparisons are always case-insensitive.
Return Values
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Errors
The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.
| Value | Meaning | ||||||||||||||||||||||
| ERROR_ACCESS_DENIED | |||||||||||||||||||||||
| The specified handle was not opened with SERVICE_CHANGE_CONFIG access. | |||||||||||||||||||||||
| ERROR_CIRCULAR_DEPENDENCY | |||||||||||||||||||||||
| A circular service dependency was specified. | |||||||||||||||||||||||
| ERROR_DUP_NAME | |||||||||||||||||||||||
| The display name already exists in the service controller's database, either as a service name or as another display name. | |||||||||||||||||||||||
| ERROR_INVALID_HANDLE | |||||||||||||||||||||||
| The specified handle is invalid. | |||||||||||||||||||||||
| ERROR_INVALID_PARAMETER | |||||||||||||||||||||||
| A parameter that was specified is invalid. | |||||||||||||||||||||||
| ERROR_INVALID_SERVICE_ACCOUNT | |||||||||||||||||||||||
| The account name does not exist, or a service is specified to share the same binary file as an already installed service but with an account name that is not the same as the installed service. | |||||||||||||||||||||||
| ERROR_SERVICE_MARKED_FOR_DELETE | |||||||||||||||||||||||
| The service has been marked for deletion. | |||||||||||||||||||||||
Remarks
The ChangeServiceConfig function changes the configuration information for the specified service in the service control manager database. This configuration information is initially specified by the CreateService function and can be queried (except for the password parameter) by using the QueryServiceConfig function.
Any of the configuration parameters specified for this function can be left unchanged by specifying NULL for a string parameter or SERVICE_NO_CHANGE for a doubleword parameter.
If the configuration is changed for a service that is running, with the exception of lpDisplayName, the changes do not take effect until the service is stopped.
See Also
CreateService, OpenService, QueryServiceConfig, StartService