WdfUsbTargetDeviceFormatRequestForUrb-Funktion (wdfusb.h)
[Gilt nur für KMDF]
Die WdfUsbTargetDeviceFormatRequestForUrb-Methode erstellt eine USB-Anforderung für ein angegebenes USB-Gerät unter Verwendung von Anforderungsparametern, die von einer URB beschrieben werden, aber die Anforderung wird nicht gesendet.
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 WdfUsbTargetDeviceCreateWithParameters 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 oder einen der Union-Member der Struktur enthält. (Alle Union-Member der URB-Struktur enthalten die _URB_HEADER-Struktur .)
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. Andernfalls wird eine Fehlerüberprüfung durchgeführt.
[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
WdfUsbTargetDeviceFormatRequestForUrb gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls kann diese Methode einen der folgenden Werte zurückgeben:
| Rückgabecode | Beschreibung |
|---|---|
|
Ein ungültiger Parameter wurde erkannt. |
|
Es war nicht genügend Arbeitsspeicher vorhanden. |
|
Der Offset, den der usbMemoryOffset-Parameter angegeben hat, war ungültig. |
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 WdfUsbTargetDeviceFormatRequestForUrb gefolgt von WdfRequestSend, um eine USB-Steuerübertragungsanforderung entweder synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetDeviceSendUrbSynchronously-Methode verwenden, um eine Anforderung synchron zu senden.
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 WdfUsbTargetDeviceFormatRequestForUrb-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 WdfUsbTargetDeviceFormatRequestForUrb-Methode an. Sie können das Anforderungsobjekt wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion EvtDriverDeviceAdd Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab zuweisungen.
Nach dem Aufrufen von 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 von WdfUsbTargetDeviceFormatRequestForUrb , 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 ( WdfUsbTargetDeviceFormatRequestForUrb 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 WdfUsbTargetDeviceFormatRequestForUrb 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 WdfUsbTargetDeviceFormatRequestForUrb-Methode und usb-E/A-Zielen finden Sie unter USB-E/A-Ziele.
Beispiele
Im folgenden Codebeispiel wird ein Speicherobjekt erstellt, das eine URB-Struktur enthält, initialisiert die URB-Struktur und ruft WdfUsbTargetDeviceFormatRequestForUrb auf, 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 | 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) |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für