Delen via

I/O-aanvragen voltooien in UMDF

  • Artikel

Waarschuwing

UMDF 2 is de nieuwste versie van UMDF en vervangt UMDF 1. Alle nieuwe UMDF-stuurprogramma's moeten worden geschreven met UMDF 2. Er worden geen nieuwe functies toegevoegd aan UMDF 1 en er is beperkte ondersteuning voor UMDF 1 op nieuwere versies van Windows 10. Universele Windows-stuurprogramma's moeten UMDF 2 gebruiken.

De gearchiveerde UMDF 1-voorbeelden vindt u in de Windows 11 versie 22H2 - update van stuurprogrammavoorbeelden van mei 2022.

Zie Aan de slag met UMDF-voor meer informatie.

Elke I/O-aanvraag moet uiteindelijk worden voltooid door een UMDF-stuurprogramma. Om een aanvraag te voltooien, moet de driver de methode IWDFIoRequest::Complete of IWDFIoRequest::CompleteWithInformation aanroepen. Wanneer het stuurprogramma de aanvraag heeft voltooid, wordt een van de volgende scenario's aangegeven:

  • De aangevraagde I/O-bewerking is voltooid.

  • De aangevraagde I/O-bewerking is gestart, maar is mislukt voordat deze is voltooid.

  • De aangevraagde I/O-bewerking wordt niet ondersteund of is niet geldig op het moment dat deze is ontvangen en kan daarom niet communiceren met het apparaat.

  • De aangevraagde I/O-bewerking is geannuleerd.

Het stuurprogramma roept de methode IWDFIoRequest::CompleteWithInformation aan om aanvullende informatie over de aanvraagbewerking door te geven. Voor een leesbewerking moet het stuurprogramma bijvoorbeeld het aantal gelezen bytes opgeven.

Als u een I/O-aanvraag wilt voltooien, moet het stuurprogramma de juiste voltooiingsstatus doorgeven aan de parameter CompletionStatus in de aanroep naar IWDFIoRequest::Complete of IWDFIoRequest::CompleteWithInformation. Het stuurprogramma gebruikt een HRESULT-code om de status van de voltooide aanvraag te communiceren.

Het hostproces van het UMDF-stuurprogramma converteert de HRESULT-code naar een NTSTATUS-code voordat het de voltooide aanvraag doorgeeft aan de reflector (Wudfrd.sys). De reflector geeft de NTSTATUS-code door aan het besturingssysteem. Het besturingssysteem converteert de NTSTATUS-code naar een Microsoft Win32-foutcode voordat het het resultaat weergeeft aan de aanroepende toepassing.

Om ervoor te zorgen dat de foutcodes van uw stuurprogramma correct kunnen worden geconverteerd, moet u foutcodes maken met een van de volgende technieken:

  • Gebruik een foutcode van Winerror.h en pas de HRESULT_FROM_WIN32 macro toe.

  • Gebruik een foutcode van Ntstatus.h en pas de macro HRESULT_FROM_NT toe.

Zie de Microsoft Windows SDK-documentatie voor meer informatie over deze macro's.

In de volgende voorbeeldcode ziet u hoe u een aanvraag kunt voltooien met een geschikte foutcode:

VOID
STDMETHODCALLTYPE
CMyQueue::OnWrite(
    __in IWDFIoQueue *pWdfQueue,
    __in IWDFIoRequest *pWdfRequest,
    __in SIZE_T BytesToWrite
    )
{
            -------------------- 
    if( BytesToWrite > MAX_WRITE_LENGTH ) {
        pWdfRequest->CompleteWithInformation(HRESULT_FROM_WIN32(ERROR_MORE_DATA), 0);
        return;
    }
            ---------------------
}

Wanneer een stuurprogramma een aanvraag heeft voltooid, wordt S_OK geretourneerd. Dit is een HRESULT-waarde. Omdat S_OK gelijk is aan NO_ERROR in Winerror.h en STATUS_SUCCESS in Ntstatus.h, zijn de conversiemacro's niet nodig.

Als Driver Verifier is ingeschakeld voor de reflector, identificeert deze een ongeldige statuscode en veroorzaakt een systeemfoutcontrole.

Opmerking De stuurprogrammaverifier voor Windows XP veroorzaakt onterecht een systeemcrash voor Win32-foutcodes waarvan de waarden decimaal 1024 (1024L) overschrijden. Als uw stuurprogramma op Windows XP wordt uitgevoerd, moet u rekening houden met dit probleem als u Driver Verifier voor de reflector inschakelt.

Als het stuurprogramma eerder een aanvraag naar een stuurprogramma op een lager niveau heeft verzonden, moet het stuurprogramma een melding ontvangen wanneer het stuurprogramma op lager niveau de aanvraag voltooit. Om u te registreren voor meldingen, roept het stuurprogramma de IWDFIoRequest::SetCompletionCallback-methode aan om de interface te registreren voor de methode die het framework aanroept wanneer het stuurprogramma op lager niveau de aanvraag voltooit. Het stuurprogramma implementeert de callback-functie IRequestCallbackRequestCompletion::OnCompletion om de bewerkingen uit te voeren die nodig zijn om de aanvraag te voltooien.

Een stuurprogramma voltooit geen I/O-aanvraag die is gemaakt door IWDFDevice::CreateRequest aan te roepen. In plaats daarvan moet het stuurprogramma IWDFObject::D eleteWdfObject aanroepen om het aanvraagobject te verwijderen, meestal nadat een I/O-doel de aanvraag heeft voltooid.

Een stuurprogramma kan bijvoorbeeld een lees- of schrijfaanvraag ontvangen voor een hoeveelheid gegevens die groter is dan de I/O-doelen van het stuurprogramma tegelijk kunnen verwerken. Het stuurprogramma moet de gegevens verdelen in verschillende kleinere aanvragen en deze kleinere aanvragen verzenden naar een of meer I/O-doelen. Technieken voor het afhandelen van deze situatie zijn:

  • IWDFDevice aanroepen::CreateRequest om één extra aanvraagobject te maken dat een kleinere aanvraag vertegenwoordigt.

    Het stuurprogramma kan deze aanvraag synchroon verzenden naar een I/O-doel. De callbackfunctie IRequestCallbackRequestCompletion::OnCompletion van de kleinere aanvraag kan IWDFIoRequest2::Reuse worden aangeroepen, zodat het stuurprogramma de aanvraag opnieuw kan gebruiken en weer naar het I/O-doel kan sturen. Nadat het I/O-doel de laatste van de kleinere aanvragen heeft voltooid, kan de callback-functie OnCompletionIWDFObject::D eleteWdfObject aanroepen om het door het stuurprogramma gemaakte aanvraagobject te verwijderen en kan het stuurprogramma IWDFIoRequest::Complete aanroepen om de oorspronkelijke aanvraag te voltooien.

  • IWDFDevice aanroepen::CreateRequest om verschillende extra aanvraagobjecten te maken die de kleinere aanvragen vertegenwoordigen.

    De I/O-doelen van het stuurprogramma kunnen deze meerdere kleinere aanvragen asynchroon verwerken. Het stuurprogramma kan een callbackfunctie voor OnCompletion registreren voor elk van de kleinere aanvragen. Telkens wanneer de callback-functie OnCompletion wordt aangeroepen, kan deze IWDFObject::D eleteWdfObject aanroepen om een door het stuurprogramma gemaakte aanvraagobject te verwijderen. Nadat het I/O-doel alle kleinere aanvragen heeft voltooid, kan het stuurprogramma IWDFIoRequest::Complete aanroepen om de oorspronkelijke aanvraag te voltooien.

Voltooiingsgegevens verkrijgen

Een op UMDF gebaseerd stuurprogramma kan het volgende doen om informatie te verkrijgen over een I/O-aanvraag die een ander stuurprogramma heeft voltooid:

Daarnaast kan een op UMDF gebaseerd stuurprogramma de methode IWDFIoRequest2::GetStatus gebruiken om de huidige status van een I/O-aanvraag te verkrijgen, vóór of nadat de aanvraag is voltooid.