Função CreateServiceW (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 CreateServiceW(
  [in]            SC_HANDLE hSCManager,
  [in]            LPCWSTR   lpServiceName,
  [in, optional]  LPCWSTR   lpDisplayName,
  [in]            DWORD     dwDesiredAccess,
  [in]            DWORD     dwServiceType,
  [in]            DWORD     dwStartType,
  [in]            DWORD     dwErrorControl,
  [in, optional]  LPCWSTR   lpBinaryPathName,
  [in, optional]  LPCWSTR   lpLoadOrderGroup,
  [out, optional] LPDWORD   lpdwTagId,
  [in, optional]  LPCWSTR   lpDependencies,
  [in, optional]  LPCWSTR   lpServiceStartName,
  [in, optional]  LPCWSTR   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.

Valor Significado
SERVICE_ADAPTER
0x00000004
Reservado.
SERVICE_FILE_SYSTEM_DRIVER
0x00000002
Serviço de driver do sistema de arquivos.
SERVICE_KERNEL_DRIVER
0x00000001
Serviço de driver.
SERVICE_RECOGNIZER_DRIVER
0x00000008
Reservado.
SERVICE_WIN32_OWN_PROCESS
0x00000010
Serviço que é executado em seu próprio processo.
SERVICE_WIN32_SHARE_PROCESS
0x00000020
Serviço que compartilha um processo com um ou mais outros serviços. Para obter mais informações, consulte Programas de serviço.
 

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.

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. Esse parâmetro pode usar 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. Para obter mais informações, consulte Iniciando serviços automaticamente.
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 . Para obter mais informações, consulte Iniciando serviços sob demanda.
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 executada, se esse serviço não for iniciado. Esse parâmetro pode usar 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 configuração válida 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 estiver sendo iniciada, a operação de inicialização continuará. Caso contrário, o sistema será reiniciado com a última configuração válida.

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

Código de retorno Descrição
ERROR_ACCESS_DENIED
O identificador do banco de dados SCM não tem o direito de acesso SC_MANAGER_CREATE_SERVICE .
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 de controle de serviço como um nome de serviço ou como outro nome de exibição.
ERROR_INVALID_HANDLE
O identificador para o banco de dados do gerenciador de controle de serviço especificado é inválido.
ERROR_INVALID_NAME
O nome do serviço especificado é inválido.
ERROR_INVALID_PARAMETER
Um parâmetro especificado é inválido.
ERROR_INVALID_SERVICE_ACCOUNT
O nome da conta de usuário especificado no parâmetro lpServiceStartName não existe.
ERROR_SERVICE_EXISTS
O serviço especificado já existe neste banco de dados.
ERROR_SERVICE_MARKED_FOR_DELETE
O serviço especificado já existe neste banco de dados e foi marcado para exclusã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.

Valor Descrição
DependOnGroup Grupos de ordenação de carga dos quais esse serviço depende, conforme especificado por lpDependencies.
DependOnService Serviços dos quais esse serviço depende, conforme especificado por lpDependencies.
Descrição Descrição especificada por ChangeServiceConfig2.
DisplayName Nome de exibição especificado por lpDisplayName.
ErrorControl Controle de erro especificado por dwErrorControl.
FailureActions Ações de falha especificadas por ChangeServiceConfig2.
Grupo Carregar o grupo de ordenação especificado por lpLoadOrderGroup. Observe que definir esse valor pode substituir a configuração do valor DependOnService .
Imagepath Nome do arquivo binário, conforme especificado por lpBinaryPathName.
ObjectName Nome da conta especificado por lpServiceStartName.
Iniciar Quando iniciar o serviço, conforme especificado por dwStartType.
Tag Identificador de marca especificado por lpdwTagId.
Tipo Tipo de serviço especificado por dwServiceType.
 

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

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

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