Função ChangeServiceConfigA (winsvc.h)

Artigo
08/27/2023

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

Para alterar os parâmetros de configuração opcionais, use a função ChangeServiceConfig2 .

Sintaxe

BOOL ChangeServiceConfigA(
  [in]            SC_HANDLE hService,
  [in]            DWORD     dwServiceType,
  [in]            DWORD     dwStartType,
  [in]            DWORD     dwErrorControl,
  [in, optional]  LPCSTR    lpBinaryPathName,
  [in, optional]  LPCSTR    lpLoadOrderGroup,
  [out, optional] LPDWORD   lpdwTagId,
  [in, optional]  LPCSTR    lpDependencies,
  [in, optional]  LPCSTR    lpServiceStartName,
  [in, optional]  LPCSTR    lpPassword,
  [in, optional]  LPCSTR    lpDisplayName
);

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.

[in] dwServiceType

O tipo do serviço. Especifique SERVICE_NO_CHANGE se você não estiver alterando o tipo de serviço existente; caso contrário, especifique um dos seguintes tipos de serviço.

Valor	Significado
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Serviço de driver do sistema de arquivos.
SERVICE_KERNEL_DRIVER 0x00000001	Serviço de driver.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Serviço executado em seu próprio processo.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Serviço que compartilha um processo com outros serviços.

Se você especificar SERVICE_WIN32_OWN_PROCESS ou SERVICE_WIN32_SHARE_PROCESS e o serviço estiver em execução no contexto da conta LocalSystem, você também poderá especificar o tipo a seguir.

Valor	Significado
SERVICE_INTERACTIVE_PROCESS 0x00000100	O serviço pode interagir com a área de trabalho. Para obter mais informações, consulte Serviços Interativos.

[in] dwStartType

As opções de início do serviço. Especifique SERVICE_NO_CHANGE se você não estiver alterando o tipo de início existente; caso contrário, especifique um dos valores a seguir.

Valor	Significado
SERVICE_AUTO_START 0x00000002	Um serviço iniciado automaticamente pelo gerenciador de controle de serviço durante a inicialização do sistema.
SERVICE_BOOT_START 0x00000000	Um driver de dispositivo iniciado pelo carregador do sistema. Esse valor só é válido para serviços do driver.
SERVICE_DEMAND_START 0x00000003	Um serviço iniciado pelo gerenciador de controle de serviço quando um processo chama a função StartService .
SERVICE_DISABLED 0x00000004	Um serviço que não pode ser iniciado. Tentativas de iniciar o serviço resultam no código de erro ERROR_SERVICE_DISABLED.
SERVICE_SYSTEM_START 0x00000001	Um driver de dispositivo iniciado pela função IoInitSystem . Esse valor só é válido para serviços do driver.

[in] dwErrorControl

A gravidade do erro e a ação executadas se esse serviço não for iniciado. Especifique SERVICE_NO_CHANGE se você não estiver alterando o controle de erro existente; caso contrário, especifique um dos valores a seguir.

Valor	Significado
SERVICE_ERROR_CRITICAL 0x00000003	O programa de inicialização registra o erro no log de eventos, se possível. Se a última configuração conhecida como boa estiver sendo iniciada, a operação de inicialização falhará. Caso contrário, o sistema será reiniciado com a última boa configuração conhecida.
SERVICE_ERROR_IGNORE 0x00000000	O programa de inicialização ignora o erro e continua a operação de inicialização.
SERVICE_ERROR_NORMAL 0x00000001	O programa de inicialização registra o erro no log de eventos, mas continua a operação de inicialização.
SERVICE_ERROR_SEVERE 0x00000002	O programa de inicialização registra o erro no log de eventos. Se a última configuração conhecida-boa estiver sendo iniciada, a operação de inicialização continuará. Caso contrário, o sistema será reiniciado com a configuração last-known-good.

[in, optional] lpBinaryPathName

O caminho totalmente qualificado para o arquivo binário de serviço. Especifique NULL se você não estiver alterando o caminho existente. Se o caminho contiver um espaço, ele deverá ser citado para que seja interpretado corretamente. Por exemplo, "d:\my share\myservice.exe" deve ser especificado como ""d:\my share\myservice.exe"".

O caminho também pode incluir argumentos para um serviço de início automático. Por exemplo, "d:\myshare\myservice.exe arg1 arg2". Esses argumentos são passados para o ponto de entrada de serviço (normalmente a função main).

Se você especificar um caminho em outro computador, o compartilhamento deverá ser acessível pela conta de computador do computador local, pois esse é o contexto de segurança usado na chamada remota. No entanto, esse requisito permite que possíveis vulnerabilidades no computador remoto afetem o computador local. Portanto, é melhor usar um arquivo local.

[in, optional] lpLoadOrderGroup

O nome do grupo de ordenação de carga do qual esse serviço é membro. Especifique NULL se você não estiver alterando o grupo existente. Especifique uma cadeia de caracteres vazia se o serviço não pertencer a um grupo.

O programa de inicialização usa grupos de ordenação de carga para carregar grupos de serviços em uma ordem especificada em relação aos outros grupos. A lista de grupos de ordenação de carga está contida no valor ServiceGroupOrder da seguinte chave do Registro:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control

[out, optional] lpdwTagId

Um ponteiro para uma variável que recebe um valor de marca exclusivo no grupo especificado no parâmetro lpLoadOrderGroup . Especifique NULL se você não estiver alterando a marca existente.

Você pode usar uma marca para ordenar a inicialização do serviço em um grupo de ordenação de carga especificando um vetor de ordem de marca no valor GroupOrderList da seguinte chave do Registro:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control

As marcas são avaliadas apenas para serviços de driver que têm tipos de início SERVICE_BOOT_START ou SERVICE_SYSTEM_START .

[in, optional] lpDependencies

Um ponteiro para uma matriz terminada em nulo duplo de nomes separados por nulo de serviços ou grupos de ordenação de carga que o sistema deve iniciar antes que esse serviço possa ser iniciado. (A dependência em um grupo significa que esse serviço pode ser executado se pelo menos um membro do grupo estiver em execução após uma tentativa de iniciar todos os membros do grupo.) Especifique NULL se você não estiver alterando as dependências existentes. Especifique uma cadeia de caracteres vazia se o serviço não tiver dependências.

Você deve prefixar nomes de grupo com SC_GROUP_IDENTIFIER para que eles possam ser diferenciados de um nome de serviço, pois serviços e grupos de serviços compartilham o mesmo espaço de nome.

[in, optional] lpServiceStartName

O nome da conta na qual o serviço deve ser executado. Especifique NULL se você não estiver alterando o nome da conta existente. Se o tipo de serviço for SERVICE_WIN32_OWN_PROCESS, use um nome de conta no formulário DomainName\UserName. O processo de serviço será conectado como este usuário. Se a conta pertencer ao domínio interno, você poderá especificar .\UserName (observe que a cadeia de caracteres C/C++ correspondente é ".\\UserName"). Para obter mais informações, consulte Contas de usuário de serviço e o aviso na seção Comentários.

Um processo compartilhado pode ser executado como qualquer usuário.

Se o tipo de serviço for SERVICE_KERNEL_DRIVER ou SERVICE_FILE_SYSTEM_DRIVER, o nome será o nome do objeto do driver que o sistema usa para carregar o driver do dispositivo. Especifique NULL se o driver usar um nome de objeto padrão criado pelo sistema de E/S.

Um serviço pode ser configurado para usar uma conta gerenciada ou uma conta virtual. Se o serviço estiver configurado para usar uma conta de serviço gerenciada, o nome será o nome da conta de serviço gerenciado. Se o serviço estiver configurado para usar uma conta virtual, especifique o nome como NT SERVICE\ServiceName. Para obter mais informações sobre contas de serviço gerenciadas e contas virtuais, consulte o Guia passo a passo das contas de serviço.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Não há suporte para contas de serviço gerenciadas e contas virtuais até o Windows 7 e o Windows Server 2008 R2.

[in, optional] lpPassword

A senha para o nome da conta especificado pelo parâmetro lpServiceStartName . Especifique NULL se você não estiver alterando a senha existente. Especifique uma cadeia de caracteres vazia se a conta não tiver senha ou se o serviço for executado na conta LocalService, NetworkService ou LocalSystem. Para obter mais informações, consulte Lista de Registros de Serviço.

Se o nome da conta especificado pelo parâmetro lpServiceStartName for o nome de uma conta de serviço gerenciada ou um nome de conta virtual, o parâmetro lpPassword deverá ser NULL.

As senhas são ignoradas para serviços de driver.

[in, optional] lpDisplayName

O nome de exibição a ser usado pelos aplicativos para identificar o serviço para seus usuários. Especifique NULL se você não estiver alterando o nome de exibição existente; caso contrário, essa cadeia de caracteres tem um comprimento máximo de 256 caracteres. O nome é preservado por maiúsculas e minúsculas no gerenciador de controle de serviço. As comparações de nome de exibição sempre diferenciam maiúsculas de minúsculas.

Esse parâmetro pode especificar uma cadeia de caracteres localizada usando o seguinte formato:

@[path]dllname,-strID

A cadeia de caracteres com o strID do identificador é carregada de dllname; o caminho é opcional. Para obter mais informações, consulte RegLoadMUIString.

Windows Server 2003 e Windows XP: Não há suporte para cadeias de caracteres localizadas até o Windows Vista.

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.

Os códigos de erro a seguir podem ser definidos pelo gerenciador de controle de serviço. Outros códigos de erro podem ser definidos pelas funções do Registro que são chamadas pelo gerenciador de controle de serviço.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O identificador não tem o acesso SERVICE_CHANGE_CONFIG correto.
ERROR_CIRCULAR_DEPENDENCY	Uma dependência de serviço circular foi especificada.
ERROR_DUPLICATE_SERVICE_NAME	O nome de exibição já existe no banco de dados do gerenciador do controlador de serviço, como um nome de serviço ou como outro nome de exibição.
ERROR_INVALID_HANDLE	O identificador especificado é inválido.
ERROR_INVALID_PARAMETER	Um parâmetro especificado é inválido.
ERROR_INVALID_SERVICE_ACCOUNT	O nome da conta não existe ou um serviço é especificado para compartilhar o mesmo arquivo binário que um serviço já instalado, mas com um nome de conta que não é o mesmo que o serviço instalado.
ERROR_SERVICE_MARKED_FOR_DELETE	O serviço foi marcado para exclusão.

Comentários

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

Se a configuração for alterada para um serviço em execução, com exceção de lpDisplayName, as alterações não entrarão em vigor até que o serviço seja interrompido. Para atualizar as credenciais sem precisar reiniciar o serviço, use a função LsaCallAuthenticationPackage .

Comentários de segurança

Definir o parâmetro lpServiceStartName altera a conta de logon do serviço. Isso pode causar problemas. Se você tiver registrado um SPN (nome da entidade de serviço), ele agora será registrado na conta errada. Da mesma forma, se você tiver usado uma ACE para conceder acesso a um serviço, ela agora concederia acesso à conta errada.

Exemplos

Para obter um exemplo, consulte Alterando a configuração de um serviç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 (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll