WdfUsbTargetPipeFormatRequestForWrite-Funktion (wdfusb.h)

  • Artikel

[Gilt für KMDF und UMDF]

Die WdfUsbTargetPipeFormatRequestForWrite-Methode erstellt eine Schreibanforderung für eine USB-Ausgabepipe, 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 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] WriteMemory

Ein Handle für ein Frameworkspeicherobjekt. 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 aufruferseitig zugeordnete WDFMEMORY_OFFSET-Struktur , die optionale Byteoffset- 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 entspricht der Puffergröße.

Rückgabewert

WdfUsbTargetPipeFormatRequestForWrite gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. 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
 Es war 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 offset-Parameter angegeben hat, war ungültig.
STATUS_REQUEST_NOT_ACCEPTED
 Das vom Request-Parameter dargestellte E/A-Anforderungspaket (IRP) bietet nicht genügend IO_STACK_LOCATION Strukturen, 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 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 Pipe muss eine Ausgabepipe 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 empfangen hat, oder Sie können eine neue Anforderung erstellen und senden. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und etwas Pufferspeicherplatz.

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

  1. Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfUsbTargetPipeFormatRequestForWrite-Methode an.
  2. Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den WriteMemory-Parameter der WdfUsbTargetPipeFormatRequestForWrite-Methode.

    Der Treiber muss WdfRequestRetrieveInputMemory aufrufen, um ein Handle für ein Frameworkspeicherobjekt abzurufen, das den Eingabepuffer der Anforderung darstellt, und dieses Handle als Wert für WriteMemory zu verwenden.

Weitere Informationen zum Weiterleiten einer E/A-Anforderung finden Sie unter Weiterleiten 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:

  1. Erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle für den Request-Parameter der WdfUsbTargetPipeFormatRequestForWrite-Methode an.

    Rufen Sie WdfRequestCreate auf , um mindestens ein Anforderungsobjekt vorab zu verwenden. 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.

  2. Geben Sie Pufferspeicher an, und geben Sie das Handle des Puffers für den WriteMemory-Parameter der WdfUsbTargetPipeFormatRequestForWrite-Methode an.

    Ihr Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für 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 WdfRequestRetrieveInputMemory 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 WdfRequestRetrieveInputMemory aufruft und das Speicherhandle an WdfUsbTargetPipeFormatRequestForWrite übergibt, darf der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue, vom Treiber erstellte Anforderungsobjekt gelöscht, wiederverwendet oder neu formatiert hat. (WdfUsbTargetPipeFormatRequestForWrite erhöht die Referenzanzahl des Speicherobjekts. Durch das Löschen, Wiederverwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts verringert.)
Nach dem Aufrufen von WdfUsbTargetPipeFormatRequestForWrite 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 WdfUsbTargetPipeFormatRequestForWrite , die dieselbe Anforderung verwenden, führen nicht zu zusätzlichen Ressourcenzuordnungen. Aus diesem Grund kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Chance zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zu verwenden. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( WdfRequestReuse aufrufen), neu formatieren ( WdfUsbTargetPipeFormatRequestForWrite aufrufen) und jedes Anforderungsobjekt erneut senden (WdfRequestSend aufrufen), ohne einen STATUS_INSUFFICIENT_RESOURCES Rückgabewert aus einem späteren Aufruf von WdfRequestCreate zu riskieren. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForWrite 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 zugeordnet.)

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

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

Beispiele

Das folgende Codebeispiel stammt aus dem kmdf_fx2 Beispieltreibers. Dieses Beispiel ist eine EvtIoWrite-Rückruffunktion , die eine Schreibanforderung an eine USB-Pipe weiterleitet. Im Beispiel wird WdfRequestRetrieveInputMemory aufgerufen, um den Eingabepuffer der Anforderung abzurufen. Anschließend wird die Schreibanforderung so formatiert, dass 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 
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

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfusb.h (wdfusb.h einschließen)
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

WdfUsbTargetPipeFormatRequestForRead