Função ConnectServerWmi

Artigo
05/10/2023

Cria uma conexão por meio do DCOM para um namespace do WMI em um computador especificado.

Observação

Esta API é somente para uso interno. Ela não é destinada ao uso do código do desenvolvedor.

Sintaxe

HRESULT ConnectServerWmi (
   [in] BSTR               strNetworkResource,
   [in] BSTR               strUser,
   [in] BSTR               strPassword,
   [in] BSTR               strLocale,
   [in] long               lSecurityFlags,
   [in] BSTR               strAuthority,
   [in] IWbemContext*      pCtx,
   [out] IWbemServices**   ppNamespace,
   [in] DWORD              impLevel,
   [in] DWORD              authLevel
);

Parâmetros

strNetworkResource
[in] Ponteiro para um BSTR válido que contém o caminho do objeto do namespace WMI correto. Consulte a seção Comentários para obter mais informações.

strUser
[in] Um ponteiro para um BSTR válido que contém o nome de usuário. Um valor null indica o contexto de segurança atual. Se o usuário for de um domínio diferente do atual, strUser também poderá conter o domínio e o nome de usuário separados por uma barra invertida. strUser também pode estar no formato UPN (nome da entidade de segurança de usuário), como userName@domainName. Consulte a seção Comentários para obter mais informações.

strPassword
[in] Um ponteiro para um BSTR válido que contém a senha. Um null indica o contexto de segurança atual. Uma cadeia de caracteres vazia ("") indica uma senha válida de comprimento zero.

strLocale
[in] Um ponteiro para um BSTR válido que indica a localidade correta para recuperação de informações. Para identificadores de localidade da Microsoft, o formato da cadeia de caracteres é "MS_xxx", em que xxx é uma cadeia de caracteres em forma hexadecimal que indica o identificador de localidade (LCID). Se for especificada uma localidade inválida, o método retornará WBEM_E_INVALID_PARAMETER, exceto no Windows 7, em que é usada a localidade padrão do servidor. Se 'null1, a localidade atual será usada.

lSecurityFlags
[in] Sinalizadores a serem passados para o método ConnectServerWmi. Um valor zero (0) para esse parâmetro resulta que a chamada de ConnectServerWmi retorne somente depois que uma conexão com o servidor é estabelecida. Isso pode resultar em um aplicativo que não responde indefinidamente se o servidor estiver quebrado. Outros valores válidos são:

Constante	Valor	Descrição
`CONNECT_REPOSITORY_ONLY`	0x40	Reservado para uso interno. Não use.
`WBEM_FLAG_CONNECT_USE_MAX_WAIT`	0x80	`ConnectServerWmi` retorna em dois minutos ou menos.

strAuthority
[in] O nome de domínio do usuário. Pode ter um dos valores a seguir:

Valor	Descrição
blank	A autenticação NTLM é usada e o domínio NTLM do usuário atual é usado. Se `strUser` especificar o domínio (o local recomendado), ele não deverá ser especificado aqui. A função retornará `WBEM_E_INVALID_PARAMETER` se você especificar o domínio em ambos os parâmetros.
Kerberos:nome da entidade de segurança	A autenticação Kerberos é usada e esse parâmetro contém um nome de entidade de segurança Kerberos.
NTLMDOMAIN:nome do Domínio	A autenticação do NT LAN Manager é usada e esse parâmetro contém um nome de domínio NTLM.

pCtx
[in] Normalmente, esse parâmetro é null. Caso contrário, ele é um ponteiro para um objeto IWbemContext exigido por um ou mais provedores de classe dinâmica.

ppNamespace
[out] Quando a função retorna, recebe um ponteiro para um objeto IWbemServices associado ao namespace especificado. Ele é definido como apontar para null quando há um erro.

impLevel
[in] O nível de representação.

authLevel
[in] O nível de autorização.

Valor retornado

Os seguintes valores retornados por essa função são definidos no arquivo de cabeçalho WbemCli.h, ou você pode defini-los como constantes em seu código:

Constante	Valor	Descrição
`WBEM_E_FAILED`	0x80041001	Houve uma falha geral.
`WBEM_E_INVALID_PARAMETER`	0x80041008	Um parâmetro não é válido.
`WBEM_E_OUT_OF_MEMORY`	0x80041006	Não há memória disponível suficiente para concluir a operação.
`WBEM_S_NO_ERROR`	0	A chamada de função foi bem-sucedida.

Comentários

Essa função encapsula uma chamada para o método IWbemLocator::ConnectServer.

Para acesso local ao namespace padrão, strNetworkResource pode ser um caminho de objeto simples: "root\default" ou "\.\root\default". Para acessar o namespace padrão em um computador remoto usando COM ou rede compatível com a Microsoft, inclua o nome do computador: "\myserver\root\default". O nome do computador também pode ser um nome DNS ou endereço IP. A ConnectServerWmi função também pode se conectar com computadores que executam IPv6 usando um endereço IPv6.

strUser não pode ser uma cadeia de caracteres vazia. Se o domínio for especificado em strAuthority, ele também não deverá ser incluído em strUserou a função retornará WBEM_E_INVALID_PARAMETER.

Requisitos

Plataformas: confira Requisitos do sistema.

Header: WMINet_Utils.idl

Versões do .NET Framework: Disponível desde 4.7.2

Confira também

WMI e Contadores de Desempenho (Referência de API Não Gerenciada)

Compartilhar via