WdfUsbTargetPipeFormatRequestForWrite-Funktion (wdfusb.h)

Artikel
08/17/2022
4 Minuten Lesedauer

[Gilt für KMDF und UMDF]

Die WdfUsbTargetPipeFormatRequestForWrite-Methode erstellt eine Schreibanforderung für eine USB-Ausgabepipeline, sendet die Anforderung jedoch nicht.

Syntax

NTSTATUS WdfUsbTargetPipeFormatRequestForWrite(
  [in]           WDFUSBPIPE        Pipe,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         WriteMemory,
  [in, optional] PWDFMEMORY_OFFSET WriteOffset
);

Parameter

[in] Pipe

Ein Handle zu einem Framework-Pipeobjekt, das durch Aufrufen von WdfUsbInterfaceGetConfiguredPipe abgerufen wurde.

[in] Request

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

[in, optional] WriteMemory

Ein Handle zu einem Framework-Speicherobjekt. Dieses Objekt stellt einen Puffer dar, der Daten enthält, die an die Pipe gesendet werden. Weitere Informationen zu diesem Puffer finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] WriteOffset

Ein Zeiger auf eine aufrufer-zugeordnete WDFMEMORY_OFFSET Struktur, die optionale Byte-Offset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse und die Länge innerhalb des Schreibpuffers 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

WdfUsbTargetPipeFormatRequestForWrite gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich verläuft. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiger Parameter wurde erkannt.
STATUS_INSUFFICIENT_RESOURCES	Unzureichender Arbeitsspeicher war verfügbar.
STATUS_INVALID_DEVICE_REQUEST	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.
STATUS_INTEGER_OVERFLOW	Der Offset, den der angegebene Offsetparameter angegeben hat, war ungültig.
STATUS_REQUEST_NOT_ACCEPTED	Das I/O-Anforderungspaket (IRP), das der Anforderungsparameter darstellt, 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.

Bemerkungen

Verwenden Sie WdfUsbTargetPipeFormatRequestForWrite, gefolgt von WdfRequestSend, um Schreibanforderungen entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeWriteSynchronously-Methode verwenden, um Schreibanforderungen synchron zu senden.

Die angegebene Leitung muss eine Ausgabepipeline sein, und der Typ des Rohrs muss WdfUsbPipeTypeBulk oder WdfUsbPipeTypeInterrupt sein.

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

Um eine E/A-Anforderung weiterzuleiten, die Ihr Treiber in einer E/A-Warteschlange erhalten hat:

Geben Sie den Handle der empfangenen Anforderung für den Anforderungsparameter der WdfUsbTargetPipeFormatRequestForWrite-Methode an.
Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den Parameter WriteMemory der WdfUsbTargetPipeFormatRequestForWrite-Methode.
Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt und diesen Handle als Wert für WriteMemory verwendet.

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

Treiber teilen häufig empfangene E/A-Anforderungen 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 Anforderungsparameter der WdfUsbTargetPipeFormatRequestForWrite-Methode an.
Rufen Sie WdfRequestCreate auf, um mindestens ein Anforderungsobjekt vorzuallocatieren. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion Des Treibers EvtDriverDeviceAdd kann Anforderungsobjekte für ein Gerät vorschreiben.
Stellen Sie Pufferraum bereit, und geben Sie den Handle des Puffers für den Parameter "WdfUsbTargetPipeFormatRequestForWrite " der WriteMemory-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 I/O-Ziel übergeben soll.
- Rufen Sie WdfRequestRetrieveInputMemory auf, um ein Handle für das Speicherobjekt abzurufen, das den Puffer einer empfangenen I/O-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das I/O-Ziel übergeben soll.
Wenn Ihr Treiber WdfRequestRetrieveInputMemory aufruft und den Speicherpunkt an WdfUsbTargetPipeFormatRequestForWrite übergibt, muss der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber gelöscht, wiederverwendet oder das neue, vom Treiber erstellte Anforderungsobjekt neu erstellt hat. (WdfUsbTargetPipeFormatRequestForWrite erhöht die Referenzanzahl des Speicherobjekts. Das Löschen, Erneute Verwenden oder Neuattieren eines Anforderungsobjekts erhöht die Referenzanzahl des Speicherobjekts.)

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

Mehrere Aufrufe von WdfUsbTargetPipeFormatRequestForWrite , die dieselbe Anforderung verwenden, verursachen keine zusätzlichen Ressourcenzuweisungen. Um die Chance zu verringern, dass WdfRequestCreate STATUS_INSUFFICIENT_RESOURCES zurückgibt, kann die Rückruffunktion Des Treibers EvtDriverDeviceAddWdfRequestCreate aufrufen, um ein oder mehrere Anforderungsobjekte für ein Gerät vorzuladen. Der Treiber kann anschließend wiederverwendet werden ( WdfRequestReuse aufrufen), umformatieren ( WdfUsbTargetPipeFormatRequestForWrite) und erneut senden (Aufrufen von WdfRequestSend) jedes Anforderungsobjekt ohne Risiko eines STATUS_INSUFFICIENT_RESOURCES Rückgabewerts von einem späteren Aufruf an WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForWrite für das wiederverwendete Anforderungsobjekt geben STATUS_SUCCESS zurück, wenn Parameterwerte nicht geändert werden. (Wenn der Treiber die gleiche Anforderungsformatierungsmethode nicht jedes Mal aufruft, werden möglicherweise zusätzliche Ressourcen zugewiesen.)

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

Weitere Informationen zur WdfUsbTargetPipeFormatRequestForWrite-Methode und USB-I/O-Zielen finden Sie unter USB-I/O-Ziele.

Beispiele

Das folgende Codebeispiel stammt aus dem kmdf_fx2 Beispieltreiber. In diesem Beispiel handelt es sich um eine EvtIoWrite-Rückruffunktion , die eine Schreibanforderung an eine USB-Leitung weiterleitet. Im Beispiel wird WdfRequestRetrieveInputMemory aufgerufen, um den Eingabepuffer der Anforderung abzurufen und dann die Schreibanforderung so zu formatieren, dass die Anforderung an eine USB-Pipe gesendet werden kann. Als Nächstes registriert das Beispiel eine CompletionRoutine-Rückruffunktion . Schließlich sendet sie die Anforderung an die USB-Leitung.

VOID 
OsrFxEvtIoWrite(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
    NTSTATUS  status;
    WDFUSBPIPE  pipe;
    WDFMEMORY  reqMemory;
    PDEVICE_CONTEXT  pDeviceContext;
 
    if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) {
        status = STATUS_INVALID_PARAMETER;
        goto Exit;
    }

    pDeviceContext = GetDeviceContext(WdfIoQueueGetDevice(Queue));
 
    pipe = pDeviceContext->BulkWritePipe;

    status = WdfRequestRetrieveInputMemory(
                                           Request,
                                           &reqMemory
                                           );
    if (!NT_SUCCESS(status)){
        goto Exit;
    }

    status = WdfUsbTargetPipeFormatRequestForWrite(
                                                   pipe,
                                                   Request,
                                                   reqMemory,
                                                   NULL
                                                   );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   EvtRequestWriteCompletionRoutine,
                                   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


Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Header	wdfusb.h (include 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)

Siehe auch

WdfUsbTargetPipeFormatRequestForRead