WdfUsbTargetDeviceSendControlTransferSynchronously function (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceSendControlTransferSynchronously membangun permintaan transfer kontrol USB dan mengirimkannya secara sinkron ke target I/O.

Sintaks

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

Handel ke objek perangkat USB yang diperoleh dari panggilan sebelumnya ke WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Request

Handel ke objek permintaan kerangka kerja. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, optional] RequestOptions

Penunjuk ke struktur WDF_REQUEST_SEND_OPTIONS yang dialokasikan pemanggil yang menentukan opsi untuk permintaan. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in] SetupPacket

Penunjuk ke struktur WDF_USB_CONTROL_SETUP_PACKET yang dialokasikan penelepon yang menjelaskan transfer kontrol.

[in, optional] MemoryDescriptor

Penunjuk ke struktur WDF_MEMORY_DESCRIPTOR yang dialokasikan pemanggil yang menjelaskan buffer input atau output, tergantung pada perintah khusus perangkat. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[out, optional] BytesTransferred

Penunjuk ke lokasi yang menerima jumlah byte yang ditransfer. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfUsbTargetDeviceSendControlTransferSynchronously mengembalikan nilai status penyelesaian target I/O jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup tersedia.
STATUS_INVALID_DEVICE_REQUEST	Deskriptor memori yang tidak valid ditentukan, atau permintaan I/O yang ditentukan sudah diantrekan ke target I/O.
STATUS_IO_TIMEOUT	Driver memberikan nilai waktu habis dan permintaan tidak selesai dalam waktu yang dialokasikan.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Gunakan metode WdfUsbTargetDeviceSendControlTransferSynchronously untuk mengirim permintaan transfer kontrol USB secara sinkron. Untuk mengirim permintaan tersebut secara asinkron, gunakan WdfUsbTargetDeviceFormatRequestForControlTransfer, diikuti oleh WdfRequestSend.

Metode WdfUsbTargetDeviceSendControlTransferSynchronously tidak kembali sampai permintaan selesai, kecuali driver menyediakan nilai waktu habis dalam struktur WDF_REQUEST_SEND_OPTIONS yang ditunjuk parameter RequestOptions , atau kecuali jika kesalahan terdeteksi.

Anda dapat meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O, atau Anda dapat membuat dan mengirim permintaan baru. Dalam kedua kasus, kerangka kerja memerlukan objek permintaan dan, tergantung pada jenis transfer kontrol, mungkin beberapa ruang buffer.

Untuk meneruskan permintaan I/O yang diterima driver Anda dalam antrean I/O:

Tentukan handel permintaan yang diterima untuk parameter Permintaan .
Gunakan buffer input atau output permintaan yang diterima untuk parameter MemoryDescriptor .
Driver dapat memanggil WdfRequestRetrieveInputMemory atau WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer input atau output permintaan dan kemudian menempatkan handel tersebut dalam struktur WDF_MEMORY_DESCRIPTOR yang disediakan driver untuk parameter MemoryDescriptor .

Untuk membuat dan mengirim permintaan baru:

Berikan handel permintaan NULL di parameter Permintaan , atau buat objek permintaan baru dan berikan handelnya:
- Jika Anda menyediakan handel permintaan NULL , kerangka kerja menggunakan objek permintaan internal. Teknik ini mudah digunakan, tetapi driver tidak dapat membatalkan permintaan.
- Jika Anda memanggil WdfRequestCreate untuk membuat satu atau beberapa objek permintaan, Anda dapat menggunakan kembali objek permintaan ini dengan memanggil WdfRequestReuse. Teknik ini memungkinkan fungsi panggilan balik EvtDriverDeviceAdd driver Anda untuk melakukan pra-alokasi objek permintaan untuk perangkat. Selain itu, utas driver lain dapat memanggil WdfRequestCancelSentRequest untuk membatalkan permintaan, jika perlu.
Driver Anda dapat menentukan parameter RequestOptionsnon-NULL, baik driver menyediakan parameter permintaannon-NULL atau NULL. Anda dapat, misalnya, menggunakan parameter RequestOptions untuk menentukan nilai waktu habis.
Berikan ruang buffer untuk parameter MemoryDescriptor metode WdfUsbTargetDeviceSendControlTransferSynchronously.
Driver Anda dapat menentukan ruang buffer ini sebagai buffer yang dialokasikan secara lokal, sebagai handel WDFMEMORY, atau sebagai MDL. Anda dapat menggunakan metode mana pun yang paling nyaman.

Jika perlu, kerangka kerja mengonversi deskripsi buffer menjadi deskripsi yang benar untuk metode target I/O untuk mengakses buffer data.

Teknik berikut tersedia:
- Menyediakan buffer lokal
  Karena WdfUsbTargetDeviceSendControlTransferSynchronously menangani permintaan I/O secara sinkron, driver dapat membuat buffer permintaan yang lokal untuk rutinitas panggilan, seperti yang ditunjukkan dalam contoh kode berikut.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Menyediakan handel WDFMEMORY
  Panggil WdfMemoryCreate atau WdfMemoryCreatePreallocated untuk mendapatkan handel ke memori yang dikelola kerangka kerja, seperti yang ditunjukkan dalam contoh kode berikut.
```
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);
```
  Atau, driver dapat memanggil WdfRequestRetrieveInputMemory atau WdfRequestRetrieveOutputMemory untuk mendapatkan handel ke objek memori kerangka kerja yang mewakili buffer permintaan I/O yang diterima, jika Anda ingin driver meneruskan konten buffer tersebut ke target I/O. Driver tidak boleh menyelesaikan permintaan I/O yang diterima sampai permintaan baru yang dikirim WdfUsbTargetDeviceSendControlTransferSynchronously ke target I/O telah dihapus, digunakan kembali, atau diformat ulang. (WdfUsbTargetDeviceSendControlTransferSynchronously menaikkan jumlah referensi objek memori. Menghapus, menggunakan kembali, atau memformat ulang objek permintaan mengurangi jumlah referensi objek memori.)
- Menyediakan MDL
  Driver dapat memperoleh MDL yang terkait dengan permintaan I/O yang diterima dengan memanggil WdfRequestRetrieveInputWdmMdl atau WdfRequestRetrieveOutputWdmMdl.

Kerangka kerja menetapkan bendera USBD_SHORT_TRANSFER_OK di URB internalnya. Mengatur bendera ini memungkinkan paket terakhir transfer data menjadi kurang dari ukuran paket maksimum.

Untuk informasi tentang mendapatkan informasi status setelah permintaan I/O selesai, lihat Mendapatkan Informasi Penyelesaian.

Untuk informasi selengkapnya tentang metode WdfUsbTargetDeviceSendControlTransferSynchronously dan target I/O USB, lihat Target I/O USB.

Contoh

Contoh kode berikut menginisialisasi struktur WDF_USB_CONTROL_SETUP_PACKET lalu memanggil WdfUsbTargetDeviceSendControlTransferSynchronously untuk mengirim transfer kontrol khusus vendor.

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;

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Versi UMDF minimum	2.0
Header	wdfusb.h (termasuk Wdfusb.h)
Pustaka	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestForUrbXrb(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)