IEnumWbemClassObject::Next-Methode (wbemcli.h)

Artikel
03/03/2024

Verwenden Sie die IEnumWbemClassObject::Next-Methode , um ein oder mehrere Objekte ab der aktuellen Position in einer Enumeration abzurufen. Diese Methode erhöht die aktuelle Position in der Enumeration durch uCount-Objekte , sodass nachfolgende Aufrufe die nachfolgenden Objekte zurückgeben.

Syntax

HRESULT Next(
  [in]  long             lTimeout,
  [in]  ULONG            uCount,
  [out] IWbemClassObject **apObjects,
  [out] ULONG            *puReturned
);

Parameter

[in] lTimeout

Gibt die maximale Zeitspanne in Millisekunden an, die der Aufruf vor der Rückgabe blockiert. Wenn Sie die konstante WBEM_INFINITE (0xFFFFFFFF) verwenden, wird der Aufruf blockiert, bis Objekte verfügbar sind. Wenn Sie den Wert 0 (WBEM_NO_WAIT) verwenden, gibt der Aufruf sofort zurück, unabhängig davon, ob Objekte verfügbar sind oder nicht.

[in] uCount

Anzahl der angeforderten Objekte.

[out] apObjects

Zeiger auf genügend Speicher, um die anzahl der IWbemClassObject-Schnittstellenzeiger zu speichern, die durch uCount angegeben werden. Dieser Speicher muss vom Aufrufer bereitgestellt werden. Dieser Parameter darf nicht NULL sein. Der Aufrufer muss Release für jeden der empfangenen Schnittstellenzeiger aufrufen, wenn sie nicht mehr benötigt werden.

[out] puReturned

Zeiger auf eine ULONG , die die Anzahl der zurückgegebenen Objekte empfängt. Diese Zahl kann kleiner als die in uCount angeforderte Zahl sein. Dieser Zeiger darf nicht NULL sein.

Hinweis Die Next-Methode gibt WBEM_S_FALSE zurück, wenn Sie das Ende der Enumeration erreicht haben, auch wenn Objekte erfolgreich zurückgegeben wurden. Der WBEM_S_NO_ERROR Wert gibt nur dann zurück, wenn die Anzahl der zurückgegebenen Objekte mit der in uCount angeforderten Zahl übereinstimmt. Der WBEM_S_TIMEDOUT Wert wird zurückgegeben, wenn die Anzahl der zurückgegebenen Objekte kleiner als die angeforderte Zahl ist, Sie sich jedoch nicht am Ende der Enumeration befinden. Aus diesem Grund sollten Sie eine Schleifenabschlusslogik verwenden, die den puReturned-Wert untersucht, um sicherzustellen, dass sie das Ende der Enumeration erreicht haben.

Rückgabewert

Die Next-Methode gibt ein HRESULT zurück, das die status des Methodenaufrufs angibt. In der folgenden Liste ist der in einem HRESULT enthaltene Wert aufgeführt.

Hinweise

Möglicherweise werden COM-spezifische Fehlercodes zurückgegeben, wenn Netzwerkprobleme dazu führen, dass die Remoteverbindung mit der Windows-Verwaltung verloren geht. Bei Einem Fehler können Sie die COM-Funktion GetErrorInfo aufrufen, um weitere Fehlerinformationen zu erhalten.

Wenn mehr als ein Objekt angefordert wird und die Anzahl der angeforderten Objekte zurückgegeben wird, gibt die Funktion WBEM_S_NO_ERROR zurück. Wenn weniger als die angeforderte Anzahl von Objekten verfügbar ist und die Enumeration abgeschlossen wurde, werden diese Objekte zurückgegeben, und die Funktion gibt WBEM_S_FALSE zurück.

Wenn die Enumeration nicht abgeschlossen wurde, wartet der Aufruf, bis Objekte bis zum angegebenen Timeout verfügbar sind. Wenn für die Enumeration ein Zeitüberschreitungsüberschreitung vorliegt, bevor die Objekte verfügbar sind, gibt die Funktion WBEM_S_TIMEDOUT zurück.

Hinweis Da der Rückruf an die Senke möglicherweise nicht auf derselben Authentifizierungsebene zurückgegeben wird, wie es für den Client erforderlich ist, wird empfohlen, die semisynchrone anstelle der asynchronen Kommunikation zu verwenden. Weitere Informationen finden Sie unter Aufrufen einer Methode.

Beispiele

Eine ausführliche Erläuterung und ein Beispiel zum Erstellen von Abfragen in C++ und WMI finden Sie unter Erstellen von WMI-Abfragen in C++ in CodeProject.

Im folgenden Code werden mehrere Objekte angefordert:

HRESULT ProcessEnum( IEnumWbemClassObject*    pEnum )
{
    HRESULT    hRes = WBEM_S_NO_ERROR;

    // Final Next will return WBEM_S_FALSE
    while ( WBEM_S_NO_ERROR == hRes )
    {
        ULONG            uReturned;
        IWbemClassObject*    apObj[10];

        hRes = pEnum->Next( WBEM_INFINITE, 10, apObj, &uReturned );

        if ( SUCCEEDED( hRes ) )
        {
            // Do something with the objects.
            //ProcessObjects( uReturned,  apObj );

            for ( ULONG n = 0; n < uReturned; n++ )
            {
                apObj[n]->Release();
            }

        }    // If Enum succeeded...
    }    // While Enum is returning objects...

    return hRes;
}

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

Weitere Informationen

WMI-Enumeration

IEnumWbemClassObject-Methoden

Freigeben über