IWDFIoQueue::RetrieveNextRequest-Methode (wudfddi.h)

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 für neuere Versionen von Windows 10 ist eingeschränkt. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF.]

Die RetrieveNextRequest-Methode ruft die nächste E/A-Anforderung aus einer E/A-Warteschlange ab.

Syntax

HRESULT RetrieveNextRequest(
  [out] IWDFIoRequest **ppRequest
);

Parameter

[out] ppRequest

Ein Zeiger auf einen Puffer, der einen Zeiger auf die IWDFIoRequest-Schnittstelle für das nächste Anforderungsobjekt empfängt, oder null empfängt, wenn die Warteschlange leer ist oder die nächste Anforderung nicht gefunden wird.

Rückgabewert

RetrieveNextRequest gibt einen der folgenden Werte zurück:

Rückgabecode	BESCHREIBUNG
S_OK	Die nächste E/A-Anforderung wurde erfolgreich aus der E/A-Warteschlange abgerufen.
HRESULT_FROM_NT (STATUS_WDF_PAUSED)	Die Warteschlange sendet keine Anforderungen. Diese Situation tritt auf, wenn das Gerät einen Energiezustandsübergang durchläuft und alle Warteschlangen am Senden von Anforderungen nicht mehr gesendet werden oder wenn der Treiber explizit IWDFIoQueue::Stop aufgerufen hat, um das Senden von Anforderungen zu beenden. Diese Situation kann auch auftreten, wenn der Treiber versucht, eine Anforderung aus einer manuellen Warteschlange zu entfernen, die vom Strom verwaltet wird und heruntergefahren wird, oder wenn die Warteschlange angehalten wird.
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)	Es befanden sich keine Anforderungen in der Warteschlange.
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	Der Aufruf wurde ausgeführt, um die Anforderung aus einer parallelen Warteschlange abzurufen.

 

RetrieveNextRequest kann auch andere HRESULT-Werte zurückgeben.

Hinweise

Wenn ein Treiber eine E/A-Warteschlange für das manuelle Senden von E/A-Anforderungen konfiguriert, kann der Treiber die RetrieveNextRequest-Methode aufrufen, um die nächste Anforderung aus der Warteschlange abzurufen. Weitere Informationen zum manuellen Senden von E/A-Anforderungen finden Sie unter Konfigurieren des Versandmodus für eine E/A-Warteschlange.

Wenn ein Treiber eine E/A-Warteschlange für das sequenzielle Senden von E/A-Anforderungen konfiguriert, kann der Treiber weiterhin die RetrieveNextRequest-Methode aufrufen, um die nächste Anforderung aus der Warteschlange abzurufen, ohne dass ein Fehler empfangen wird. Obwohl das Framework dem Treiber erlaubt , RetrieveNextRequest aufzurufen, um eine Anforderung aus einer sequenziellen Warteschlange abzurufen, sollte der Treiber nur RetrieveNextRequest aufrufen, bevor der Treiber die aktuelle Anforderung abgeschlossen hat. Andernfalls kann eine Racebedingung auftreten, wenn der Treiber versucht , RetrieveNextRequest aufzurufen, nachdem der Treiber die aktuelle Anforderung abgeschlossen hat. Diese Racebedingung tritt zwischen dem automatischen Senden der nächsten Anforderung aus der sequenziellen Warteschlange und dem Aufruf des Treibers an RetrieveNextRequest zum Abrufen der nächsten Anforderung durch das Framework auf.

Beispiele

Im folgenden Codebeispiel, das vom umdf_fx2 Beispieltreiber stammt, wird die Warteschlange auf Anforderungen abgefragt, solange Anforderungen abgerufen werden können. Der Code überprüft zunächst, ob Anforderungen einem bestimmten Dateiobjekt zugeordnet sind.

VOID
CMyDevice::ServiceSwitchChangeQueue(
    __in SWITCH_STATE NewState,
    __in HRESULT CompletionStatus,
    __in_opt IWDFFile *SpecificFile
    )
{
    IWDFIoRequest *fxRequest;
    HRESULT enumHr = S_OK;
    do {
        HRESULT hr;
        //
        // Get the next request.
        //
        if (NULL != SpecificFile) {
        enumHr = m_SwitchChangeQueue->RetrieveNextRequestByFileObject(
                                        SpecificFile,
                                        &fxRequest
                                        );
        }
        else {
            enumHr = m_SwitchChangeQueue->RetrieveNextRequest(&fxRequest);
        }
        //
        // If a request was retrieved, complete it.
        //
        if (S_OK == enumHr) {
            if (S_OK == CompletionStatus) {
                IWDFMemory *fxMemory;
                //
                // Copy the result to the request buffer.
                //
                fxRequest->GetOutputMemory(&fxMemory);
                hr = fxMemory->CopyFromBuffer(0, 
                                              &NewState, 
                                              sizeof(SWITCH_STATE));
                                              fxMemory->Release();
            }
            else {
                 hr = CompletionStatus;
            }
            //
            // Complete the request with the copy or 
            // completion status.
            //
            if (S_OK == hr) {
                fxRequest->CompleteWithInformation(hr, 
                                                   sizeof(SWITCH_STATE));
            }
            else {
                fxRequest->Complete(hr);
            }
            fxRequest->Release();
        }
    }
    while (S_OK == enumHr);
}

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform	Desktop
UMDF-Mindestversion	1.5
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll

Weitere Informationen

IWDFIoQueue

IWDFIoQueue::Stop

IWDFIoRequest