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

Article
08/27/2023

La méthode IWbemLocator ::ConnectServer crée une connexion via DCOM à un espace de noms WMI sur l’ordinateur spécifié dans le paramètre strNetworkResource .

SWbemLocator.ConnectServer peut se connecter à des ordinateurs exécutant IPv6 à l’aide d’une adresse IPv6 dans le paramètre strNetworkResource . Pour plus d’informations, consultez Prise en charge d’IPv6 et d’IPv4 dans WMI.

Syntaxe

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

Paramètres

[in] strNetworkResource

Pointeur vers un BSTR valide qui contient le chemin d’accès de l’objet de l’espace de noms WMI correct. Pour l’accès local à l’espace de noms par défaut, utilisez un chemin d’objet simple : « root\default » ou « \.\root\default ». Pour accéder à l’espace de noms par défaut sur un ordinateur distant à l’aide d’une mise en réseau compatible COM ou Microsoft, incluez le nom de l’ordinateur : « \myserver\root\default ». Pour plus d’informations, consultez Description d’un chemin d’objet d’espace de noms WMI. Le nom de l’ordinateur peut également être un nom DNS ou une adresse IP. À compter de Windows Vista, SWbemLocator.ConnectServer peut se connecter à des ordinateurs exécutant IPv6 à l’aide d’une adresse IPv6. Pour plus d’informations, consultez Prise en charge d’IPv6 et d’IPv4 dans WMI.

[in] strUser

Pointeur vers un BSTR valide, qui contient le nom d’utilisateur dont vous avez besoin pour une connexion. Une valeur NULL indique le contexte de sécurité actuel. Si le nom d’utilisateur provient d’un domaine différent du domaine actuel, la chaîne peut contenir le nom de domaine et le nom d’utilisateur séparés par une barre oblique inverse.

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

Le paramètre strUser ne peut pas être une chaîne vide. Notez que si le domaine est spécifié dans strAuthority, il ne doit pas être spécifié ici. La spécification du domaine dans les deux paramètres entraîne une erreur de paramètre non valide.

Vous pouvez utiliser le format de nom d’utilisateur principal (UPN), qui est Username@DomainName pour spécifier le strUser.

[in] strPassword

Pointeur vers un BSTR valide qui contient le mot de passe dont vous avez besoin pour une connexion. Une valeur NULL indique le contexte de sécurité actuel. Une chaîne vide « » spécifie un mot de passe de longueur nulle valide.

[in] strLocale

Si la valeur est NULL, les paramètres régionaux actuels sont utilisés. S’il n’est pas NULL, ce paramètre doit être un BSTR valide, ce qui indique les paramètres régionaux appropriés pour la récupération des informations. Pour les identificateurs de paramètres régionaux Microsoft, le format de la chaîne est « MS_xxx », où xxx est une chaîne au format hexadécimal qui indique l’identification locale (LCID). Par exemple, l’anglais américain apparaît comme « MS_409 ». Si un paramètre régional non valide est spécifié, la méthode retourne WBEM_E_INVALID_PARAMETER.

Windows 7 : Si un paramètre régional non valide est spécifié, les paramètres régionaux par défaut du serveur sont utilisés, sauf s’il existe des paramètres régionaux pris en charge par le serveur fournis par l’application utilisateur.

[in] lSecurityFlags

Valeur longue utilisée pour passer des valeurs d’indicateur à ConnectServer. La valeur zéro (0) pour ce paramètre entraîne le retour de l’appel à ConnectServer uniquement après l’établissement de la connexion au serveur. Cela peut entraîner l’interruption de la réponse de votre programme indéfiniment si le serveur est défectueux. La liste suivante répertorie les autres valeurs valides pour lSecurityFlags.

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40))

Réservé à un usage interne. Ne pas utiliser.

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80))

L’appel ConnectServer est retourné dans 2 minutes ou moins. Utilisez cet indicateur pour éviter que votre programme cesse de répondre indéfiniment si le serveur est défectueux.

[in] strAuthority

Ce paramètre contient le nom du domaine de l’utilisateur à authentifier.

strAuthority peut avoir les valeurs suivantes :

blank
Si vous laissez ce paramètre vide, l’authentification NTLM est utilisée et le domaine NTLM de l’utilisateur actuel est utilisé. Si le domaine est spécifié dans strUser, qui est l’emplacement recommandé, il ne doit pas être spécifié ici. La spécification du domaine dans les deux paramètres entraîne une erreur de paramètre non valide.
Kerberos :<nom principal>
L’authentification Kerberos est utilisée et ce paramètre doit contenir un nom de principal Kerberos.
NTLMDOMAIN :<nom de domaine>
L’authentification NT LAN Manager est utilisée et ce paramètre doit contenir un nom de domaine NTLM.

[in] pCtx

En règle générale, il s’agit de la valeur NULL. Sinon, il s’agit d’un pointeur vers un objet IWbemContext requis par un ou plusieurs fournisseurs de classes dynamiques. Les valeurs de l’objet de contexte doivent être spécifiées dans la documentation des fournisseurs en question. Pour plus d’informations sur ce paramètre, consultez Effectuer des appels à WMI.

[out] ppNamespace

Reçoit un pointeur vers un objet IWbemServices lié à l’espace de noms spécifié. Ce pointeur a un nombre de références positif. L’appelant doit appeler IWbemServices ::Release sur le pointeur lorsqu’il n’est plus nécessaire. Ce pointeur est défini pour pointer sur NULL en cas d’erreur.

Valeur retournée

Cette méthode retourne une valeur HRESULT qui indique l’état de l’appel de méthode. La liste suivante répertorie la valeur contenue dans un HRESULT.

Des codes d’erreur spécifiques à COM peuvent être retournés si des problèmes réseau vous font perdre la connexion à distance à WMI.

Ces codes de retour d’erreur sont définis dans le fichier Wbemcli.h de la section WMI du répertoire PSDK \Include. Pour plus d’informations, consultez Constantes d’erreur WMI.

Remarques

Ne spécifiez pas strUser, strPassword ou strAuthority lors de l’établissement d’une connexion à un espace de noms local. Pour plus d’informations, consultez Connexion à WMI sur un ordinateur distant.

Pour plus d’informations sur l’utilisation de ConnectServer, consultez Création d’une connexion à un espace de noms WMI. Notez que la connexion à IWbemLocator est l’une des connexions que vous devez arrêter à la fin de votre application, comme décrit dans Nettoyage et arrêt d’une application WMI.

Exemples

Pour obtenir plusieurs exemples qui utilisent la méthode ConnectServer , consultez Exemples d’applications WMI C++.

L’exemple de code C++ suivant décrit comment utiliser smi2smir.xml pour se connecter à un espace de noms spécifié.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	wbemcli.h (inclure Wbemidl.h)
Bibliothèque	Wbemuuid.lib
DLL	Wbemcore.dll