IWbemServices::ExecQueryAsync-Methode (wbemcli.h)
Die IWbemServices::ExecQueryAsync-Methode führt eine Abfrage aus, um Objekte asynchron abzurufen.
Syntax
HRESULT ExecQueryAsync(
[in] const BSTR strQueryLanguage,
[in] const BSTR strQuery,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Parameter
[in] strQueryLanguage
GültigeS BSTR, das eine der Abfragesprachen enthält, die die Windows-Verwaltungsinstrumentation (WMI) unterstützt. Dies muss "WQL" sein.
[in] strQuery
Gültiger BSTR , der den Text der Abfrage enthält. Dies darf nicht NULL sein. Wenn Sie einen instance-Anbieter implementieren, kann Ihr Anbieter die Abfrage ablehnen, weil sie zu komplex ist. Wenn ein Anbieter feststellt, dass eine Abfrage zu komplex ist, kann WMI den Anbieter mit einer einfachen Abfrage wiederholen oder die Obermenge der Abfrageinstanzen abrufen und aufzählen.
Weitere Informationen zum Erstellen von WMI-Abfragezeichenfolgen finden Sie unter Abfragen mit WQL sowie in der Referenz zu WQL.
[in] lFlags
Dieser Parameter kann einen der folgenden Werte annehmen.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Wenn dieses Flag festgelegt ist, ruft WMI die geänderten Qualifizierer ab, die im lokalisierten Namespace des Gebietsschemas der aktuellen Verbindung gespeichert sind. Wenn nicht festgelegt, werden nur die im unmittelbaren Namespace gespeicherten Qualifizierer abgerufen.
WBEM_FLAG_BIDIRECTIONAL
Dieses Flag bewirkt, dass WMI Zeiger auf Objekte der Enumeration behält, bis der Client den Enumerator freigibt.
WBEM_FLAG_SEND_STATUS
Dieses Flag registriert eine Anforderung bei WMI, um zwischengeschaltete status Berichte über die Implementierung von IWbemObjectSink::SetStatus auf dem Client zu empfangen. Die Anbieterimplementierung muss zwischengeschaltete status Berichterstellung unterstützen, damit sich dieses Flag ändert.
WBEM_FLAG_ENSURE_LOCATABLE
Dieses Flag stellt sicher, dass zurückgegebene Objekte genügend Informationen enthalten, sodass die Systemeigenschaften wie __PATH, __RELPATH und __SERVER nicht NULL sind.
WBEM_FLAG_PROTOTYPE
Dieses Flag wird für das Erstellen von Prototypen verwendet. Die Abfrage wird nicht ausgeführt, sondern ein Objekt zurückgegeben, das wie ein typisches Ergebnisobjekt aussieht.
WBEM_FLAG_DIRECT_READ
Dieses Flag bewirkt den direkten Zugriff auf den Anbieter für die angegebene Klasse ohne Berücksichtigung der übergeordneten Klasse oder Unterklassen.
[in] pCtx
In der Regel NULL. Andernfalls ist dies ein Zeiger auf ein IWbemContext-Objekt , das der Anbieter verwenden kann, um die angeforderten Klassen oder Instanzen zurückzugeben. Die Werte im Kontextobjekt müssen in der Dokumentation für den Anbieter angegeben werden. Weitere Informationen zu diesem Parameter finden Sie unter Ausführen von Aufrufen an WMI.
[in] pResponseHandler
Zeiger auf die Implementierung von IWbemObjectSink des Aufrufers. Dieser Handler empfängt die Objekte im Abfrageresultset, sobald sie verfügbar sind. Wenn ein Fehlercode zurückgegeben wird, wird der angegebene IWbemObjectSink-Zeiger nicht verwendet. Wenn WBEM_S_NO_ERROR zurückgegeben wird, wird die IWbemObjectSink-Implementierung des Benutzers aufgerufen, um das Ergebnis des Vorgangs anzugeben. Windows-Verwaltungsinstrumentation (WMI) ruft IWbemObjectSink::Indicate mit den Objekten beliebig oft auf, gefolgt von einem einzelnen Aufruf von IWbemObjectSink::SetStatus, um die endgültige status anzugeben.
WMI ruft nur AddRef auf den Zeiger auf, wenn WBEM_S_NO_ERROR zurückgibt. Wenn ein Fehlercode zurückgegeben wird, ist die Verweisanzahl identisch mit der beim Eintrag. Eine ausführliche Erläuterung der Methoden des asynchronen Aufrufens finden Sie unter Aufrufen einer Methode.
Rückgabewert
Diese Methode gibt ein HRESULT zurück, das den Status des Methodenaufrufs angibt. In der folgenden Liste ist der in einem HRESULT enthaltene Wert aufgeführt.
Wenn ein Fehler auftritt, können Sie Informationen von der COM-Funktion GetErrorInfo abrufen.
Andere Fehlercodes werden an die Objektsenke zurückgegeben, die durch den pResponseHandler-Parameter angegeben wird.
Com-spezifische Fehlercodes werden möglicherweise zurückgegeben, wenn Netzwerkprobleme dazu führen, dass die Remoteverbindung mit WMI verloren geht.
Wenn dies abgeschlossen ist, kann ein instance Anbieter entweder mit dem Rückgabecode von ExecQueryAsync oder über einen Aufruf von SetStatus über pResponseHandler Erfolg oder Fehler melden. Wenn Sie SetStatus aufrufen, hat der über pResponseHandler gesendete Rückgabecode Vorrang.
Hinweise
Es gibt Grenzwerte für die Anzahl von AND- und OR-Schlüsselwörtern, die in WQL-Abfragen verwendet werden können. Eine große Anzahl an WQL-Schlüsselwörtern, die in einer komplexen Abfrage verwendet werden, kann dazu führen, dass WMI den Fehlercode WBEM_E_QUOTA_VIOLATION als HRESULT-Wert zurückgibt. Der Grenzwert für WQL-Schlüsselwörter hängt davon ab, wie komplex die Abfrage ist.
Die IWbemObjectSink::Indicate-Methode des Aufrufers kann aufgerufen werden, um zeitweilige status zu melden. Die IWbemObjectSink::SetStatus-Methode wird aufgerufen, um das Ende des Resultsets anzugeben.
Wenn ein Anbieter die Abfrageverarbeitung nicht unterstützt, kann sie von WMI unterstützt werden. Eine Anbieterimplementierung der Abfrageverarbeitung ist jedoch wahrscheinlich effizienter als die WMI-Version. Um Abfragen zu unterstützen, muss Ihr instance Anbieter die ExecQueryAsync-Methode implementieren. Wenn ein Anbieter ExecQueryAsync unterstützt, sendet WMI eine einfache unäre SELECT-Abfrage direkt über den strQuery-Parameter an den Anbieter, und der Anbieter muss die Abfrage analysieren und die relevanten Instanzen zurückgeben. Der Anbieter muss die Abfrage analysieren, da WMI die Abfrage nicht ändert , auch wenn die Abfrage in WQL geschrieben wird.
Um WMI für die Abfrageverarbeitung zu verwenden, legen Sie die QuerySupportLevels-Eigenschaft nicht in Ihrem __InstanceProviderRegistration fest. Wenn Sie dies tun, ruft WMI Ihre Implementierung von CreateInstanceEnumAsync auf und filtert die Ergebnisse nach, sodass der Aufrufer nur die Instanzen abruft, die die Abfragekriterien erfüllen.
Das folgende Beispiel zeigt eine typische instance Anbieterimplementierung von ExecQueryAsync. Die IWbemObjectSink::SetStatus-Methode wird aufgerufen, um das Ende des Resultsets anzugeben. Er kann auch ohne dazwischen liegende Aufrufe von IWbemObjectSink::Geben Sie an , ob Fehlerbedingungen auftreten.
Da der Rückruf möglicherweise nicht auf derselben Authentifizierungsebene zurückgegeben wird, wie es für den Client erforderlich ist, empfiehlt es sich, anstelle der asynchronen Kommunikation eine semisynchrone Kommunikation zu verwenden. Wenn Sie asynchrone Kommunikation benötigen, finden Sie weitere Informationen unter Aufrufen einer Methode.
Weitere Informationen finden Sie unter IWbemServices::ExecQuery und Aufrufen einer Methode.
HRESULT CStdProvider::ExecQueryAsync(
/* [in] */ BSTR strQueryLanguage,
/* [in] */ BSTR strQuery,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
IWbemClassObject *pClass = 0;
// Parse the query.
// You must implement ParseQuery().
if (!ParseQuery(strQuery)) return WBEM_E_PROVIDER_NOT_CAPABLE;
// Assume there is an IWbemServices pointer (m_pSvc) available to
// retrieve the class definition.
HRESULT hRes = m_pSvc->GetObject(L"ClassName", 0, NULL, &pClass, 0);
if (FAILED(hRes))
return hRes;
// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
int iNumInst = GetNumberInst();
// Now loop through the private source and create each
// instance which is part of the result set of the query.
for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
{
// Prepare an empty object to receive the class definition.
IWbemClassObject *pNextInst = 0;
hRes = pClass->SpawnInstance(0, &pNextInst);
// Create the instance.
// You must implement FillInst().
/*FillInst(pNextInst, iCnt);*/
// Deliver the class to WMI.
pResponseHandler->Indicate(1, &pNextInst);
pNextInst->Release( );
}
// Clean up memory
pClass->Release();
// Send finish message to WMI.
pResponseHandler->SetStatus(0, hRes, 0, 0);
return hRes;
}
Im vorherigen Beispiel ruft der instance Anbieter einen Thread von WMI ab, um die erforderlichen Synchronisierungsvorgänge auszuführen. Sie können die AddRef-Methode der Senke aufrufen und einen weiteren Thread erstellen, um die Objekte im Resultset bereitzustellen. Durch das Erstellen eines weiteren Threads kann der aktuelle Thread zu WMI zurückkehren, ohne den Threadpool zu erschöpfen. Ob der Anbieter den Einzelthreadentwurf oder den Dual-Thread-Entwurf auswählt, hängt davon ab, wie lange der Anbieter die Verwendung des WMI-Threads plant. Es gibt keine festen Regeln. Experimentieren kann Ihnen helfen, zu bestimmen, wie sich Ihr Entwurf auf die WMI-Leistung auswirkt.
// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);
// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista |
| Unterstützte Mindestversion (Server) | Windows Server 2008 |
| Zielplattform | Windows |
| Kopfzeile | wbemcli.h (include Wbemidl.h) |
| Bibliothek | Wbemuuid.lib |
| DLL | Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll |