WdfUsbTargetPipeFormatRequestForUrb-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WdfUsbTargetPipeFormatRequestForUrb--Methode erstellt eine USB-Anforderung für ein angegebenes USB-Pipe mithilfe von Anforderungsparametern, die von einem angegebenen URB- beschrieben werden, aber die Anforderung wird nicht gesendet.

Syntax

NTSTATUS WdfUsbTargetPipeFormatRequestForUrb(
                 WDFUSBPIPE        PIPE,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Parameter

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] UrbMemory

Ein Handle zu einem Framework-Speicherobjekt, das eine URB- Struktur enthält.

Wenn der zuvor WdfUsbTargetDeviceCreateWithParameters aufgerufen wurde, um UsbDevicezu erstellen, muss der Treiber WdfUsbTargetDeviceCreateUrb oder WdfUsbTargetDeviceCreateIsochUrb verwenden, um die in diesem Speicherobjekt enthaltene URB zu erstellen.

[in, optional] UrbMemoryOffset

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 der URB im Speicher zu bestimmen, die UrbMemory- angibt. Wenn dieser Zeiger NULL-ist, befindet sich der URB am Anfang des UrbMemory Arbeitsspeicher.

Rückgabewert

WdfUsbTargetPipeFormatRequestForUrb gibt den Fertigstellungsstatuswert des E/A-Ziels 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_INTEGER_OVERFLOW	Der Offset, den der UsbMemoryOffset angegebenen Parameter war ungültig.
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 WdfUsbTargetPipeFormatRequestForUrbgefolgt von WdfRequestSend, um eine USB-Anforderung entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeSendUrbSynchronly Methode verwenden, um eine Anforderung synchron zu senden.

Das Framework untersucht die USB-Anforderung nicht. Wenn die Anforderung den Zustand des USB-Pipes ändert, wird das Framework die Änderung nicht kennen.

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.

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 WdfUsbTargetPipeFormatRequestForUrb Parameter der Request-Methode an.

Rufen Sie WdfRequestCreate auf, um eine neue E/A-Anforderung zu erstellen. Geben Sie den Anforderungshandle für den WdfUsbTargetPipeFormatRequestForUrb Method's Request Parameter an. Sie können das Anforderungsobjekt wiederverwenden, indem Sie WdfRequestReuse-aufrufen, damit die EvtDriverDeviceAdd Rückruffunktion Anforderungsobjekte für ein Gerät vorab zugewiesen werden kann.

Nach dem Aufrufen WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb, 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 WdfUsbTargetPipeFormatRequestForUrb) 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 WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Im folgenden Codebeispiel wird ein Speicherobjekt erstellt, das eine URB darstellt. Anschließend initialisiert das Beispiel die URB, formatiert eine USB-Anforderung, die die URB enthält, registriert eine CompletionRoutine Rückruffunktion und sendet die Anforderung.

URB  urb;
PURB  pUrb = NULL;
WDFMEMORY  urbMemory
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER),
                         &urbMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

pUrb = WdfMemoryGetBuffer(
                          urbMemory,
                          NULL
                          );

pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeFormatRequestForUrb(
                                             pipe,
                                             Request,
                                             urbMemory,
                                             NULL
                                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}
WdfRequestSetCompletionRoutine(
                               Request,
                               UrbCompletionRoutine,
                               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
Header-	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
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)