ChangeServiceConfig2 function

ChangeServiceConfig2 function

 

Changes the optional configuration parameters of a service.

Syntax

C++

 

BOOL WINAPI ChangeServiceConfig2(
  _In_     SC_HANDLE hService,
  _In_     DWORD     dwInfoLevel,
  _In_opt_ LPVOID    lpInfo
);

Parameters

hService [in]

A handle to the service. This handle is returned by the OpenService or CreateService function and must have the SERVICE_CHANGE_CONFIG access right. For more information, see Service Security and Access Rights.

If the service controller handles the SC_ACTION_RESTART action, hService must have the SERVICE_START access right.

dwInfoLevel [in]

The configuration information to be changed. This parameter can be one of the following values.

Value	Meaning
SERVICE_CONFIG_DELAYED_AUTO_START_INFO 3	The lpInfo parameter is a pointer to a SERVICE_DELAYED_AUTO_START_INFO structure. Windows Server 2003 and Windows XP:  This value is not supported.
SERVICE_CONFIG_DESCRIPTION 1	The lpInfo parameter is a pointer to a SERVICE_DESCRIPTION structure.
SERVICE_CONFIG_FAILURE_ACTIONS 2	The lpInfo parameter is a pointer to a SERVICE_FAILURE_ACTIONS structure. If the service controller handles the SC_ACTION_REBOOT action, the caller must have the SE_SHUTDOWN_NAMEprivilege. For more information, see Running with Special Privileges.
SERVICE_CONFIG_FAILURE_ACTIONS_FLAG 4	The lpInfo parameter is a pointer to a SERVICE_FAILURE_ACTIONS_FLAG structure. Windows Server 2003 and Windows XP:  This value is not supported.
SERVICE_CONFIG_PREFERRED_NODE 9	The lpInfo parameter is a pointer to a SERVICE_PREFERRED_NODE_INFO structure. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:  This value is not supported.
SERVICE_CONFIG_PRESHUTDOWN_INFO 7	The lpInfo parameter is a pointer to a SERVICE_PRESHUTDOWN_INFO structure. Windows Server 2003 and Windows XP:  This value is not supported.
SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO 6	The lpInfo parameter is a pointer to a SERVICE_REQUIRED_PRIVILEGES_INFO structure. Windows Server 2003 and Windows XP:  This value is not supported.
SERVICE_CONFIG_SERVICE_SID_INFO 5	The lpInfo parameter is a pointer to a SERVICE_SID_INFO structure.
SERVICE_CONFIG_TRIGGER_INFO 8	The lpInfo parameter is a pointer to a SERVICE_TRIGGER_INFO structure. This value is not supported by the ANSI version of ChangeServiceConfig2. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:  This value is not supported until Windows Server 2008 R2.
SERVICE_CONFIG_LAUNCH_PROTECTED 12	The lpInfo parameter is a pointer a SERVICE_LAUNCH_PROTECTED_INFO structure. Note  This value is supported starting with Windows 8.1.

lpInfo [in, optional]

A pointer to the new value to be set for the configuration information. The format of this data depends on the value of the dwInfoLevel parameter. If this value is NULL, the information remains unchanged.

Return value

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.

Remarks

The ChangeServiceConfig2 function changes the optional configuration information for the specified service in the service control manager database. You can obtain the current optional configuration information by using the QueryServiceConfig2 function.

You cannot set the SERVICE_CONFIG_FAILURE_ACTIONS value for a service that shares the service control manager's process. This includes all services whose executable image is "Services.exe".

You can change and query additional configuration information using the ChangeServiceConfig and QueryServiceConfig functions, respectively.

If a service is configured to restart after it finishes with an error, the service control manager queues the restart action to occur after the specified time delay. A queued restart action cannot be canceled. If the service is manually restarted and then stopped before the queued restart action occurs, the service will restart unexpectedly when the time delay elapses. The service must be explicitly disabled to prevent it from restarting.

The SERVICE_CONFIG_LAUNCH_PROTECTED value can be used to launch the service as protected. In order to launch the service as protected, the service must be signed with a special certificate.

SERVICE_CONFIG_LAUNCH_PROTECTED example:

C++

 

SERVICE_LAUNCH_PROTECTED_INFO Info;
SC_HANDLE hService;

Info.dwLaunchProtected = SERVICE_LAUNCH_PROTECTED_ANTIMALWARE_LIGHT;

hService = CreateService (...);

if (ChangeServiceConfig2(hService,
                        SERVICE_CONFIG_LAUNCH_PROTECTED,
                        &Info) == FALSE)
{
    Result = GetLastError();
}

Examples

For an example, see Changing a Service's Configuration.

Requirements

Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Header	Winsvc.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll
Unicode and ANSI names	ChangeServiceConfig2W (Unicode) and ChangeServiceConfig2A (ANSI)

See also

ChangeServiceConfig

CreateService

OpenService

QueryServiceConfig

QueryServiceConfig2

QueryServiceDynamicInformation

Service Configuration

Service Functions

SERVICE_DELAYED_AUTO_START_INFO

SERVICE_DESCRIPTION

SERVICE_FAILURE_ACTIONS

SERVICE_FAILURE_ACTIONS_FLAG

SERVICE_PRESHUTDOWN_INFO

SERVICE_REQUIRED_PRIVILEGES_INFO

SERVICE_SID_INFO