ChangeServiceConfig
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