Freigeben über

WdfUsbTargetDeviceFormatRequestForControlTransfer-Funktion (wdfusb.h)

  • Artikel

[Gilt für KMDF und UMDF]

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

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 aus einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParametersabgerufen wurde.

[in] Request

Ein Handle zu einem Framework-Anforderungsobjekt. 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 zu einem Framework-Speicherobjekt, das abhängig vom gerätespezifischen Befehl entweder eine 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, der 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 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-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Verwenden Sie WdfUsbTargetDeviceFormatRequestForControlTransfergefolgt von WdfRequestSend-, um eine USB-Steuerübertragungsanforderung entweder 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 abhängig vom Typ der Steuerungsübertragung möglicherweise einen Pufferraum.

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

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

    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 TransferMemoryverwenden.

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

    Rufen Sie WdfRequestCreate auf, um mindestens ein Anforderungsobjekt vorab zu verwenden. Sie können diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuseaufrufen. Die EvtDriverDeviceAdd Rückruffunktion Ihres Treibers kann Anforderungsobjekte für ein Gerät vorab allocatieren.

  2. Stellen Sie Pufferraum bereit, und geben Sie den Handle des Puffers für den WdfUsbTargetDeviceFormatRequestForControlTransferTransferMemory Parameter der Methode an.

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

    Wenn Ihr Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory- aufruft und den Speicherpunkt an WdfUsbTargetDeviceFormatRequestForControlTransferübergibt, muss der Treiber die empfangene E/A-Anforderung erst nach dem Löschen des Treibers abschließen, das neue anforderungsobjekt, das vom Treiber erstellt wurde, wiederverwendet oder neu formatiert. (WdfUsbTargetDeviceFormatRequestForControlTransfer erhöht die Referenzanzahl des Speicherobjekts. Beim Löschen, Erneuten Verwenden oder Neuformatieren eines Anforderungsobjekts wird die Referenzanzahl des Speicherobjekts erhöht.)
Nach dem Aufrufen 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 an WdfUsbTargetDeviceFormatRequestForControlTransfer, 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 WdfUsbTargetDeviceFormatRequestForControlTransfer) 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 WdfUsbTargetDeviceFormatRequestForControlTransfer 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.)

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 von Statusinformationen nach Abschluss einer E/A-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

Weitere Informationen zu den WdfUsbTargetDeviceFormatRequestForControlTransfer Methode und USB-E/A-Zielen finden Sie unter USB I/O Targets.

Beispiele

Im folgenden Codebeispiel wird ein Anforderungsobjekt und ein Speicherobjekt erstellt, und anschließend wird eine WDF_USB_CONTROL_SETUP_PACKET Struktur für die Übertragung eines "Get Status"-Steuerelements initialisiert. Im nächsten Beispiel wird WdfUsbTargetDeviceFormatRequestForControlTransfer aufgerufen, 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- Universal
Minimale KMDF-Version 1.0
Mindest-UMDF-Version 2.0
Header- wdfusb.h (include Wdfusb.h)
Library 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)

Siehe auch

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_GET_STATUS

WdfUsbTargetDeviceSendControlTransferSynchronously