WdfUsbTargetDeviceFormatRequestForUrb-Funktion (wdfusb.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WdfUsbTargetDeviceFormatRequestForUrb-Methode erstellt eine USB-Anforderung für ein angegebenes USB-Gerät, wobei Anforderungsparameter verwendet werden, die durch eine URB-beschrieben werden, die Anforderung jedoch nicht gesendet wird.

Syntax

NTSTATUS WdfUsbTargetDeviceFormatRequestForUrb(
  [in]           WDFUSBDEVICE      UsbDevice,
  [in]           WDFREQUEST        Request,
  [in]           WDFMEMORY         UrbMemory,
  [in, optional] PWDFMEMORY_OFFSET UrbMemoryOffset
);

Parameter

[in] UsbDevice

Ein Handle für ein USB-Geräteobjekt, das aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen 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 oder eines der Union-Member der Struktur enthält. (Alle Gewerkschaftsmitglieder der URB-Struktur enthalten die _URB_HEADER Struktur.)

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. Andernfalls tritt eine Fehlerüberprüfung auf.

[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

WdfUsbTargetDeviceFormatRequestForUrb gibt STATUS_SUCCESS 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 vorhanden.
STATUS_INTEGER_OVERFLOW	Der Offset, den der UsbMemoryOffset angegebenen Parameter war ungültig.

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 WdfUsbTargetDeviceFormatRequestForUrb, gefolgt von WdfRequestSend-, um eine USB-Steuerungsübertragungsanforderung entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetDeviceSendUrbSynchronly Methode verwenden, um eine Anforderung synchron zu senden.

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

Rufen Sie WdfRequestCreate auf, um eine neue E/A-Anforderung zu erstellen. Geben Sie den Anforderungshandle für den WdfUsbTargetDeviceFormatRequestForUrb Parameter der Request Methode an. Sie können das Anforderungsobjekt wiederverwenden, indem Sie WdfRequestReuseaufrufen. Die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab allocatieren.

Nach dem Aufrufen WdfUsbTargetDeviceFormatRequestForUrb zum Formatieren einer E/A-Anforderung muss der Treiber WdfRequestSend aufrufen, um die Anforderung (synchron oder asynchron) an ein E/A-Ziel zu senden. Verwenden Sie nicht die Option Senden und Vergessen, um die Anforderung zu senden.

Mehrere Aufrufe an WdfUsbTargetDeviceFormatRequestForUrb, 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), neu formatieren (Aufruf WdfUsbTargetDeviceFormatRequestForUrb) 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 WdfUsbTargetDeviceFormatRequestForUrb 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 zu den WdfUsbTargetDeviceFormatRequestForUrb Methode und USB-E/A-Zielen finden Sie unter USB I/O Targets.

Beispiele

Im folgenden Codebeispiel wird ein Speicherobjekt zum Speichern einer URB-Struktur erstellt, die URB-Struktur initialisiert und WdfUsbTargetDeviceFormatRequestForUrb aufgerufen, um eine Anforderung zu formatieren, die den Inhalt der URB-Struktur verwendet. Anschließend registriert das Beispiel eine CompletionRoutine Rückruffunktion und sendet die Anforderung an ein E/A-Ziel.

WDFMEMORY urbMemory;
URB *urbBuffer;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST),
                         &urbMemory,
                         NULL
                         );

if (!NT_SUCCESS(status)){
    return status;
}
urbBuffer = (PURB) WdfMemoryGetBuffer(
                                      urbMemory,
                                      NULL
                                      );
urbBuffer->UrbHeader.Function =  URB_FUNCTION_GET_CONFIGURATION;
urbBuffer->UrbHeader.Length = sizeof(struct _URB_CONTROL_GET_CONFIGURATION_REQUEST);
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferLength = 1 ;
urbBuffer->UrbControlGetConfigurationRequest.TransferBufferMDL = NULL;
urbBuffer->UrbControlGetConfigurationRequest.TransferBuffer = outBuffer;
urbBuffer->UrbControlGetConfigurationRequest.UrbLink = NULL;

status = WdfUsbTargetDeviceFormatRequestForUrb(
                                               deviceContext->WdfUsbTargetDevice,
                                               request,
                                               urbMemory,
                                               NULL
                                               );
WdfRequestSetCompletionRoutine(
                              request,
                              MyCompletionRoutine,
                              NULL);

if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

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)