WdfUsbTargetDeviceSendControlTransferSynchronously-Funktion (wdfusb.h)

[Gilt für KMDF und UMDF]

Die WdfUsbTargetDeviceSendControlTransferSynchronously-Methode erstellt eine USB-Steuerungsübertragungsanforderung und sendet sie synchron an ein I/O-Ziel.

Syntax

NTSTATUS WdfUsbTargetDeviceSendControlTransferSynchronously(
  [in]            WDFUSBDEVICE                  UsbDevice,
  [in, optional]  WDFREQUEST                    Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS     RequestOptions,
  [in]            PWDF_USB_CONTROL_SETUP_PACKET SetupPacket,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR        MemoryDescriptor,
  [out, optional] PULONG                        BytesTransferred
);

Parameter

[in] UsbDevice

Ein Handle zu einem USB-Geräteobjekt, das von einem vorherigen Aufruf von WdfUsbTargetDeviceCreateWithParameters abgerufen wurde.

[in, optional] Request

Ein Handle zu einem Framework-Anforderungsobjekt. Dieser Parameter ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in, optional] RequestOptions

Ein Zeiger auf eine anrufer zugewiesene WDF_REQUEST_SEND_OPTIONS Struktur, die Optionen für die Anforderung angibt. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] SetupPacket

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

[in, optional] MemoryDescriptor

Ein Zeiger auf eine vom Anrufer zugewiesene WDF_MEMORY_DESCRIPTOR Struktur, die entweder eine Eingabe oder einen Ausgabepuffer beschreibt, abhängig vom gerätespezifischen Befehl. Dieser Zeiger ist optional und kann NULL sein. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[out, optional] BytesTransferred

Ein Zeiger auf einen Speicherort, der die Anzahl der Bytes empfängt, die übertragen werden. Dieser Parameter ist optional und kann NULL sein.

Rückgabewert

WdfUsbTargetDeviceSendControlTransferSynchronously gibt den Statuswert des I/O-Ziels 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
Unzureichender Arbeitsspeicher war verfügbar.
STATUS_INVALID_DEVICE_REQUEST
Ein ungültiger Speicherdeskriptor wurde angegeben, oder die angegebene I/O-Anforderung wurde bereits an ein I/O-Ziel in die Warteschlange gestellt.
STATUS_IO_TIMEOUT
Der Treiber hat einen Timeoutwert bereitgestellt und die Anforderung wurde innerhalb der zugewiesenen Zeit nicht abgeschlossen.
 

Diese Methode kann auch andere NTSTATUS-Werte zurückgeben.

Eine Fehlerprüfung tritt auf, wenn der Treiber einen ungültigen Objekthandpunkt bereitstellt.

Bemerkungen

Verwenden Sie die WdfUsbTargetDeviceSendControlTransferSynchronously-Methode , um eine USB-Steuerelementübertragungsanforderung synchron zu senden. Um solche Anforderungen asynchron zu senden, verwenden Sie WdfUsbTargetDeviceFormatRequestForControlTransfer, gefolgt von WdfRequestSend.

Die WdfUsbTargetDeviceSendControlTransferSynchronously-Methode gibt erst zurück, wenn die Anforderung abgeschlossen ist, sofern der Treiber keinen Timeoutwert in der WDF_REQUEST_SEND_OPTIONS Struktur bereitstellt, auf die der RequestOptions-Parameter verweist, oder es sei denn, ein Fehler wird erkannt.

Sie können eine I/O-Anforderung weiterleiten, die Ihr Treiber in einer I/O-Warteschlange empfangen 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 einen Pufferraum.

So weiterleiten Sie eine I/O-Anforderung, die Ihr Treiber in einer I/O-Warteschlange empfangen hat:

  1. Geben Sie den Handle der empfangenen Anforderung für den Anforderungsparameter an.
  2. Verwenden Sie den Eingabe- oder Ausgabepuffer der empfangenen Anforderung für den MemoryDescriptor-Parameter .

    Der Treiber kann WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufrufen, um ein Handle zu einem Framework-Speicherobjekt abzurufen, das den Eingabe- oder Ausgabepuffer der Anforderung darstellt, und platzieren Sie dann den Handle in der WDF_MEMORY_DESCRIPTOR Struktur, die der Treiber für den MemoryDescriptor-Parameter bereitstellt.

So erstellen und senden Sie eine neue Anforderung:
  1. Geben Sie einen NULL-Anforderungshandpunkt im Anforderungsparameter an, oder erstellen Sie ein neues Anforderungsobjekt und geben Sie seinen Handle an:
    • Wenn Sie einen NULL-Anforderungshandpunkt angeben, verwendet das Framework ein internes Anforderungsobjekt. Diese Technik ist einfach zu verwenden, aber der Treiber kann die Anforderung nicht abbrechen.
    • Wenn Sie WdfRequestCreate aufrufen, um eine oder mehrere Anforderungsobjekte zu erstellen, können Sie diese Anforderungsobjekte wiederverwenden, indem Sie WdfRequestReuse aufrufen. Diese Technik ermöglicht die EvtDriverDeviceAdd-Rückruffunktion Ihres Treibers, um Anforderungsobjekte für ein Gerät vorzuschreiben. Darüber hinaus kann ein weiterer Treiberthread WdfRequestCancelSentRequest aufrufen, um die Anforderung bei Bedarf abzubrechen.

    Ihr Treiber kann einen Parameter ohne NULL-Anforderungsoptions angeben, ob der Treiber keinen NULL- oder NULL-Anforderungsparameter bereitstellt. Sie können z. B. den RequestOptions-Parameter verwenden, um einen Timeoutwert anzugeben.

  2. Geben Sie Pufferraum für den Parameter "MemoryDescriptor" der WdfUsbTargetDeviceSendControlTransferSynchronously-Methode an.

    Ihr Treiber kann diesen Pufferraum als lokal zugewiesenen Puffer angeben, als WDFMEMORY-Handle oder als MDL. Sie können verwenden, welche Methode am bequemsten ist.

    Wenn erforderlich, konvertiert das Framework die Pufferbeschreibung in eine, die für die I/O-Zielmethode für den Zugriff auf Datenpuffer korrekt ist.

    Die folgenden Techniken sind verfügbar:

    • Bereitstellen eines lokalen Puffers

      Da WdfUsbTargetDeviceSendControlTransferSynchronously I/O-Anforderungen synchron verarbeitet, kann der Treiber Anforderungspuffer erstellen, die lokal auf die Aufrufroutine sind, wie im folgenden Codebeispiel dargestellt.

      WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
      MY_BUFFER_TYPE  myBuffer;
      WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                        (PVOID) &myBuffer,
                                        sizeof(myBuffer));
      
    • Bereitstellen eines WDFMEMORY-Handles

      Rufen Sie WdfMemoryCreate oder WdfMemoryCreatePreallocated auf, um einen Handle für framework verwalteten Arbeitsspeicher abzurufen, wie im folgenden Codebeispiel gezeigt.

      WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
      WDFMEMORY  memoryHandle = NULL;
      status = WdfMemoryCreate(NULL,
                               NonPagedPool,
                               POOL_TAG,
                               MY_BUFFER_SIZE,
                               &memoryHandle,
                               NULL);
      WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&memoryDescriptor,
                                        memoryHandle,
                                        NULL);
      

      Alternativ kann der Treiber WdfRequestRetrieveInputMemory oder WdfRequestRetrieveOutputMemory aufrufen, um einen Handle zu einem Framework-Speicherobjekt abzurufen, das den Puffer einer empfangenen I/O-Anforderung darstellt, wenn der Treiber den Inhalt dieses Puffers an das I/O-Ziel übergeben soll. Der Treiber muss die empfangene I/O-Anforderung erst abschließen, wenn die neue Anforderung , die WdfUsbTargetDeviceSendControlTransferSynchronously sendet, an das I/O-Ziel gesendet wurde, gelöscht, wiederverwendet oder neu formatiert wurde. (WdfUsbTargetDeviceSendControlTransferSynchronously erhöht die Referenzanzahl des Speicherobjekts. Löschen, Reusieren oder Reformieren eines Anforderungsobjekts dekrementiert die Referenzanzahl des Speicherobjekts.)

    • Bereitstellen einer MDL

      Treiber können MDLs abrufen, die einer empfangenen I/O-Anforderung zugeordnet sind, indem Sie WdfRequestRetrieveInputWdmMdl oder WdfRequestRetrieveOutputWdmMdl aufrufen.

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 I/O-Anforderung finden Sie unter Abrufen von Abschlussinformationen.

Weitere Informationen zur WdfUsbTargetDeviceSendControlTransferSynchronously-Methode und USB-I/O-Zielen finden Sie unter USB-I/O-Ziele.

Beispiele

Im folgenden Codebeispiel wird eine WDF_USB_CONTROL_SETUP_PACKET-Struktur initialisiert und dann WdfUsbTargetDeviceSendControlTransferSynchronously aufgerufen, um eine anbieterspezifische Steuerelementübertragung zu senden.

WDF_USB_CONTROL_SETUP_PACKET  controlSetupPacket;

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR(
                                         &controlSetupPacket,
                                         BmRequestHostToDevice,
                                         BmRequestToDevice,
                                         USBFX2LK_REENUMERATE,
                                         0,
                                         0
                                         );

status = WdfUsbTargetDeviceSendControlTransferSynchronously(
                                         UsbDevice,
                                         WDF_NO_HANDLE,
                                         NULL,
                                         &controlSetupPacket,
                                         NULL,
                                         NULL
                                         );
return status;

Anforderungen

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfusb.h (enthalten Wdfusb.h)
Bibliothek Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI-Complianceregeln DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Weitere Informationen

WDF_USB_CONTROL_SETUP_PACKET

WDF_USB_CONTROL_SETUP_PACKET_INIT_VENDOR

WdfRequestCancelSentRequest

WdfUsbTargetDeviceFormatRequestForControlTransfer

WdfUsbTargetDeviceSendUrbSynchronously