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 von 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 eines der Union-Member der Struktur enthält. (Alle Unionmitglieder 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 vom Aufrufer zugewiesene WDFMEMORY_OFFSET Struktur, die optionale Byteoffset- und Längenwerte bereitstellt. Das Framework verwendet diese Werte, um die Anfangsadresse der URB im Arbeitsspeicher zu bestimmen, den UrbMemory angibt. Wenn dieser Zeiger NULL ist, befindet sich die URB am Anfang des UrbMemory-Arbeitsspeichers .
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-Steuerungsübertragungsanforderung 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 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 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 zu allocatieren. 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. Daher kann die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers WdfRequestCreate aufrufen, um die Möglichkeit zu verringern, dass WdfRequestCreate zurückgegeben STATUS_INSUFFICIENT_RESOURCES wird, um ein oder mehrere Anforderungsobjekte für ein Gerät vorab zuordnen. Der Treiber kann jedes Anforderungsobjekt anschließend wiederverwenden ( aufrufen WdfRequestReuse), neu formatieren (aufrufen von WdfUsbTargetDeviceFormatRequestForUrb) und erneut senden (aufrufen WdfRequestSend), 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 zugewiesen.)
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, 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 | Universell |
| KMDF-Mindestversion | 1.0 |
| Kopfzeile | wdfusb.h (einschließlich Wdfusb.h) |
| Bibliothek | Wdf01000.sys (siehe Versionierung 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) |