WdfUsbTargetPipeFormatRequestForRead-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfUsbTargetPipeFormatRequestForRead-Methode erstellt eine Leseanforderung für eine USB-Eingabepipeline, sendet jedoch nicht die Anforderung.

Syntax

NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         ReadMemory,
  [in, optional] PWDFMEMORY_OFFSET ReadOffset
);

Parameter

[in] Pipe

Ein Handle zu einem Framework-Pipeobjekt, das durch Aufrufen WdfUsbInterfaceGetConfiguredPipeabgerufen wurde.

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] ReadMemory

Ein Handle für ein Framework-Speicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten aus der Pipe empfängt. Die Puffergröße muss ein Vielfaches der maximalen Paketgröße der Pipe sein, es sei denn, der Treiber hat WdfUsbTargetPipeSetNoMaximumPacketSizeCheckaufgerufen. Weitere Informationen zu diesem Puffer finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] ReadOffset

Ein Zeiger auf eine vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und -länge innerhalb des Lesepuffers für die Datenübertragung zu bestimmen. Wenn dieser Zeiger NULL-ist, beginnt die Datenübertragung am Anfang des Puffers, und die Übertragungsgröße ist die Puffergröße.

Rückgabewert

WdfUsbTargetPipeFormatRequestForRead gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Nicht genügend Arbeitsspeicher verfügbar.
STATUS_INVALID_DEVICE_REQUEST	Es wurde ein ungültiger Speicherdeskriptor angegeben, der Typ der Pipe war ungültig, die Übertragungsrichtung ungültig, oder die angegebene E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt.
STATUS_INTEGER_OVERFLOW	Der Offset, den der angegebene Offset Parameter war ungültig.
STATUS_INVALID_BUFFER_SIZE	Die Puffergröße war kein Vielfaches der maximalen Paketgröße der Pipe. Die Puffergröße muss ein Vielfaches der maximalen Paketgröße der Pipe sein, es sei denn, der Treiber hat WdfUsbTargetPipeSetNoMaximumPacketSizeCheckaufgerufen.
STATUS_REQUEST_NOT_ACCEPTED	Das E/A-Anforderungspaket (IRP-), das der parameter Request darstellt, stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, damit der Treiber die Anforderung weiterleiten kann.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Verwenden Sie WdfUsbTargetPipeFormatRequestForReadgefolgt von WdfRequestSend-, um Leseanforderungen entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeReadSynchronously Methode verwenden, um Leseanforderungen synchron zu senden.

Die pipe, die der parameter Pipe angibt, muss eine Eingabepipe sein, und der Typ der Pfeife mussWdfUsbPipeTypeBulk oder WdfUsbPipeTypeInterruptsein.

Sie können eine E/A-Anforderung weiterleiten, die Ihr Treiber in einer E/A-Warteschlange erhalten hat, oder Sie können eine neue Anforderung erstellen und senden. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und einen Pufferraum.

So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange erhalten hat:

Geben Sie das Handle der empfangenen Anforderung für den WdfUsbTargetPipeFormatRequestForRead Methode Request Parameter an.
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den WdfUsbTargetPipeFormatRequestForReadReadMemory-Parameter der Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory- aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt, und dieses Handle als Wert für den ReadMemory Parameter verwenden.

Weitere Informationen zum Weiterleiten einer E/A-Anforderung finden Sie unter Weiterleitung von E/A-Anforderungen.

Treiber teilen empfangene E/A-Anforderungen häufig in kleinere Anforderungen auf, die sie an ein E/A-Ziel senden, sodass Ihr Treiber möglicherweise neue Anforderungen erstellt.

So erstellen Sie eine neue E/A-Anforderung:

Erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle für den WdfUsbTargetPipeFormatRequestForReadRequest Parameter der Methode an.
Rufen Sie WdfRequestCreate auf, um mindestens ein Anforderungsobjekt vorab zu verwenden. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuseaufrufen. Die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab allocatieren.
Stellen Sie Pufferspeicher bereit, und geben Sie den Handle des Puffers für den WdfUsbTargetPipeFormatRequestForReadReadMemory-Parameter an.
Der Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für vom Framework verwalteten Speicher angeben. Ihr Treiber kann eine der folgenden Aktionen ausführen:
- Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um einen neuen Speicherpuffer zu erstellen, wenn der Treiber einen neuen Puffer an das E/A-Ziel übergeben soll.
- Rufen Sie WdfRequestRetrieveOutputMemory- auf, um ein Handle für das Speicherobjekt abzurufen, das den Puffer einer empfangenen E/A-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das E/A-Ziel übergeben soll.
Wenn Ihr Treiber WdfRequestRetrieveOutputMemory- aufruft und das Speicherhandle an WdfUsbTargetPipeFormatRequestForReadübergibt, muss der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue anforderungsobjekt vom Treiber gelöscht, wiederverwendet oder neu erstellt hat. (WdfUsbTargetPipeFormatRequestForRead erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)

Nach dem Aufrufen WdfUsbTargetPipeFormatRequestForRead zum Formatieren einer E/A-Anforderung muss der Treiber WdfRequestSend- aufrufen, um die Anforderung (synchron oder asynchron) an ein E/A-Ziel zu senden.

Mehrere Aufrufe von WdfUsbTargetPipeFormatRequestForRead, die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Um die Chance zu verringern, dass WdfRequestCreate- STATUS_INSUFFICIENT_RESOURCES zurückgibt, kann die EvtDriverDeviceAdd- Rückruffunktion WdfRequestCreate aufrufen, um mindestens ein Anforderungsobjekt für ein Gerät vorab bereitzustellen. Der Treiber kann anschließend wiederverwendet werden (aufruf WdfRequestReuse), neu formatieren (Aufruf WdfUsbTargetPipeFormatRequestForRead) und erneut senden (WdfRequestSend) jedes Anforderungsobjekt, ohne dass ein STATUS_INSUFFICIENT_RESOURCES Rückgabewert von einem späteren Aufruf an WdfRequestCreateriskiert wird. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForRead für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn parameterwerte nicht geändert werden. (Wenn der Treiber nicht jedes Mal dieselbe Anforderungsformatierungsmethode aufruft, werden möglicherweise zusätzliche Ressourcen zugeordnet.)

Das Framework legt das USBD_SHORT_TRANSFER_OK Flag in seiner internen URB-fest. Durch Festlegen dieses Flags kann das letzte Paket einer Datenübertragung kleiner als die maximale Paketgröße sein.

Informationen zum Abrufen von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

Weitere Informationen zur WdfUsbTargetPipeFormatRequestForRead Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Das folgende Codebeispiel stammt aus dem kmdf_fx2 Beispieltreiber. Dieses Beispiel ist eine EvtIoRead Rückruffunktion, die eine Leseanforderung an eine USB-Pipe weiterleitet. Im Beispiel wird WdfRequestRetrieveOutputMemory- aufgerufen, um den Ausgabepuffer der Anforderung abzurufen. Anschließend wird die Leseanforderung so formatiert, dass die Anforderung an eine USB-Pipe gesendet werden kann. Im nächsten Beispiel wird eine CompletionRoutine Rückruffunktion registriert. Schließlich sendet sie die Anforderung an das USB-Rohr.

VOID 
OsrFxEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    WDFUSBPIPE  pipe;
    NTSTATUS  status;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;

    //
    // First, validate input parameters.
    //
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkReadPipe;
 
    status = WdfRequestRetrieveOutputMemory(
                                            Request,
                                            &reqMemory
                                            );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }
 
    status = WdfUsbTargetPipeFormatRequestForRead(
                                                  pipe,
                                                  Request,
                                                  reqMemory,
                                                  NULL
                                                  ); 
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestReadCompletionRoutine,
                                   pipe
                                   );
    if (WdfRequestSend(
                       Request,
                       WdfUsbTargetPipeGetIoTarget(pipe),
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
        goto Exit;
    }

 
Exit:
    if (!NT_SUCCESS(status)) {
        WdfRequestCompleteWithInformation(
                                          Request,
                                          status,
                                          0
                                          );
    }
    return;
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	<=DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)