ExecNotificationQueryWmi-Funktion

Artikel
06/12/2023

Führt eine Abfrage zum Empfangen von Ereignissen aus. Der Aufruf wird sofort zurückgegeben, und der Aufrufer kann den zurückgegebenen Enumerator nach Ereignissen abfragen, wenn sie eintreffen. Durch Freigeben des zurückgegebenen Enumerators wird die Abfrage abgebrochen.

Hinweis

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

Syntax

HRESULT ExecNotificationQueryWmi (
   [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. Hierbei handelt es sich um das Akronym für „WMI Query Language“ (WMI-Abfragesprache).

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

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

Konstante	Wert	Beschreibung
`WBEM_FLAG_RETURN_IMMEDIATELY`	0x10	Das Flag verursacht einen halbsynchronen Aufruf. Ist dieses Flag nicht festgelegt, ist der Aufruf nicht erfolgreich. Das liegt daran, dass Ereignisse kontinuierlich empfangen werden, was bedeutet, dass Benutzer*innen den zurückgegebenen Enumerator abfragen müssen. Wenn dieser Aufruf auf unbestimmte Zeit blockiert wird, ist dies nicht möglich.
`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 Clone zu.

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 Ereignisse 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. Weitere Informationen finden Sie im Abschnitt Bemerkungen.

authLevel
[in] Die Autorisierungsstufe.

impLevel
[in] Die Identitätswechselebene.

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

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

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

strAuthority
[in] Der Domänenname des Benutzers bzw. der Benutzerin. Weitere Informationen finden Sie unter ConnectServerWmi-Funktion.

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_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_CLASS`	0x80041010	In der Abfrage ist eine Klasse angegeben, die nicht vorhanden ist.
`WBEMESS_E_REGISTRATION_TOO_PRECISE`	0x80042002	Es wurde eine zu genaue Übermittlung von Ereignissen angefordert. Eine größere Abfragetoleranz muss angegeben werden.
`WBEMESS_E_REGISTRATION_TOO_BROAD`	0x80042001	Von der Abfrage werden mehr Informationen angefordert als die Windows-Verwaltung bereitstellen kann. Dieses `HRESULT` wird zurückgegeben, wenn eine Ereignisabfrage eine Anforderung zur Folge hat, die alle Objekte in einem Namespace abfragt.
`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 RPC-Verbindung (Remote Procedure Call, RPC) zwischen dem aktuellen Prozess und WMI.
`WBEM_E_UNPARSABLE_QUERY`	0x80041058	Die Abfrage kann nicht analysiert werden.
`WBEM_S_NO_ERROR`	0	Der Funktionsaufruf war erfolgreich.

Bemerkungen

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

Nachdem die Funktion zurückgegeben wurde, übergibt der Aufrufer das zurückgegebene ppEnum-Objekt in regelmäßigen Abständen an die Next-Funktion, um zu überprüfen, ob Ereignisse verfügbar sind.

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 Fehlercode WBEM_E_QUOTA_VIOLATION (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 nicht erfolgreich war, 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

WMI und Leistungsindikatoren (Referenz zur nicht verwalteten API)

Freigeben über