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 |
|---|---|
|
Reservado. |
|
Serviço de driver do sistema de arquivos. |
|
Serviço de driver. |
|
Reservado. |
|
Serviço que é executado em seu próprio processo. |
|
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 |
|---|---|
|
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 |
|---|---|
|
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. |
|
Um driver de dispositivo iniciado pelo carregador do sistema. Esse valor só é válido para serviços do driver. |
|
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. |
|
Um serviço que não pode ser iniciado. Tentativas de iniciar o serviço resultam no código de erro ERROR_SERVICE_DISABLED. |
|
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.
[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 |
|---|---|
|
O identificador do banco de dados SCM não tem o direito de acesso SC_MANAGER_CREATE_SERVICE . |
|
Uma dependência de serviço circular foi especificada. |
|
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. |
|
O identificador para o banco de dados do gerenciador de controle de serviço especificado é inválido. |
|
O nome do serviço especificado é inválido. |
|
Um parâmetro especificado é inválido. |
|
O nome da conta de usuário especificado no parâmetro lpServiceStartName não existe. |
|
O serviço especificado já existe neste banco de dados. |
|
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
QueryServiceDynamicInformation
Guia passo a passo de contas de serviço