WdfUsbTargetPipeFormatRequestForWrite-Funktion (wdfusb.h)

[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 WdfUsbInterfaceGetConfiguredPipeabgerufen wurde.

[in] Request

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

[in, optional] WriteMemory

Ein Handle für ein 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 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 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 ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

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 WdfUsbTargetPipeFormatRequestForWritegefolgt 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 Ausgabepipeline sein, und der Typ des Rohrs 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:

1. Geben Sie das Handle der empfangenen Anforderung für den WdfUsbTargetPipeFormatRequestForWriteRequest Parameter der Methode an.
2. Verwenden Sie den Eingabepuffer der empfangenen Anforderung für den WdfUsbTargetPipeFormatRequestForWriteWriteMemory Parameter der 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 WriteMemoryverwenden.

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 WdfUsbTargetPipeFormatRequestForWriteRequest 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.

2. Stellen Sie Pufferraum bereit, und geben Sie den Handle des Puffers für den WdfUsbTargetPipeFormatRequestForWrite Methode WriteMemory 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 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, muss der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue, vom Treiber erstellte Anforderungsobjekt gelöscht, wiederverwendet oder neu erstellt hat. (WdfUsbTargetPipeFormatRequestForWrite erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)

Mehrere Aufrufe von WdfUsbTargetPipeFormatRequestForWrite, 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), Neuformatierung (Aufruf WdfUsbTargetPipeFormatRequestForWrite) und erneut senden (WdfRequestSend) jedes Anforderungsobjekt ohne Risiko eines STATUS_INSUFFICIENT_RESOURCES Rückgabewerts von einem späteren Aufruf an WdfRequestCreate. Alle nachfolgenden Aufrufe von WdfUsbTargetPipeFormatRequestForWriteForWrite 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.)

Informationen zum Abrufen von Statusinformationen 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 Beispieltreiber. 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. Im nächsten Beispiel wird eine CompletionRoutine Rückruffunktion registriert. Schließlich sendet sie die Anforderung an das USB-Rohr.

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

Siehe auch

WdfUsbTargetPipeFormatRequestForRead-