Função CreateServiceA (winsvc.h)

Cria um objeto de serviço e o adiciona ao banco de dados do gerenciador de controle de serviço especificado.

Sintaxe

SC_HANDLE CreateServiceA(
  [in]            SC_HANDLE hSCManager,
  [in]            LPCSTR    lpServiceName,
  [in, optional]  LPCSTR    lpDisplayName,
  [in]            DWORD     dwDesiredAccess,
  [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
);

Parâmetros

[in] hSCManager

Um identificador para o banco de dados do gerenciador de controle de serviço. Esse identificador é retornado pela função OpenSCManager e deve ter o direito de acesso SC_MANAGER_CREATE_SERVICE. Para obter mais informações, consulte Segurança do Serviço e Direitos de Acesso.

[in] lpServiceName

O nome do serviço a ser instalado. O comprimento máximo da cadeia de caracteres é de 256 caracteres. O banco de dados do gerenciador de controle de serviço preserva as maiúsculas e minúsculas dos caracteres, mas as comparações de nome de serviço sempre diferenciam maiúsculas de minúsculas. Barra (/) e barra invertida (\) não são caracteres de nome de serviço válidos.

[in, optional] lpDisplayName

O nome de exibição a ser usado por programas de interface do usuário para identificar o serviço. Essa cadeia de caracteres tem um tamanho 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.

[in] dwDesiredAccess

O acesso ao serviço. Antes de conceder o acesso solicitado, o sistema verifica o token de acesso do processo de chamada. Para obter uma lista de valores, consulte Segurança do Serviço e Direitos de Acesso.

[in] dwServiceType

O tipo de serviço. Esse parâmetro pode usar um dos valores a seguir.

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 valor a seguir.

[in] dwStartType

As opções de início do serviço. Esse parâmetro pode usar um dos valores a seguir.

[in] dwErrorControl

A gravidade do erro e a ação executada, se esse serviço não for iniciado. Esse parâmetro pode usar um dos valores a seguir.

[in, optional] lpBinaryPathName

O caminho totalmente qualificado para o arquivo binário de serviço. 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

Os nomes do grupo de ordenação de carga do qual esse serviço é membro. Especifique NULL ou 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 seguinte valor do Registro: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\ServiceGroupOrder

[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 seguinte valor do Registro:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\GroupOrderList

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 desse serviço. Especifique NULL ou uma cadeia de caracteres vazia se o serviço não tiver dependências. A dependência em um grupo significa que esse serviço poderá ser executado se pelo menos um membro do grupo estiver em execução após uma tentativa de iniciar todos os membros do grupo.

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. Se o tipo de serviço for SERVICE_WIN32_OWN_PROCESS, use um nome de conta no formulário Nome de Usuário DomainName\. O processo de serviço será conectado como este usuário. Se a conta pertencer ao domínio interno, você poderá especificar .\UserName.

Se esse parâmetro for NULL, CreateService usará a conta LocalSystem. Se o tipo de serviço especificar SERVICE_INTERACTIVE_PROCESS, o serviço deverá ser executado na conta LocalSystem.

Se esse parâmetro for NT AUTHORITY\LocalService, CreateService usará a conta LocalService. Se o parâmetro for NT AUTHORITY\NetworkService, CreateService usará a conta NetworkService.

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 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.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o serviço.

Se a função falhar, o valor retornado será NULL. 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.

Comentários

A função CreateService cria um objeto de serviço e o instala no banco de dados do gerenciador de controle de serviço criando uma chave com o mesmo nome que o serviço na seguinte chave do Registro:HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services

As informações especificadas por CreateService, ChangeServiceConfig e ChangeServiceConfig2 são salvas como valores sob essa chave. Veja a seguir exemplos de valores armazenados para um serviço.

Programas de instalação e o próprio serviço podem criar subchaves adicionais para informações específicas do serviço.

O identificador retornado só é válido para o processo chamado CreateService. Ele pode ser fechado chamando a função CloseServiceHandle .

Se você estiver criando serviços que compartilham um processo, evite chamar funções com efeitos em todo o processo, como ExitProcess. Além disso, não descarregue sua DLL de serviço.

Exemplos

Para obter um exemplo, consulte Instalando um serviço.

Requisitos

Confira também

ChangeServiceConfig

ChangeServiceConfig2

CloseServiceHandle

ControlService

DeleteService

EnumDependentServices

OpenSCManager

QueryServiceConfig

QueryServiceDynamicInformation

QueryServiceObjectSecurity

QueryServiceStatusEx

Guia passo a passo de contas de serviço

Funções de serviço

Instalação, remoção e enumeração de serviço

SetServiceObjectSecurity

Startservice