IWbemServices::CreateClassEnumAsync-Methode (wbemcli.h)

Artikel
08/27/2023

Die IWbemServices::CreateClassEnumAsync-Methode gibt eine Enumeration aller Klassen zurück, die der Klassenanbieter unterstützt. Der Klassenanbieter erstellt jede Klassendefinition von Grund auf neu und gibt nur Unterklassen der angeforderten Klasse zurück. Als asynchrone Methode gibt CreateClassEnumAsync sofort eine status Nachricht zurück und aktualisiert dann die Senke, die über den pResponseHandler-Parameter übergeben wird – falls erforderlich.

Wenn ein Aufruf erfolgreich ist, ruft WMI AddRef auf dem Zeiger pResponseHandler auf, gibt sofort zurück, und ruft dann asynchron pResponseHandler auf– >Angeben von einem anderen Thread mit Klassendefinitionen, bis die Abfrage erfüllt ist.

Syntax

HRESULT CreateClassEnumAsync(
  [in] const BSTR      strSuperclass,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Parameter

[in] strSuperclass

Wenn nicht NULL oder leer, gibt dieser Parameter einen übergeordneten Klassennamen an. Nur Klassen, die Unterklassen dieser Klasse sind, werden im Enumerator zurückgegeben. Wenn NULL oder leer und lFlagsWBEM_FLAG_SHALLOW ist, werden nur Klassen der obersten Ebene zurückgegeben, die keine übergeordnete Klasse aufweisen. Wenn es NULL oder leer ist und lFlagsWBEM_FLAG_DEEP ist, werden alle Klassen innerhalb des Namespace zurückgegeben.

[in] lFlags

Mindestens einer der folgenden Werte ist gültig.

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 aktuellen Verbindungsgebietsschemas gespeichert sind. Wenn nicht festgelegt, werden nur die Qualifizierer abgerufen, die im unmittelbaren Namespace gespeichert sind.

WBEM_FLAG_BIDIRECTIONAL

Dieses Flag bewirkt, dass WMI Zeiger auf Objekte der Enumeration behält, bis der Client den Enumerator freigibt.

WBEM_FLAG_DEEP

Dieses Flag erzwingt, dass die Enumeration diese und alle 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 eine Anforderung in WMI 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.

Hinweis Wenn strSuperclassNULL oder leer ist und WBEM_FLAG_DEEP angegeben ist, werden alle Klassen zurückgegeben.

[in] pCtx

Normalerweise NULL. Andernfalls ist dies ein Zeiger auf ein IWbemContext-Objekt , das vom Anbieter verwendet werden kann, der die angeforderten Klassen zurückgibt. Die Werte im Kontextobjekt müssen in der Dokumentation für den Anbieter angegeben werden. Weitere Informationen zu diesem Parameter finden Sie unter Tätigen von Aufrufen von WMI.

[in] pResponseHandler

Zeiger auf die Aufruferimplementierung von IWbemObjectSink. Dieser Handler empfängt die Objekte, sobald sie verfügbar werden, mithilfe der IWbemObjectSink::Indicate-Methode . Wenn keine Objekte verfügbar sind, wird die IWbemObjectSink::SetStatus-Methode von WMI aufgerufen. 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. WMI ruft AddRef nur auf dem Zeiger auf, wenn WBEM_S_NO_ERROR zurückgibt. Wenn ein Fehlercode zurückgegeben wird, ist die Verweisanzahl identisch mit keinem Eintrag. Eine ausführliche Erläuterung zu diesem Parameter finden Sie unter Aufrufen einer Methode.

Rückgabewert

Diese Methode gibt ein HRESULT zurück, das den Status des Methodenaufrufs angibt. Bei einem Fehler können Sie verfügbare Informationen aus der COM-Funktion GetErrorInfo abrufen. COM-spezifische Fehlercodes können zurückgegeben werden, wenn Netzwerkprobleme dazu führen, dass die Remoteverbindung mit WMI verloren geht. Beachten Sie, dass WMI auf ein Ergebnis der SetStatus-Methode des Antworthandlers wartet, wenn CreateClassEnumAsync WBEM_S_NO_ERROR zurückgibt. WMI wartet auf unbegrenzte Zeit bei einer lokalen Verbindung oder bis ein Timeout der Remoteverbindung auftritt. Die folgende Liste listet den Wert auf, der in einem HRESULT enthalten ist.

Hinweise

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. Wenn Sie eine asynchrone Kommunikation benötigen, finden Sie weitere Informationen unter Aufrufen einer Methode.

Weitere Informationen zur semisynchronen Verwendung von Methoden finden Sie unter IWbemServices::CreateClassEnum und Aufrufen einer Methode.

Beispiele

Im folgenden Codebeispiel wird veranschaulicht, wie CreateClassEnumAsync implementiert wird.

HRESULT CStdProvider::CreateClassEnumAsync( 
            /* [in] */ BSTR strSuperclass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0;

    // Assume there is an IWbemServices pointer available (m_pSvc).
    // Retrieve an 'empty' object that will be built up
    // into the class definition.
    
    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
    {
        return hRes;
    }

    // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);

    // Now loop through the private source of class definitions
    // and create each class.
    while(hRes)
    {
        // Create the class definition elsewhere.
        // For example, call a function that creates a definition:
        // FillClassDef(pNextClass);

        // Deliver the class to WMI.
        pResponseHandler->Indicate(1, &pNextClass);
        pNextClass->Release( );

        // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);     
    }

    pClass->Release();

    // Send a finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

Im vorherigen Beispiel ruft der Klassenanbieter einen Thread von WMI ab, um die erforderlichen Vorgänge auszuführen. Möglicherweise möchten Sie die AddRef-Methode aufrufen und einen weiteren Thread erstellen, um die Objekte im Resultset bereitzustellen. 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 oder den Dual-Thread-Entwurf wählt, hängt von der Zeit ab, die der Anbieter für die Verwendung des WMI-Threads plant. Es gibt keine festen Regeln. Experimentieren kann Ihnen helfen, festzustellen, wie sich Ihr Entwurf auf die WMI-Leistung auswirkt.

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