ExecNotificationQueryWmi-Funktion

  • Artikel

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