WdfUsbTargetPipeFormatRequestForUrb-Funktion (wdfusb.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die WdfUsbTargetPipeFormatRequestForUrb-Methode erstellt eine USB-Anforderung für eine angegebene 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 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] UrbMemory

Ein Handle für ein Frameworkspeicherobjekt, das eine URB-Struktur enthält.

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

[in, optional] UrbMemoryOffset

Ein Zeiger auf eine aufruferseitig zugeordnete WDFMEMORY_OFFSET-Struktur , die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse des URB innerhalb des Von UrbMemory angegebenen Arbeitsspeichers zu bestimmen. Wenn dieser Zeiger NULL ist, befindet sich die URB am Anfang des UrbMemory-Speichers .

Rückgabewert

WdfUsbTargetPipeFormatRequestForUrb gibt den Abschluss des E/A-Ziels status Wert 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	Es war nicht genügend Arbeitsspeicher verfügbar.
STATUS_INTEGER_OVERFLOW	Der Offset, den der usbMemoryOffset-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 WdfUsbTargetPipeFormatRequestForUrb, gefolgt von WdfRequestSend, um eine USB-Anforderung entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetPipeSendUrbSynchronously-Methode verwenden, um eine Anforderung synchron zu senden.

Das Framework untersucht die USB-Anforderung nicht. Wenn die Anforderung den Status der USB-Pipe ändert, wird das Framework die Änderung nicht kennen.

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.

Um eine E/A-Anforderung weiterzuleiten, die Ihr Treiber in einer E/A-Warteschlange empfangen hat, geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfUsbTargetPipeFormatRequestForUrb-Methode an.

Um eine neue E/A-Anforderung zu erstellen, rufen Sie WdfRequestCreate auf , um ein Anforderungsobjekt vorab zuzuspeichern. Geben Sie das Anforderungshandle für den Request-Parameter der WdfUsbTargetPipeFormatRequestForUrb-Methode an. Sie können das Anforderungsobjekt wiederverwenden, indem Sie WdfRequestReuse aufrufen, damit die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers Anforderungsobjekte für ein Gerät vorab zuweisungen kann.

Nach dem Aufrufen von 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. 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 ( WdfUsbTargetPipeFormatRequestForUrb 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 WdfUsbTargetPipeFormatRequestForUrb 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 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 den 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	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfusb.h (wdfusb.h einschließen)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
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)