Metodo IWbemLocator::ConnectServer (wbemcli.h)

Articolo
03/13/2024

Il metodo IWbemLocator::ConnectServer crea una connessione tramite DCOM a uno spazio dei nomi WMI nel computer specificato nel parametro strNetworkResource .

SWbemLocator.ConnectServer può connettersi ai computer che eseguono IPv6 usando un indirizzo IPv6 nel parametro strNetworkResource . Per altre informazioni, vedere Supporto IPv6 e IPv4 in WMI.

Sintassi

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
);

Parametri

[in] strNetworkResource

Puntatore a un BSTR valido che contiene il percorso dell'oggetto dello spazio dei nomi WMI corretto. Per l'accesso locale allo spazio dei nomi predefinito, usare un percorso di oggetto semplice: "root\default" o "\.\root\default". Per l'accesso allo spazio dei nomi predefinito in un computer remoto usando la rete compatibile con COM o Microsoft, includere il nome del computer: "\myserver\root\default". Per altre informazioni, vedere Descrizione di un percorso oggetto dello spazio dei nomi WMI. Il nome del computer può anche essere un nome DNS o un indirizzo IP. A partire da Windows Vista, SWbemLocator.ConnectServer può connettersi ai computer che eseguono IPv6 usando un indirizzo IPv6. Per altre informazioni, vedere Supporto IPv6 e IPv4 in WMI.

[in] strUser

Puntatore a un BSTR valido, che contiene il nome utente necessario per una connessione. Un valore NULL indica il contesto di sicurezza corrente. Se il nome utente proviene da un dominio diverso dal dominio corrente, la stringa può contenere il nome di dominio e il nome utente separati da una barra rovesciata.

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

Il parametro strUser non può essere una stringa vuota. Si noti che se il dominio è specificato in strAuthority, non deve essere specificato qui. Se si specifica il dominio in entrambi i parametri, viene generato un errore di parametro non valido.

È possibile usare il formato UPN (User Principal Name), che è Username@DomainName per specificare strUser.

[in] strPassword

Puntatore a un BSTR valido che contiene la password necessaria per una connessione. Un valore NULL indica il contesto di sicurezza corrente. Una stringa vuota "" specifica una password di lunghezza zero valida.

[in] strLocale

Se NULL, vengono usate le impostazioni locali correnti. In caso contrario, questo parametro deve essere un BSTR valido, che indica le impostazioni locali corrette per il recupero delle informazioni. Per gli identificatori delle impostazioni locali Microsoft, il formato della stringa è "MS_xxx", dove xxx è una stringa in formato esadecimale che indica l'identificazione locale (LCID), ad esempio, l'inglese americano verrà visualizzato come "MS_409". Se vengono specificate impostazioni locali non valide, il metodo restituisce WBEM_E_INVALID_PARAMETER.

Windows 7: Se vengono specificate impostazioni locali non valide, le impostazioni locali predefinite del server vengono usate a meno che non siano presenti impostazioni locali supportate dal server fornite dall'applicazione utente.

[in] lSecurityFlags

Valore lungo usato per passare i valori del flag a ConnectServer. Un valore pari a zero (0) per questo parametro genera la chiamata a ConnectServer che restituisce solo dopo la connessione al server. Ciò potrebbe comportare il ceasing del programma per rispondere in modo indefinito se il server è interrotto. Nell'elenco seguente sono elencati gli altri valori validi per lSecurityFlags.

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40))

Riservato per utilizzo interno. Non usare.

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80))

La chiamata ConnectServer restituisce in 2 minuti o meno. Usare questo flag per impedire che il programma risponda in modo indefinito se il server è interrotto.

[in] strAuthority

Questo parametro contiene il nome del dominio dell'utente da autenticare.

strAuthority può avere i valori seguenti:

vuoto
Se si lascia vuoto questo parametro, viene usata l'autenticazione NTLM e viene usato il dominio NTLM dell'utente corrente. Se il dominio è specificato in strUser, ovvero il percorso consigliato, non deve essere specificato qui. Se si specifica il dominio in entrambi i parametri, viene generato un errore di parametro non valido.
Nome Kerberos:<principal>
L'autenticazione Kerberos viene usata e questo parametro deve contenere un nome dell'entità Kerberos.
NTLMDOMAIN:<domain name>
L'autenticazione di NT LAN Manager viene usata e questo parametro deve contenere un nome di dominio NTLM.

[in] pCtx

In genere, questo è NULL. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext richiesto da uno o più provider di classi dinamiche. I valori nell'oggetto contesto devono essere specificati nella documentazione per i provider in questione. Per altre informazioni su questo parametro, vedere Creazione di chiamate a WMI.

[out] ppNamespace

Riceve un puntatore a un oggetto IWbemServices associato allo spazio dei nomi specificato. Questo puntatore ha un numero di riferimenti positivo. Il chiamante deve chiamare IWbemServices::Release nel puntatore quando non è più necessario. Questo puntatore è impostato su NULL quando si verifica un errore.

Valore restituito

Questo metodo restituisce un HRESULT che indica lo stato della chiamata al metodo. L'elenco seguente elenca il valore contenuto in un HRESULT.

I codici di errore specifici di COM possono essere restituiti se i problemi di rete causano la perdita della connessione remota a WMI.

Questi codici restituiti di errore sono definiti nel file Wbemcli.h nella sezione WMI della directory PSDK \Include. Per altre informazioni, vedere Costanti di errore WMI.

Commenti

Non specificare strUser, strPassword o strAuthority quando si effettua una connessione a uno spazio dei nomi locale. Per altre informazioni, vedere Connessione a WMI in un computer remoto.

Per altre informazioni su come usare ConnectServer, vedere Creazione di una connessione a uno spazio dei nomi WMI. Si noti che la connessione a IWbemLocator è una delle connessioni che è necessario arrestare alla fine dell'applicazione, come descritto in Pulizia e arresto di un'applicazione WMI.

Esempio

Per più esempi che usano il metodo ConnectServer , vedere Esempi di applicazioni WMI C++.

L'esempio di codice C++ seguente descrive come usare smi2smir.xml per connettersi a uno spazio dei nomi specificato.

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; 
    } 
    ...
}

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	wbemcli.h (include Wbemidl.h)
Libreria	Wbemuuid.lib
DLL	Wbemcore.dll