ConnectServerWmi-Funktion

Artikel
06/12/2023

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

WMI und Leistungsindikatoren (Referenz zur nicht verwalteten API)

Freigeben über