ExecQueryWmi-Funktion

  • Artikel

Führt eine Abfrage zum Abrufen von Objekten aus.

Hinweis

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

Syntax

HRESULT ExecQueryWmi (
   [in] BSTR                    strQueryLanguage,
   [in] BSTR                    strQuery,
   [in] long                    lFlags,
   [in] IWbemContext*           pCtx,
   [out] IEnumWbemClassObject** ppEnum,
   [in] DWORD                   authLevel,
   [in] DWORD                   impLevel,
   [in] IWbemServices*          pCurrentNamespace,
   [in] BSTR                    strUser,
   [in] BSTR                    strPassword,
   [in] BSTR                    strAuthority
);

Parameter

strQueryLanguage
[in] Eine Zeichenfolge mit der gültigen Abfragesprache, die von der Windows-Verwaltung unterstützt wird. Sie muss „WQL“ lauten (Akronym für WMI Query Language).

strQuery
[in] Der Text der Abfrage. Dieser Parameter darf nicht null sein.

lFlags
[in] Eine Kombination von Flags, die das Verhalten dieser Funktion beeinflussen. Die folgenden Werte werden in der WbemCli.h-Headerdatei definiert, oder Sie können sie als Konstanten im Code definieren:

Konstante Wert Beschreibung
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x20000 Wenn festgelegt, ruft die Funktion die geänderten Qualifizierer ab, die im lokalisierten Namespace des Gebietsschemas der aktuellen Verbindung gespeichert sind.
Wenn nicht festgelegt, ruft die Funktion nur die Qualifizierer ab, die im unmittelbaren Namespace gespeichert sind.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 Das Flag verursacht einen halbsynchronen Aufruf.
WBEM_FLAG_FORWARD_ONLY 0x20 Die Funktion gibt einen Vorwärtsenumerator zurück. In der Regel sind Vorwärtsenumeratoren schneller und verbrauchen weniger Arbeitsspeicher als herkömmliche Enumeratoren, lassen jedoch keine Aufrufe von Klonen zu.
WBEM_FLAG_BIDIRECTIONAL 0 WMI behält die Zeiger auf Objekte in der Enumeration bei, bis sie freigegeben werden.
WBEM_FLAG_ENSURE_LOCATABLE 0x100 Stellt sicher, dass alle zurückgegebenen Objekte genügend Informationen enthalten, sodass Systemeigenschaften wie __PATH, __RELPATH und __SERVER nicht null sind.
WBEM_FLAG_PROTOTYPE 2 Dieses Flag wird für das Erstellen von Prototypen verwendet. Es führt die Abfrage nicht aus und gibt stattdessen ein Objekt zurück, das wie ein typisches Ergebnisobjekt aussieht.
WBEM_FLAG_DIRECT_READ 0x200 Bewirkt den direkten Zugriff auf den Anbieter für die angegebene Klasse ohne Berücksichtigung der übergeordneten Klasse oder Unterklassen.

Die empfohlenen Flags sind WBEM_FLAG_RETURN_IMMEDIATELY und WBEM_FLAG_FORWARD_ONLY für optimale Leistung.

pCtx
[in] In der Regel ist dieser Wert null. Andernfalls handelt es sich um einen Zeiger auf eine IWbemContext-Instanz, die von dem Anbieter verwendet werden kann, der die angeforderten Klassen bereitstellt.

ppEnum
[out] Wenn kein Fehler auftritt, wird der Zeiger auf den Enumerator empfangen, mit dem der Aufrufer die Instanzen im Resultset der Abfrage abrufen kann. Die Abfrage kann über ein Resultset mit null Instanzen verfügen. Weitere Informationen finden Sie im Abschnitt Hinweise.

authLevel
[in] Die Autorisierungsstufe.

impLevel
[in] Die Identitätswechselstufe.

pCurrentNamespace
[in] Ein Zeiger auf ein IWbemServices-Objekt, das den aktuellen Namespace darstellt.

strUser
[in] Der Benutzername. Weitere Informationen finden Sie in der ConnectServerWmi-Funktion.

strPassword
[in] Das Kennwort. Weitere Informationen finden Sie in der ConnectServerWmi-Funktion.

strAuthority
[in] Der Domänenname der Benutzer*innen. Weitere Informationen finden Sie in der ConnectServerWmi-Funktion.

Rückgabewert

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

Konstante Wert Beschreibung
WBEM_E_ACCESS_DENIED 0x80041003 Die Benutzer*innen verfügen nicht über die Berechtigung, eine oder mehrere der Klassen anzuzeigen, die die Funktion zurückgeben kann.
WBEM_E_FAILED 0x80041001 Ein unbekannter Fehler ist aufgetreten.
WBEM_E_INVALID_PARAMETER 0x80041008 Ein Parameter ist nicht gültig.
WBEM_E_INVALID_QUERY 0x80041017 Die Abfrage weist einen Syntaxfehler auf.
WBEM_E_INVALID_QUERY_TYPE 0x80041018 Die angeforderte Abfragesprache wird nicht unterstützt.
WBEM_E_QUOTA_VIOLATION 0x8004106c Die Abfrage ist zu komplex.
WBEM_E_OUT_OF_MEMORY 0x80041006 Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.
WBEM_E_SHUTTING_DOWN 0x80041033 WMI wurde wahrscheinlich beendet und startet neu. Rufen Sie ConnectServerWmi erneut auf.
WBEM_E_TRANSPORT_FAILURE 0x80041015 Fehler bei der Remoteprozeduraufruf-Verbindung (RPC) zwischen dem aktuellen Prozess und WMI.
WBEM_E_NOT_FOUND 0x80041002 In der Abfrage ist eine Klasse angegeben, die nicht vorhanden ist.
WBEM_S_NO_ERROR 0 Der Funktionsaufruf war erfolgreich.

Bemerkungen

Diese Funktion umschließt einen Aufruf der IWbemServices::ExecQuery-Methode.

Diese Funktion verarbeitet die im strQuery-Parameter angegebene Abfrage und erstellt einen Enumerator, über den der Aufrufer auf die Abfrageergebnisse zugreifen kann. Der Enumerator ist ein Zeiger auf eine IEnumWbemClassObject-Schnittstelle. Die Abfrageergebnisse sind Instanzen von Klassenobjekten, die über die IWbemClassObject-Schnittstelle zur Verfügung gestellt werden.

Es gibt Grenzwerte für die Anzahl von AND- und OR-Schlüsselwörtern, die in WQL-Abfragen verwendet werden können. Wenn eine große Anzahl von WQL-Schlüsselwörtern in einer komplexen Abfrage verwendet wird, kann dies dazu führen, dass WMI den WBEM_E_QUOTA_VIOLATION-Fehlercode (oder 0x8004106c) als HRESULT-Wert zurückgibt. Der Grenzwert für WQL-Schlüsselwörter hängt davon ab, wie komplex die Abfrage ist.

Wenn der Funktionsaufruf fehlschlägt, können Sie zusätzliche Fehlerinformationen abrufen, indem Sie die GetErrorInfo-Funktion aufrufen.

Anforderungen

Plattformen: Informationen finden Sie unter Systemanforderungen.

Header: WMINet_Utils.idl

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

Siehe auch