WdfUsbTargetPipeFormatRequestForRead-Funktion (wdfusb.h)
[Gilt für KMDF und UMDF]
Die WdfUsbTargetPipeFormatRequestForRead-Methode erstellt eine Leseanforderung für eine USB-Eingabepipe, sendet die Anforderung jedoch nicht.
Syntax
NTSTATUS WdfUsbTargetPipeFormatRequestForRead(
[in] WDFUSBPIPE Pipe,
[in] WDFREQUEST Request,
[in, optional] WDFMEMORY ReadMemory,
[in, optional] PWDFMEMORY_OFFSET ReadOffset
);
Parameter
[in] Pipe
Ein Handle für ein Framework-Pipeobjekt, das durch aufrufen von WdfUsbInterfaceGetConfiguredPipe abgerufen wurde.
[in] Request
Ein Handle für ein Frameworkanforderungsobjekt. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, optional] ReadMemory
Ein Handle für ein Frameworkspeicherobjekt. 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 WdfUsbTargetPipeSetNoMaximumPacketSizeCheck aufgerufen. Weitere Informationen zu diesem Puffer finden Sie im 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 |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Nicht genügend Arbeitsspeicher war verfügbar. |
|
Ein ungültiger Speicherdeskriptor wurde angegeben, der Typ der Pipe war ungültig, die Übertragungsrichtung war ungültig, oder die angegebene E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt. |
|
Der Offset, den der Offset-Parameter angegeben hat, war ungültig. |
|
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 WdfUsbTargetPipeSetNoMaximumPacketSizeCheck aufgerufen. |
|
Das vom Request-Parameter dargestellte E/A-Anforderungspaket (IRP) stellt nicht genügend IO_STACK_LOCATION Strukturen bereit, damit der Treiber die Anforderung weiterleiten kann. |
Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.
Eine Fehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.
Hinweise
Verwenden Sie WdfUsbTargetPipeFormatRequestForRead, gefolgt von WdfRequestSend, um Leseanforderungen synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeReadSynchronously-Methode verwenden, um Leseanforderungen synchron zu senden.
Die Pipe, die der Pipe-Parameter angibt, muss eine Eingabepipe sein, und der Typ der Pipe muss WdfUsbPipeTypeBulk oder WdfUsbPipeTypeInterrupt sein.
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 etwas Pufferspeicher.
So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:
- Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfUsbTargetPipeFormatRequestForRead-Methode an.
-
Verwenden Sie den Ausgabepuffer der empfangenen Anforderung für den ReadMemory-Parameter der WdfUsbTargetPipeFormatRequestForRead-Methode.
Der Treiber muss WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Ausgabepuffer der Anforderung darstellt, und dieses Handle als Wert für den ReadMemory-Parameter verwenden.
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 Request-Parameter der WdfUsbTargetPipeFormatRequestForRead-Methode an.
Rufen Sie WdfRequestCreate auf , um ein oder mehrere Anforderungsobjekte vorab zuzulisten. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion EvtDriverDeviceAdd ihres Treibers kann Anforderungsobjekte für ein Gerät vorab zuweisungen.
-
Stellen Sie Pufferspeicher bereit, und geben Sie das Handle des Puffers für den ReadMemory-Parameter der WdfUsbTargetPipeFormatRequestForRead-Methode an.
Ihr Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für den vom Framework verwalteten Arbeitsspeicher 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.
Mehrere Aufrufe von WdfUsbTargetPipeFormatRequestForRead , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuordnungen. Daher kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Möglichkeit zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zuordnen. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( WdfRequestReuse aufrufen), neu formatieren (aufrufen von WdfUsbTargetPipeFormatRequestForRead) und erneut senden (aufrufen WdfRequestSend), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForRead für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn sich die Parameterwerte nicht ändern. (Wenn der Treiber nicht jedes Mal dieselbe Methode zur Anforderungsformatierung aufruft, werden möglicherweise zusätzliche Ressourcen zugewiesen.)
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 status Informationen 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. Das Beispiel ruft WdfRequestRetrieveOutputMemory auf, um den Ausgabepuffer der Anforderung abzurufen, und formatiert dann die Leseanforderung, sodass die Anforderung an eine USB-Pipe gesendet werden kann. Als Nächstes registriert das Beispiel eine CompletionRoutine-Rückruffunktion . Schließlich wird die Anforderung an die USB-Pipe gesendet.
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 | Universell |
| KMDF-Mindestversion | 1.0 |
| UMDF-Mindestversion | 2.0 |
| Kopfzeile | wdfusb.h (einschließlich Wdfusb.h) |
| Bibliothek | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| DDI-Complianceregeln | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |
Weitere Informationen
WdfRequestCompleteWithInformation
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für