ConnectServerWmi-Funktion

  • Artikel

Erstellt über DCOM eine Verbindung mit einem WMI-Namespace auf einem angegebenen Computer.

Hinweis

Diese API ist ausschließlich für die interne Verwendung vorgesehen. Sie ist nicht für die Verwendung im Entwicklercode vorgesehen.

Syntax

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

Parameter

strNetworkResource
[in] Zeiger auf ein gültiges BSTR-Element, das den Objektpfad des korrekten WMI-Namespace enthält. Weitere Informationen finden Sie im Abschnitt Bemerkungen.

strUser
[in] Ein Zeiger auf ein gültiges BSTR-Element, das den Benutzernamen enthält. Ein null-Wert gibt den aktuellen Sicherheitskontext an. Wenn der Benutzer bzw. die Benutzerin nicht der aktuellen Domäne angehört, kann strUser auch die Domäne und den Benutzernamen (getrennt durch einen umgekehrten Schrägstrich) enthalten. strUser kann auch im UPN-Format (User Principal Name, Dienstprinzipalname) vorliegen – also beispielsweise als userName@domainName. Weitere Informationen finden Sie im Abschnitt Bemerkungen.

strPassword
[in] Ein Zeiger auf ein gültiges BSTR-Element, das das Kennwort enthält. null gibt den aktuellen Sicherheitskontext an. Eine leere Zeichenfolge („“) gibt ein gültiges Kennwort der Länge Null an.

strLocale
[in] Ein Zeiger auf ein gültiges BSTR-Element, das das korrekte Gebietsschema für den Abruf von Informationen angibt. Bei Microsoft-Gebietsschemabezeichnern hat die Zeichenfolge das Format „MS_xxx“, wobei xxx eine Zeichenfolge in hexadezimaler Form ist, die den Gebietsschemabezeichner (Locale Identifier, LCID) angibt. Bei Angabe eines ungültigen Gebietsschemas gibt die Methode WBEM_E_INVALID_PARAMETER zurück (außer unter Windows 7; hier wird stattdessen das Standardgebietsschema des Servers verwendet). Bei „null1“ wird das aktuelle Gebietsschema verwendet.

lSecurityFlags
[in] Flags, die an die ConnectServerWmi-Methode übergeben werden sollen. Ein Nullwert (0) für diesen Parameter führt dazu, dass der Aufruf von ConnectServerWmi erst abgeschlossen wird, nachdem eine Verbindung mit dem Server hergestellt wurde. Dies kann dazu führen, dass eine Anwendung für einen unbestimmten Zeitraum nicht reagiert, wenn der Server nicht verfügbar ist. Weitere gültige Werte:

Konstante Wert Beschreibung
CONNECT_REPOSITORY_ONLY 0x40 Für die interne Verwendung reserviert. Darf nicht verwendet werden.
WBEM_FLAG_CONNECT_USE_MAX_WAIT 0x80 ConnectServerWmi wird in maximal zwei Minuten abgeschlossen.

strAuthority
[in] Der Domänenname des Benutzers bzw. der Benutzerin. Die folgenden Werte sind möglich:

Wert Beschreibung
leer Die NTLM-Authentifizierung und die NTLM-Domäne des aktuellen Benutzers bzw. der aktuellen Benutzerin werden verwendet. Wenn die Domäne per strUser angegeben wird (empfohlen), darf sie hier nicht angegeben werden. Die Funktion gibt WBEM_E_INVALID_PARAMETER zurück, wenn Sie die Domäne in beiden Parametern angeben.
Kerberos:Prinzipalname Die Kerberos-Authentifizierung wird verwendet, und dieser Parameter enthält einen Kerberos-Prinzipalnamen.
NTLMDOMAIN:Domänenname Die NT-LAN-Manager-Authentifizierung wird verwendet, und dieser Parameter enthält einen NTLM-Domänennamen.

pCtx
[in] Dieser Parameter ist in der Regel null. Andernfalls handelt es sich um einen Zeiger auf ein IWbemContext-Objekt, das von mindestens einem Anbieter dynamischer Klassen benötigt wird.

ppNamespace
[out] Nach Abschluss der Funktion wird ein Zeiger auf ein IWbemServices-Objekt empfangen, das an den angegebenen Namespace gebunden ist. Bei einem Fehler wird auf null gezeigt.

impLevel
[in] Die Identitätswechselebene.

authLevel
[in] Die Autorisierungsstufe.

Rückgabewert

Die folgenden von dieser Funktion zurückgegebenen Werte werden in der Headerdatei WbemCli.h definiert oder können als Konstanten im Code definiert werden:

Konstante Wert Beschreibung
WBEM_E_FAILED 0x80041001 Es ist ein allgemeiner Fehler aufgetreten.
WBEM_E_INVALID_PARAMETER 0x80041008 Ein Parameter ist nicht gültig.
WBEM_E_OUT_OF_MEMORY 0x80041006 Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.
WBEM_S_NO_ERROR 0 Der Funktionsaufruf war erfolgreich.

Bemerkungen

Diese Funktion umschließt einen Aufruf der IWbemLocator::ConnectServer-Methode.

Für den lokalen Zugriff auf den Standardnamespace kann strNetworkResource ein einfacher Objektpfad sein: „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. Der Computername kann auch ein DNS-Name oder eine IP-Adresse sein. Die ConnectServerWmi-Funktion kann auch über eine IPv6-Adresse eine Verbindung mit Computern herstellen, auf denen IPv6 aktiv ist.

strUser darf keine leere Zeichenfolge sein. Wenn die Domäne in strAuthority angegeben ist, darf sie nicht auch in strUser enthalten sein. Andernfalls gibt die Funktion WBEM_E_INVALID_PARAMETER zurück.

Anforderungen

Plattformen: Informationen finden Sie unter Systemanforderungen.

Header: WMINet_Utils.idl

.NET Framework-Versionen: Seit Version 4.7.2 verfügbar

Siehe auch