Função OpenServiceA (winsvc.h)

Artigo
08/27/2023

Abre um serviço existente.

Sintaxe

SC_HANDLE OpenServiceA(
  [in] SC_HANDLE hSCManager,
  [in] LPCSTR    lpServiceName,
  [in] DWORD     dwDesiredAccess
);

Parâmetros

[in] hSCManager

Um identificador para o banco de dados do gerenciador de controle de serviço. A função OpenSCManager retorna esse identificador. Para obter mais informações, consulte Segurança do Serviço e Direitos de Acesso.

[in] lpServiceName

O nome do serviço a ser aberto. Esse é o nome especificado pelo parâmetro lpServiceName da função CreateService quando o objeto de serviço foi criado, não o nome de exibição do serviço mostrado pelos aplicativos de interface do usuário para identificar o serviço.

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 (\) são caracteres de nome de serviço inválidos.

[in] dwDesiredAccess

O acesso ao serviço. Para obter uma lista de direitos de acesso, consulte Segurança do Serviço e Direitos de Acesso.

Antes de conceder o acesso solicitado, o sistema verifica o token de acesso do processo de chamada em relação à lista de controle de acesso discricionário do descritor de segurança associado ao objeto de serviço.

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. Outras podem ser definidas 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 acesso ao serviço.
ERROR_INVALID_HANDLE	O identificador especificado é inválido.
ERROR_INVALID_NAME	O nome do serviço especificado é inválido.
ERROR_SERVICE_DOES_NOT_EXIST	O serviço especificado não existe.

Comentários

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

Para usar o OpenService, nenhum privilégio é necessário além de SC_MANAGER_CONNECT.

Exemplos

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

Observação

O cabeçalho winsvc.h define OpenService como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de funçã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