IWbemServices::CreateInstanceEnumAsync-Methode (wbemcli.h)
Die IWbemServices::CreateInstanceEnumAsync-Methode erstellt einen Enumerator, der die Instanzen einer angegebenen Klasse gemäß den vom Benutzer angegebenen Auswahlkriterien asynchron zurückgibt. Diese Methode unterstützt einfache WMI Query Language(WQL)-Abfragen. Komplexere Abfragen können mit der IWbemServices::ExecQueryAsync-Methode verarbeitet werden.
Syntax
HRESULT CreateInstanceEnumAsync(
[in] const BSTR strFilter,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Parameter
[in] strFilter
Gültiger BSTR , der den Namen der Klasse enthält, für die Instanzen gewünscht werden. Dieser Parameter darf nicht NULL sein.
[in] lFlags
Dieser Parameter kann einen der folgenden Werte annehmen.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Wenn dieses Flag festgelegt ist, ruft die Windows-Verwaltungsinstrumentation (WMI) die geänderten Qualifizierer ab, die im lokalisierten Namespace des Gebietsschemas der aktuellen Verbindung gespeichert sind. Wenn nicht festgelegt, werden nur die Qualifizierer abgerufen, die im unmittelbaren Namespace gespeichert sind.
WBEM_FLAG_DEEP
Dieses Flag erzwingt, dass die Enumeration Instanzen dieser und aller Unterklassen in die Hierarchie einschließt.
WBEM_FLAG_SHALLOW
Dieses Flag erzwingt, dass die Enumeration nur reine Instanzen dieser Klasse enthält, wobei alle Instanzen von Unterklassen ausgeschlossen werden, die Eigenschaften bereitstellen, die in dieser Klasse nicht gefunden wurden.
WBEM_FLAG_SEND_STATUS
Dieses Flag registriert bei der Windows-Verwaltung eine Anforderung zum Empfangen von zwischengeschalteten status Berichten über die Clientimplementierung von IWbemObjectSink::SetStatus. Die Anbieterimplementierung muss die Berichterstellung für zwischengeschaltete status unterstützen, damit dieses Flag das Verhalten ändern kann.
WBEM_FLAG_BIDIRECTIONAL
Dieses Flag bewirkt, dass die Windows-Verwaltung Zeiger auf Objekte der Enumeration behält, bis der Client den Enumerator freigibt.
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
Normalerweise NULL. Andernfalls ist dies ein Zeiger auf ein IWbemContext-Objekt , das von dem Anbieter verwendet werden kann, der die angeforderten Instanzen zurückgibt. Die Werte im Kontextobjekt müssen in der Dokumentation für den betreffenden Anbieter angegeben werden. Weitere Informationen finden Sie unter Richten von Aufrufen an WMI.
[in] pResponseHandler
Zeiger auf die Implementierung von IWbemObjectSink durch den Aufrufer. Dieser Handler empfängt die Objekte, sobald sie verfügbar werden. Wenn 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. Die Windows-Verwaltung ruft AddRef nur auf dem Zeiger auf, wenn WBEM_S_NO_ERROR zurückgegeben wird. In Fällen, in denen ein Fehlercode zurückgegeben wird, ist die Verweisanzahl identisch mit der beim Eintrag. Weitere Informationen finden Sie unter Aufrufen einer Methode.
Rückgabewert
Diese Methode gibt ein HRESULT zurück, das den Status des Methodenaufrufs angibt. Die folgende Liste listet den Wert auf, der in einem HRESULT enthalten ist.
Bei einem Fehler können Sie weitere Informationen aus der COM-Funktion GetErrorInfo abrufen.
COM-spezifische Fehlercodes können auch zurückgegeben werden, wenn Netzwerkprobleme dazu führen, dass die Remoteverbindung mit der Windows-Verwaltung verloren geht.
Ein instance-Anbieter kann entweder mit dem Rückgabecode von CreateInstanceEnumAsync oder über einen Aufruf von SetStatus über pResponseHandler einen Erfolg oder Fehler melden. Wenn Sie SetStatus aufrufen, hat der über pResponseHandler gesendete Rückgabecode Vorrang.
Wenn CreateInstanceEnumAsyncWBEM_S_NO_ERROR zurückgibt, wartet WMI auf ein Ergebnis der SetStatus-Methode des Antworthandlers. WMI wartet auf unbegrenzte Zeit bei einer lokalen Verbindung oder bis ein Timeout der Remoteverbindung auftritt.
Hinweise
Die IWbemObjectSink::SetStatus-Methode wird aufgerufen, um das Ende des Resultsets anzugeben. Es kann auch ohne eingreifende Aufrufe von IWbemObjectSink::Geben Sie an, ob Fehlerbedingungen auftreten.
Da der Rückruf möglicherweise nicht auf der gleichen Authentifizierungsebene zurückgegeben wird, die der Client erfordert, wird empfohlen, die semisynchrone Kommunikation anstelle der asynchronen Kommunikation zu verwenden.
Weitere Informationen finden Sie unter IWbemServices::CreateInstanceEnum und Aufrufen einer Methode.
Beispiele
Das folgende Beispiel zeigt, wie Sie CreateInstanceEnumAsync implementieren.
#define NUM_OF_INSTANCES 3
HRESULT CStdProvider::CreateInstanceEnumAsync(
/* [in] */ BSTR strClass,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
IWbemClassObject *pClass = 0;
IWbemClassObject *pNextInst = 0;
// Assume there is an IWbemServices pointer available to
// retrieve the class definition.
HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
if (hRes)
return hRes;
// Now loop through the private source and create each instance.
for (int i = 0; i < NUM_OF_INSTANCES; i++)
{
// Prepare an empty object to receive the class definition.
pClass->SpawnInstance(0, &pNextInst);
// Create the instance.
// For example, create the instance in a
// FillInst method you implement:
/*FillInst(pNextInst);*/
// Deliver the class to WMI.
pResponseHandler->Indicate(1, &pNextInst);
pNextInst->Release();
}
// Send a finish message to WMI.
pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);
// Free memory resources.
SysFreeString(strClass);
pClass->Release();
m_pSvc->Release();
return WBEM_S_NO_ERROR;
}
Im vorherigen Beispiel ruft der instance-Anbieter einen Thread von WMI ab, um alle erforderlichen Vorgänge auszuführen. Möglicherweise möchten Sie die AddRef-Methode aufrufen und einen weiteren Thread zum Übermitteln der Objekte im Resultset erstellen. Das Erstellen eines weiteren Threads ermöglicht es dem aktuellen Thread, zu WMI zurückzukehren, ohne den Threadpool zu erschöpfen. Ob der Anbieter den Einzelthreadentwurf gegenüber dem Dual-Thread-Design wählt, hängt davon ab, wie lange der Anbieter den WMI-Thread verwenden möchte. Es gibt keine festen Regeln. Experimentieren kann Ihnen helfen, festzustellen, wie sich Ihr Entwurf auf die WMI-Leistung auswirkt.
Anforderungen
| Anforderung | Wert |
|---|---|
| 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 |