WdfUsbTargetDeviceFormatRequestForControlTransfer-Funktion (wdfusb.h)

  • Artikel

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceFormatRequestForControlTransfer-Methode erstellt eine USB-Steuerelementübertragungsanforderung, sendet die Anforderung jedoch nicht.

Syntax

NTSTATUS WdfUsbTargetDeviceFormatRequestForControlTransfer(
  [in]           WDFUSBDEVICE                  UsbDevice,
  [in]           WDFREQUEST                    Request,
  [in]           PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional] WDFMEMORY                     TransferMemory,
  [in, optional] PWDFMEMORY_OFFSET             TransferOffset
);

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

Ein Zeiger auf eine vom Aufrufer zugewiesene WDF_USB_CONTROL_SETUP_PACKET Struktur, die die Steuerungsübertragung beschreibt.

[in, optional] TransferMemory

Ein Handle für ein Frameworkspeicherobjekt, das abhängig vom gerätespezifischen Befehl entweder einen Eingabe- oder einen Ausgabepuffer beschreibt. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] TransferOffset

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 und länge innerhalb des Puffers zu bestimmen, den TransferMemory angibt. Wenn dieser Zeiger NULL ist, verwendet das Framework den gesamten Puffer.

Rückgabewert

WdfUsbTargetDeviceFormatRequestForControlTransfer 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 war verfügbar.
STATUS_INVALID_DEVICE_REQUEST
 Es wurde ein ungültiger Speicherdeskriptor angegeben, oder die angegebene E/A-Anforderung wurde bereits an ein E/A-Ziel in die Warteschlange gestellt.
 

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 WdfUsbTargetDeviceFormatRequestForControlTransfer gefolgt von WdfRequestSend, um eine USB-Steuerungsübertragungsanforderung synchron oder asynchron zu senden. Alternativ können Sie die WdfUsbTargetDeviceSendControlTransferSynchronously-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. In beiden Fällen erfordert das Framework ein Anforderungsobjekt und je nach Art der Steuerungsübertragung möglicherweise etwas Pufferspeicher.

So leiten Sie eine E/A-Anforderung weiter, die Ihr Treiber in einer E/A-Warteschlange empfangen hat:

  1. Geben Sie das Handle der empfangenen Anforderung für den Request-Parameter der WdfUsbTargetDeviceFormatRequestForControlTransfer-Methode an.
  2. Verwenden Sie den Eingabe- oder Ausgabepuffer der empfangenen Anforderung für den TransferMemory-Parameter .

    Der Treiber muss WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufrufen, um ein Handle für ein Framework-Speicherobjekt abzurufen, das den Eingabe- oder Ausgabepuffer der Anforderung darstellt, und dieses Handle als Wert für TransferMemory verwenden.

So erstellen Sie eine neue E/A-Anforderung und einen neuen Puffer:
  1. Erstellen Sie ein neues Anforderungsobjekt, und geben Sie dessen Handle für den Request-Parameter der WdfUsbTargetDeviceFormatRequestForControlTransfer-Methode an.

    Rufen Sie WdfRequestCreate auf , um ein oder mehrere Anforderungsobjekte vorab zuzulisten. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Die Rückruffunktion EvtDriverDeviceAdd ihres Treibers kann Anforderungsobjekte für ein Gerät vorab zuweisungen.

  2. Geben Sie Pufferspeicher an, und geben Sie das Handle des Puffers für den TransferMemory-Parameter der WdfUsbTargetDeviceFormatRequestForControlTransfer-Methode an.

    Ihr Treiber muss diesen Pufferspeicher als WDFMEMORY-Handle für den vom Framework verwalteten Arbeitsspeicher angeben. Ihr Treiber kann eine der folgenden Aktionen ausführen:

    Wenn Ihr Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufruft und das Speicherhandle an WdfUsbTargetDeviceFormatRequestForControlTransfer übergibt, darf der Treiber die empfangene E/A-Anforderung erst abschließen, nachdem der Treiber das neue, vom Treiber erstellte Anforderungsobjekt gelöscht, wiederverwendet oder neu erstellt hat. (WdfUsbTargetDeviceFormatRequestForControlTransfer erhöht die Verweisanzahl des Speicherobjekts. Durch das Löschen, Erneutes Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Verweisanzahl des Speicherobjekts verringert.)
Nach dem Aufrufen von WdfUsbTargetDeviceFormatRequestForControlTransfer 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 WdfUsbTargetDeviceFormatRequestForControlTransfer , 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 WdfUsbTargetDeviceFormatRequestForControlTransfer) 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 WdfUsbTargetDeviceFormatRequestForControlTransfer 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.)

Das Framework legt das USBD_SHORT_TRANSFER_OK-Flag in seiner internen URB fest. Durch Festlegen dieses Flags kann das letzte Paket einer Datenübertragung kleiner als die maximale Paketgröße sein.

Informationen zum Abrufen status Informationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

Weitere Informationen zur WdfUsbTargetDeviceFormatRequestForControlTransfer-Methode und USB-E/A-Zielen finden Sie unter USB-E/A-Ziele.

Beispiele

Das folgende Codebeispiel erstellt ein Anforderungsobjekt und ein Speicherobjekt und initialisiert dann eine WDF_USB_CONTROL_SETUP_PACKET-Struktur für eine "get status"-Steuerelementübertragung. Als Nächstes ruft das Beispiel WdfUsbTargetDeviceFormatRequestForControlTransfer auf, um die Anforderung zu formatieren. Anschließend legt das Beispiel eine CompletionRoutine-Rückruffunktion fest und sendet die Anforderung an ein E/A-Ziel.

WDF_USB_CONTROL_SETUP_PACKET packet;
NTSTATUS status;
WDF_OBJECT_ATTRIBUTES attributes;
WDFMEMORY memHandle;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);

status = WdfRequestCreate(
                          &attributes,
                          WdfUsbTargetDeviceGetIoTarget(
                              UsbTargetDevice,
                              &request
                              )
                          );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = request;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         sizeof(USHORT),
                         &memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS(
                                             &packet,
                                             BmRequestToDevice,
                                             0
                                             );
status = WdfUsbTargetDeviceFormatRequestForControlTransfer(
                         UsbTargetDevice,
                         request,
                         &packet,
                         memHandle,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyCompletionRoutine,
                               NULL
                               );
if (WdfRequestSend(
                   request,
                   WdfUsbTargetDeviceGetIoTarget(UsbTargetDevice),
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Anforderungen

Anforderung Wert
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Kopfzeile wdfusb.h (einschließlich Wdfusb.h)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <=DISPATCH_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestForUrbXrb(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Weitere Informationen

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS

WdfUsbTargetDeviceSendControlTransferSynchronly