Função ChangeServiceConfig2A (winsvc.h)

Artigo
08/27/2023

Altera os parâmetros de configuração opcionais de um serviço.

Sintaxe

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

Parâmetros

[in] hService

Um identificador para o serviço. Esse identificador é retornado pela função OpenService ou CreateService e deve ter o direito de acesso SERVICE_CHANGE_CONFIG. Para obter mais informações, consulte Segurança do Serviço e Direitos de Acesso.

Se o controlador de serviço manipular a ação SC_ACTION_RESTART , hService deverá ter o direito de acesso SERVICE_START .

[in] dwInfoLevel

As informações de configuração a serem alteradas. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
SERVICE_CONFIG_DELAYED_AUTO_START_INFO 3	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_DELAYED_AUTO_START_INFO . Windows Server 2003 e Windows XP: Não há suporte para esse valor.
SERVICE_CONFIG_DESCRIPTION 1	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_DESCRIPTION .
SERVICE_CONFIG_FAILURE_ACTIONS 2	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_FAILURE_ACTIONS . Se o controlador de serviço manipular a ação SC_ACTION_REBOOT, o chamador deverá ter o privilégioSE_SHUTDOWN_NAME. Para obter mais informações, confira Executar com privilégios especiais.
SERVICE_CONFIG_FAILURE_ACTIONS_FLAG 4	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_FAILURE_ACTIONS_FLAG . Windows Server 2003 e Windows XP: Não há suporte para esse valor.
SERVICE_CONFIG_PREFERRED_NODE 9	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_PREFERRED_NODE_INFO . Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para esse valor.
SERVICE_CONFIG_PRESHUTDOWN_INFO 7	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_PRESHUTDOWN_INFO . Windows Server 2003 e Windows XP: Não há suporte para esse valor.
SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO 6	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_REQUIRED_PRIVILEGES_INFO . Windows Server 2003 e Windows XP: Não há suporte para esse valor.
SERVICE_CONFIG_SERVICE_SID_INFO 5	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_SID_INFO .
SERVICE_CONFIG_TRIGGER_INFO 8	O parâmetro lpInfo é um ponteiro para uma estrutura SERVICE_TRIGGER_INFO . Esse valor não é compatível com a versão ANSI de ChangeServiceConfig2. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Esse valor não tem suporte até o Windows Server 2008 R2.
SERVICE_CONFIG_LAUNCH_PROTECTED 12	O parâmetro lpInfo é um ponteiro de uma estrutura SERVICE_LAUNCH_PROTECTED_INFO . Nota Esse valor tem suporte começando com Windows 8.1.

[in, optional] lpInfo

Um ponteiro para o novo valor a ser definido para as informações de configuração. O formato desses dados depende do valor do parâmetro dwInfoLevel . Se esse valor for NULL, as informações permanecerão inalteradas.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função ChangeServiceConfig2 altera as informações de configuração opcionais para o serviço especificado no banco de dados do gerenciador de controle de serviço. Você pode obter as informações de configuração opcionais atuais usando a função QueryServiceConfig2 .

Não é possível definir o valor SERVICE_CONFIG_FAILURE_ACTIONS para um serviço que compartilha o processo do gerenciador de controle de serviço. Isso inclui todos os serviços cuja imagem executável é "Services.exe".

Você pode alterar e consultar informações de configuração adicionais usando as funções ChangeServiceConfig e QueryServiceConfig , respectivamente.

Se um serviço estiver configurado para reiniciar após a conclusão com um erro, o gerenciador de controle de serviço enfileirará a ação de reinicialização para ocorrer após o atraso de tempo especificado. Uma ação de reinicialização enfileirada não pode ser cancelada. Se o serviço for reiniciado manualmente e interrompido antes que a ação de reinicialização enfileirada ocorra, o serviço será reiniciado inesperadamente quando o atraso de tempo decorrer. O serviço deve ser explicitamente desabilitado para impedir que ele seja reiniciado.

O valor SERVICE_CONFIG_LAUNCH_PROTECTED pode ser usado para iniciar o serviço como protegido. Para iniciar o serviço como protegido, o serviço deve ser assinado com um certificado especial.

SERVICE_CONFIG_LAUNCH_PROTECTED exemplo:

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

Exemplos

Para obter um exemplo, consulte Alterando a configuração de um serviço.

Observação

O cabeçalho winsvc.h define ChangeServiceConfig2 como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winsvc.h (incluir Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll