IWbemLocator::ConnectServer-Methode (wbemcli.h)

Artikel
08/27/2023

Die IWbemLocator::ConnectServer-Methode erstellt eine Verbindung über DCOM mit einem WMI-Namespace auf dem computer, der im strNetworkResource-Parameter angegeben ist.

SWbemLocator.ConnectServer kann mithilfe einer IPv6-Adresse im strNetworkResource-Parameter eine Verbindung mit Computern herstellen, auf denen IPv6 ausgeführt wird. Weitere Informationen finden Sie unter IPv6- und IPv4-Unterstützung in WMI.

Syntax

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

Parameter

[in] strNetworkResource

Zeiger auf einen gültigen BSTR , der den Objektpfad des richtigen WMI-Namespace enthält. Verwenden Sie für den lokalen Zugriff auf den Standardnamespace einen einfachen Objektpfad: "root\default" oder "\.\root\default". Wenn Sie über COM oder über ein mit Microsoft kompatibles Netzwerk auf den Standardnamespace auf einem Remotecomputer zugreifen möchten, schließen Sie den Computernamen „\myserver\root\default“ ein. Weitere Informationen finden Sie unter Beschreiben eines WMI-Namespaceobjektpfads. Der Computername kann auch ein DNS-Name oder eine IP-Adresse sein. Ab Windows Vista kann SWbemLocator.ConnectServer über eine IPv6-Adresse eine Verbindung mit Computern herstellen, auf denen IPv6 ausgeführt wird. Weitere Informationen finden Sie unter IPv6- und IPv4-Unterstützung in WMI.

[in] strUser

Zeiger auf einen gültigen BSTR, der den Benutzernamen enthält, den Sie für eine Verbindung benötigen. Ein NULL-Wert gibt den aktuellen Sicherheitskontext an. Wenn der Benutzername aus einer anderen Domäne als der aktuellen Domäne stammt, kann die Zeichenfolge den Domänennamen und den Benutzernamen enthalten, getrennt durch einen umgekehrten Schrägstrich.

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

Der strUser-Parameter darf keine leere Zeichenfolge sein. Wenn die Domäne in strAuthority angegeben ist, darf sie hier nicht angegeben werden. Die Angabe der Domäne in beiden Parametern führt zu einem ungültigen Parameterfehler.

Sie können das UpN-Format (User Principal Name) verwenden, das Username@DomainName ist, um strUser anzugeben.

[in] strPassword

Zeiger auf einen gültigen BSTR , der das Kennwort enthält, das Sie für eine Verbindung benötigen. Ein NULL-Wert gibt den aktuellen Sicherheitskontext an. Eine leere Zeichenfolge "" gibt ein gültiges Kennwort der Länge Null an.

[in] strLocale

Wenn NULL, wird das aktuelle Gebietsschema verwendet. Wenn nicht NULL, muss dieser Parameter ein gültiger BSTR sein, der das richtige Gebietsschema für den Informationsabruf angibt. Bei Microsoft-Gebietsschemabezeichnern lautet das Format der Zeichenfolge "MS_xxx", wobei xxx eine hexadezimale Zeichenfolge ist, die die lokale Identifizierung (LCID) angibt, z. B. würde englisch amerikanisch als "MS_409" angezeigt. Wenn ein ungültiges Gebietsschema angegeben wird, gibt die Methode WBEM_E_INVALID_PARAMETER zurück.

Windows 7: Wenn ein ungültiges Gebietsschema angegeben wird, wird das Standardgebietsschema des Servers verwendet, es sei denn, die Benutzeranwendung stellt ein vom Server unterstütztes Gebietsschema bereit.

[in] lSecurityFlags

Long-Wert, der verwendet wird, um Flagwerte an ConnectServer zu übergeben. Der Wert null (0) für diesen Parameter führt dazu, dass der Aufruf von ConnectServer erst zurückgegeben wird, nachdem die Verbindung mit dem Server hergestellt wurde. Dies kann dazu führen, dass Ihr Programm auf unbestimmte Zeit reagiert, wenn der Server unterbrochen wird. In der folgenden Liste sind die anderen gültigen Werte für lSecurityFlags aufgeführt.

WBEM_FLAG_CONNECT_REPOSITORY_ONLY (64 (0x40))

Für die interne Verwendung reserviert. Darf nicht verwendet werden.

WBEM_FLAG_CONNECT_USE_MAX_WAIT (128 (0x80))

Der ConnectServer-Aufruf wird in zwei Minuten oder weniger zurückgegeben. Verwenden Sie dieses Flag, um zu verhindern, dass Ihr Programm auf unbestimmte Zeit reagiert, wenn der Server ausgefallen ist.

[in] strAuthority

Dieser Parameter enthält den Namen der Domäne des zu authentifizierden Benutzers.

strAuthority kann die folgenden Werte aufweisen:

leer
Wenn Sie diesen Parameter leer lassen, wird die NTLM-Authentifizierung verwendet, und die NTLM-Domäne des aktuellen Benutzers wird verwendet. Wenn die Domäne in strUser angegeben ist, was der empfohlene Speicherort ist, darf sie hier nicht angegeben werden. Die Angabe der Domäne in beiden Parametern führt zu einem ungültigen Parameterfehler.
Kerberos:<principal name>
Die Kerberos-Authentifizierung wird verwendet, und dieser Parameter sollte einen Kerberos-Prinzipalnamen enthalten.
NTLMDOMAIN:<Domänenname>
Die NT LAN Manager-Authentifizierung wird verwendet, und dieser Parameter sollte einen NTLM-Domänennamen enthalten.

[in] pCtx

In der Regel ist dies NULL. Andernfalls ist dies ein Zeiger auf ein IWbemContext-Objekt , das von mindestens einem dynamischen Klassenanbieter erforderlich ist. Die Werte im Kontextobjekt müssen in der Dokumentation für die betreffenden Anbieter angegeben werden. Weitere Informationen zu diesem Parameter finden Sie unter Ausführen von Aufrufen an WMI.

[out] ppNamespace

Empfängt einen Zeiger auf ein IWbemServices-Objekt , das an den angegebenen Namespace gebunden ist. Dieser Zeiger weist eine positive Verweisanzahl auf. Der Aufrufer muss IWbemServices::Release für den Zeiger aufrufen, wenn er nicht mehr benötigt wird. Dieser Zeiger wird so festgelegt, dass er auf NULL zeigt, wenn ein Fehler auftritt.

Rückgabewert

Diese Methode gibt ein HRESULT zurück, das den Status des Methodenaufrufs angibt. In der folgenden Liste ist der in einem HRESULT enthaltene Wert aufgeführt.

COM-spezifische Fehlercodes werden möglicherweise zurückgegeben, wenn Netzwerkprobleme dazu führen, dass die Remoteverbindung mit WMI verloren geht.

Diese Fehlerrückgabecodes werden in der Datei "Wbemcli.h" im WMI-Abschnitt des Verzeichnisses PSDK \Include definiert. Weitere Informationen finden Sie unter WMI-Fehlerkonstanten.

Hinweise

Geben Sie strUser, strPassword oder strAuthority nicht an, wenn Sie eine Verbindung mit einem lokalen Namespace herstellen. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit WMI auf einem Remotecomputer.

Weitere Informationen zur Verwendung von ConnectServer finden Sie unter Erstellen einer Verbindung mit einem WMI-Namespace. Beachten Sie, dass die Verbindung mit IWbemLocator eine der Verbindungen ist, die Sie am Ende Ihrer Anwendung herunterfahren müssen, wie unter Bereinigen und Herunterfahren einer WMI-Anwendung beschrieben.

Beispiele

Mehrere Beispiele, die die ConnectServer-Methode verwenden, finden Sie unter WMI C++-Anwendungsbeispiele.

Im folgenden C++-Codebeispiel wird beschrieben, wie Sie smi2smir.xml verwenden, um eine Verbindung mit einem angegebenen Namespace herzustellen.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	wbemcli.h (include Wbemidl.h)
Bibliothek	Wbemuuid.lib
DLL	Wbemcore.dll