Função ConnectServerWmi

Artigo
05/10/2023

Cria uma ligação através do DCOM a um espaço de nomes WMI num computador especificado.

Nota

Esta API destina-se apenas a utilização interna. Não se destina a ser utilizado a partir do código do programador.

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 válido BSTR que contém o caminho do objeto do espaço de nomes WMI correto. Consulte a secção Observações para obter mais informações.

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

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

strLocale
[in] Um ponteiro para um valor válido BSTR que indica a região correta para obtenção de informações. Para os identificadores de região da Microsoft, o formato da cadeia é "MS_xxx", em que xxx é uma cadeia na forma hexadecimal que indica o identificador de região (LCID). Se for especificada uma região inválida, o método será devolvido WBEM_E_INVALID_PARAMETER exceto no Windows 7, onde é utilizada a região predefinida do servidor. Se "null1, é utilizada a região atual.

lSecurityFlags
[in] Sinalizadores para passar para o ConnectServerWmi método. Um valor de zero (0) para este parâmetro resulta na chamada para ConnectServerWmi devolver apenas após a ligação ao servidor ser estabelecida. Isto pode resultar numa aplicação que não responde indefinidamente se o servidor estiver avariado. Os outros valores válidos são:

Constante	Valor	Descrição
`CONNECT_REPOSITORY_ONLY`	0x40	Reservado para utilização interna. Não utilizar.
`WBEM_FLAG_CONNECT_USE_MAX_WAIT`	0x80	`ConnectServerWmi` devolve em dois minutos ou menos.

strAuthority
[in] O nome de domínio do utilizador. Pode ter os seguintes valores:

Valor	Descrição
em branco	A autenticação NTLM é utilizada e é utilizado o domínio NTLM do utilizador atual. Se `strUser` especificar o domínio (a localização recomendada), não pode ser especificado aqui. A função devolve `WBEM_E_INVALID_PARAMETER` se especificar o domínio em ambos os parâmetros.
Kerberos:nome principal	A autenticação Kerberos é utilizada e este parâmetro contém um nome principal kerberos.
NTLMDOMAIN:nome de domínio	A autenticação NT LAN Manager é utilizada e este parâmetro contém um nome de domínio NTLM.

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

ppNamespace
[fora] Quando a função é devolvida, recebe um ponteiro para um objeto IWbemServices vinculado ao espaço de nomes especificado. Está definido para apontar para null quando existe um erro.

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

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

Valor devolvido

Os seguintes valores devolvidos por esta função são definidos no ficheiro de cabeçalho WbemCli.h ou pode defini-los como constantes no seu código:

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

Observações

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

Para o acesso local ao espaço de nomes predefinido, strNetworkResource pode ser um caminho de objeto simples: "root\default" ou "\.\root\default". Para aceder ao espaço de nomes predefinido num computador remoto através de redes compatíveis com COM ou 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 ligar-se a computadores com IPv6 com um endereço IPv6.

strUser não pode ser uma cadeia vazia. Se o domínio for especificado no strAuthority, também não pode ser incluído no strUserou a função devolve WBEM_E_INVALID_PARAMETER.

Requisitos

Plataformas: Veja Requisitos do Sistema.

Cabeçalho: WMINet_Utils.idl

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

Ver também

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

Partilhar via