Método IWbemLocator::ConnectServer (wbemcli.h)

Artigo
03/03/2024

O método IWbemLocator::ConnectServer cria uma conexão por meio do DCOM com um namespace WMI no computador especificado no parâmetro strNetworkResource .

SWbemLocator.ConnectServer pode se conectar com computadores que executam IPv6 usando um endereço IPv6 no parâmetro strNetworkResource . Para obter mais informações, consulte Suporte a IPv6 e IPv4 no WMI.

Sintaxe

HRESULT ConnectServer(
  [in]  const BSTR    strNetworkResource,
  [in]  const BSTR    strUser,
  [in]  const BSTR    strPassword,
  [in]  const BSTR    strLocale,
  [in]  long          lSecurityFlags,
  [in]  const BSTR    strAuthority,
  [in]  IWbemContext  *pCtx,
  [out] IWbemServices **ppNamespace
);

Parâmetros

[in] strNetworkResource

Ponteiro para um BSTR válido que contém o caminho do objeto do namespace WMI correto. Para acesso local ao namespace padrão, use 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". Para obter mais informações, consulte Descrevendo um caminho de objeto de namespace WMI. O nome do computador também pode ser um nome DNS ou endereço IP. A partir do Windows Vista, sWbemLocator.ConnectServer pode se conectar com computadores que executam IPv6 usando um endereço IPv6. Para obter mais informações, consulte Suporte a IPv6 e IPv4 no WMI.

[in] strUser

Ponteiro para um BSTR válido, que contém o nome de usuário necessário para uma conexão. Um valor NULL indica o contexto de segurança atual. Se o nome de usuário for de um domínio diferente do domínio atual, a cadeia de caracteres poderá conter o nome de domínio e o nome de usuário separados por uma barra invertida.

StrUserName = SysAllocString(L"Domain\UserName");

O parâmetro strUser não pode ser uma cadeia de caracteres vazia. Observe que, se o domínio for especificado em strAuthority, ele não deverá ser especificado aqui. Especificar o domínio em ambos os parâmetros resulta em um erro de parâmetro inválido.

Você pode usar o formato UPN (nome upn), que é Username@DomainName para especificar o strUser.

[in] strPassword

Ponteiro para um BSTR válido que contém a senha necessária para uma conexão. Um valor NULL indica o contexto de segurança atual. Uma cadeia de caracteres em branco "" especifica uma senha válida de comprimento zero.

[in] strLocale

Se NULL, a localidade atual será usada. Se não for NULL, esse parâmetro deverá ser um BSTR válido, o 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 na forma hexadecimal que indica a Identificação Local (LCID), por exemplo, o inglês americano apareceria como "MS_409". Se uma localidade inválida for especificada, o método retornará WBEM_E_INVALID_PARAMETER.

Windows 7: Se uma localidade inválida for especificada, a localidade padrão do servidor será usada, a menos que haja uma localidade com suporte para servidor fornecida pelo aplicativo do usuário.

[in] lSecurityFlags

Valor longo usado para passar valores de sinalizador para ConnectServer. Um valor zero (0) para esse parâmetro resulta na chamada para ConnectServer retornando somente após a conexão com o servidor ser estabelecida. Isso pode fazer com que o programa ceda a responder indefinidamente se o servidor estiver quebrado. A lista a seguir lista os outros valores válidos para lSecurityFlags.

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40))

Reservado para uso interno. Não use.

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80))

A chamada ConnectServer retorna em 2 minutos ou menos. Use esse sinalizador para impedir que o programa ceda para responder indefinidamente se o servidor estiver quebrado.

[in] strAuthority

Esse parâmetro contém o nome do domínio do usuário a ser autenticado.

strAuthority pode ter os seguintes valores:

blank
Se você deixar esse parâmetro em branco, a autenticação NTLM será usada e o domínio NTLM do usuário atual será usado. Se o domínio for especificado em strUser, que é o local recomendado, ele não deverá ser especificado aqui. Especificar o domínio em ambos os parâmetros resulta em um erro de parâmetro inválido.
Kerberos:<nome principal>
A autenticação Kerberos é usada e esse parâmetro deve conter um nome de entidade de segurança Kerberos.
NTLMDOMAIN:<domain name>
A autenticação do NT LAN Manager é usada e esse parâmetro deve conter um nome de domínio NTLM.

[in] pCtx

Normalmente, isso é NULL. Caso contrário, esse é um ponteiro para um objeto IWbemContext exigido por um ou mais provedores de classe dinâmica. Os valores no objeto de contexto devem ser especificados na documentação para os provedores em questão. Para obter mais informações sobre esse parâmetro, consulte Fazendo chamadas para WMI.

[out] ppNamespace

Recebe um ponteiro para um objeto IWbemServices associado ao namespace especificado. Esse ponteiro tem uma contagem de referência positiva. O chamador deve chamar IWbemServices::Release no ponteiro quando ele não for mais necessário. Esse ponteiro é definido para apontar para NULL quando há um erro.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista o valor contido em um HRESULT.

Códigos de erro específicos do COM podem ser retornados se problemas de rede fizerem com que você perca a conexão remota com o WMI.

Esses códigos de retorno de erro são definidos no arquivo Wbemcli.h na seção WMI do diretório PSDK \Include. Para obter mais informações, consulte Constantes de erro WMI.

Comentários

Não especifique strUser, strPassword ou strAuthority ao fazer uma conexão com um namespace local. Para obter mais informações, confira Como conectar-se ao WMI em um computador remoto.

Para obter mais informações sobre como usar o ConnectServer, consulte Criando uma conexão com um namespace WMI. Observe que a conexão com IWbemLocator é uma das conexões que você deve desligar no final do aplicativo, conforme descrito em Limpar e desligar um aplicativo WMI.

Exemplos

Para obter vários exemplos que usam o método ConnectServer , consulte Exemplos de aplicativo WMI C++.

O exemplo de código C++ a seguir descreve como usar smi2smir.xml para se conectar a um namespace especificado.

int _tmain(int argc, _TCHAR* argv[]) 
{ 
    // Initialize COM. ------------------------------------------ 
    HRESULT hres = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED); 
    if (FAILED(hres)) 
    { 
        wcout << "CoInitializeEx() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
 
    // Obtain the initial locator to Windows Management 
    // on a particular host computer. 
    IWbemLocator *pLoc = NULL; 
    hres = CoCreateInstance(CLSID_WbemLocator, 0, CLSCTX_INPROC_SERVER,IID_IWbemLocator, (LPVOID *)&pLoc); 
    if (FAILED(hres)) 
    { 
        CoUninitialize(); 
        wcout << "CreateInstance failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
 
    // Connect to WMI through the IWbemLocator::ConnectServer method 
    // Connect to the local ROOT\CIMV2 namespace 
    // and obtain pointer pSvc to make IWbemServices calls. 
    IWbemServices *pSvc = NULL;
    BSTR namespace = SysAllocString(L"ROOT\\CimV2");
    hres = pLoc->ConnectServer(namespace, NULL, NULL, 0, NULL, 0, 0, &pSvc);
    SysFreeString(namespace);
 
    if (FAILED(hres)) 
    { 
        pLoc->Release(); 
        CoUninitialize(); 
        wcout << "ConnectServer() failure:" << hex << (unsigned long)hres; 
        return 0; 
    } 
    ...
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	wbemcli.h (inclua Wbemidl.h)
Biblioteca	Wbemuuid.lib
DLL	Wbemcore.dll