Função OpenSCManagerA (winsvc.h)

Artigo
03/08/2023

Estabelece uma conexão com o gerenciador de controle de serviço no computador especificado e abre o banco de dados do gerenciador de controle de serviço especificado.

Sintaxe

SC_HANDLE OpenSCManagerA(
  [in, optional] LPCSTR lpMachineName,
  [in, optional] LPCSTR lpDatabaseName,
  [in]           DWORD  dwDesiredAccess
);

Parâmetros

[in, optional] lpMachineName

O nome do computador de destino. Se o ponteiro for NULL ou apontar para uma cadeia de caracteres vazia, a função se conectará ao gerenciador de controle de serviço no computador local.

[in, optional] lpDatabaseName

O nome do banco de dados do gerenciador de controle de serviço. Esse parâmetro deve ser definido como SERVICES_ACTIVE_DATABASE. Se for NULL, o banco de dados SERVICES_ACTIVE_DATABASE será aberto por padrão.

[in] dwDesiredAccess

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

Antes de conceder os direitos de acesso solicitados, o sistema verifica o token de acesso do processo de chamada na lista de controle de acesso discricionário do descritor de segurança associado ao gerenciador de controle de serviço.

O SC_MANAGER_CONNECT direito de acesso é especificado implicitamente chamando essa função.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o banco de dados do gerenciador de controle de serviço especificado.

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 SCM. Outros códigos de erro podem ser definidos pelas funções do Registro que são chamadas pelo SCM.

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O acesso solicitado foi negado.
ERROR_DATABASE_DOES_NOT_EXIST	O banco de dados especificado não existe.

Comentários

Quando um processo usa a função OpenSCManager para abrir um identificador para um banco de dados do gerenciador de controle de serviço, o sistema executa uma marcar de segurança antes de conceder o acesso solicitado. Para obter mais informações, consulte Segurança do serviço e Direitos de Acesso.

Se o usuário atual não tiver acesso adequado ao se conectar a um serviço em outro computador, a chamada de função OpenSCManager falhará. Para se conectar a um serviço remotamente, chame a função LogonUser com LOGON32_LOGON_NEW_CREDENTIALS e chame ImpersonateLoggedOnUser antes de chamar OpenSCManager. Para obter mais informações sobre como se conectar a serviços remotamente, consulte Serviços e RPC/TCP.

Somente processos com privilégios de administrador são capazes de abrir um identificador de banco de dados que pode ser usado pela função CreateService .

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

Exemplos

Para obter um exemplo, consulte Alterando a configuração de um serviço.

Observação

O cabeçalho winsvc.h define OpenSCManager 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 (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll