Função ChangeServiceConfig2A (winsvc.h)

Artigo
11/20/2024

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 do OpenService ou CreateService e deve ter o acesso SERVICE_CHANGE_CONFIG correto. Para obter mais informações, consulte de Direitos de Acesso e Segurança do Serviço.

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

[in] dwInfoLevel

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

Valor	Significado
SERVICE_CONFIG_DELAYED_AUTO_START_INFO 3	O parâmetro lpInfo é um ponteiro para uma estrutura de SERVICE_DELAYED_AUTO_START_INFO. Windows Server 2003 e Windows XP: Esse valor não tem suporte.
SERVICE_CONFIG_DESCRIPTION 1	O parâmetro lpInfo é um ponteiro para uma estrutura de SERVICE_DESCRIPTION.
SERVICE_CONFIG_FAILURE_ACTIONS 2	O parâmetro lpInfo é um ponteiro para uma estrutura de SERVICE_FAILURE_ACTIONS. Se o controlador de serviço manipular a ação SC_ACTION_REBOOT, o chamador deverá ter o privilégio SE_SHUTDOWN_NAME. Para obter mais informações, consulte Em execução 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: Esse valor não tem suporte.
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: Esse valor não tem suporte.
SERVICE_CONFIG_REQUIRED_PRIVILEGES_INFO 6	O parâmetro lpInfo é um ponteiro para uma estrutura de SERVICE_REQUIRED_PRIVILEGES_INFO. Windows Server 2003 e Windows XP: Esse valor não tem suporte.
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 do 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. Observação Esse valor tem suporte a partir do 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 de retorno

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

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

Observações

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.

Você não pode 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 ser reiniciado após a conclusão com um erro, o gerenciador de controle de serviço enfileira a ação de reinicialização para ocorrer após o atraso de tempo especificado. Uma ação de reinicialização na fila não pode ser cancelada. Se o serviço for reiniciado manualmente e interrompido antes que a ação de reinicialização na fila ocorra, o serviço será reiniciado inesperadamente quando o tempo de atraso se passar. O serviço deve estar 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 ode configuração de um serviço.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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