Функция ChangeServiceConfig2A (winsvc.h)

Статья
11/20/2024

Изменяет необязательные параметры конфигурации службы.

Синтаксис

BOOL ChangeServiceConfig2A(
  [in]           SC_HANDLE hService,
  [in]           DWORD     dwInfoLevel,
  [in, optional] LPVOID    lpInfo
);

Параметры

[in] hService

Дескриптор службы. Этот дескриптор возвращается функцией OpenService или CreateService и должен иметь право доступа SERVICE_CHANGE_CONFIG. Дополнительные сведения см. в службы безопасности и доступа.

Если контроллер службы обрабатывает действие SC_ACTION_RESTART, hService должны иметь право доступа SERVICE_START.

[in] dwInfoLevel

Сведения о конфигурации, которые необходимо изменить. Этот параметр может быть одним из следующих значений.

Ценность	Значение
SERVICE_CONFIG_DELAYED_AUTO_START_INFO 3	Параметр lpInfo — это указатель на структуру SERVICE_DELAYED_AUTO_START_INFO. Windows Server 2003 и Windows XP: это значение не поддерживается.
SERVICE_CONFIG_DESCRIPTION 1	Параметр lpInfo — это указатель на структуру SERVICE_DESCRIPTION.
SERVICE_CONFIG_FAILURE_ACTIONS 2	Параметр lpInfo — это указатель на структуру SERVICE_FAILURE_ACTIONS. Если контроллер службы обрабатывает действие SC_ACTION_REBOOT, вызывающий объект должен иметь SE_SHUTDOWN_NAME привилегии. Дополнительные сведения см. в разделе Выполнение с специальными привилегиями.
SERVICE_CONFIG_FAILURE_ACTIONS_FLAG 4	Параметр lpInfo является указателем на структуру SERVICE_FAILURE_ACTIONS_FLAG. Windows Server 2003 и Windows XP: это значение не поддерживается.
SERVICE_CONFIG_PREFERRED_NODE 9	Параметр lpInfo является указателем на структуру SERVICE_PREFERRED_NODE_INFO. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается.
SERVICE_CONFIG_PRESHUTDOWN_INFO 7	Параметр lpInfo — это указатель на структуру SERVICE_PRESHUTDOWN_INFO. Windows Server 2003 и Windows XP: это значение не поддерживается.
SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO 6	Параметр lpInfo — это указатель на структуру SERVICE_REQUIRED_PRIVILEGES_INFO. Windows Server 2003 и Windows XP: это значение не поддерживается.
SERVICE_CONFIG_SERVICE_SID_INFO 5	Параметр lpInfo является указателем на структуру SERVICE_SID_INFO.
SERVICE_CONFIG_TRIGGER_INFO 8	Параметр lpInfo является указателем на структуру SERVICE_TRIGGER_INFO. Это значение не поддерживается версией ANSI ChangeServiceConfig2. Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Это значение не поддерживается до Windows Server 2008 R2.
SERVICE_CONFIG_LAUNCH_PROTECTED 12	Параметр lpInfo — это указатель на структуру SERVICE_LAUNCH_PROTECTED_INFO. Примечание Это значение поддерживается начиная с Windows 8.1.

[in, optional] lpInfo

Указатель на новое значение, которое необходимо задать для сведений о конфигурации. Формат этих данных зависит от значения параметра dwInfoLevel. Если это значение равно null, информация остается неизменной.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение ненулевое.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

Замечания

Функция ChangeServiceConfig2 изменяет необязательные сведения о конфигурации для указанной службы в базе данных диспетчера управления службами. Текущие необязательные сведения о конфигурации можно получить с помощью функции QueryServiceConfig2.

Нельзя задать значение SERVICE_CONFIG_FAILURE_ACTIONS для службы, которая использует процесс диспетчера управления службами. Сюда входят все службы, исполняемые образы которых —Services.exe.

Вы можете изменять и запрашивать дополнительные сведения о конфигурации с помощью функций ChangeServiceConfig и QueryServiceConfig соответственно.

Если служба настроена для перезапуска после завершения ошибки, диспетчер управления службами помещает действие перезапуска после указанной задержки времени. Не удается отменить действие перезапуска в очереди. Если служба перезапущена вручную, а затем остановлена перед выполнением действия перезапуска в очереди, служба неожиданно перезапустится при истечении времени задержки. Служба должна быть явно отключена, чтобы не перезапустить ее.

Значение SERVICE_CONFIG_LAUNCH_PROTECTED можно использовать для запуска службы в качестве защищенной. Чтобы запустить службу как защищенную, служба должна быть подписана с помощью специального сертификата.

SERVICE_CONFIG_LAUNCH_PROTECTED пример:

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();
}

Примеры

Пример см. в разделе Изменениеконфигурации службы.

Заметка

Заголовок winsvc.h определяет ChangeServiceConfig2 как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winsvc.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll