WinUsb_ControlTransfer (winusb.h)

Artikel
08/27/2023

Fungsi WinUsb_ControlTransfer mengirimkan data kontrol melalui titik akhir kontrol default.

Sintaks

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parameter

[in] InterfaceHandle

Handel buram ke antarmuka dalam konfigurasi yang dipilih.

Untuk menentukan penerima permintaan kontrol sebagai seluruh perangkat atau antarmuka pertama, gunakan handel yang dikembalikan oleh WinUsb_Initialize. Untuk semua antarmuka lainnya, dapatkan handel ke antarmuka target dengan memanggil WinUsb_GetAssociatedInterface, lalu panggil WinUsb_ControlTransfer dengan menentukan handel antarmuka yang diperoleh.

[in] SetupPacket

Paket penyiapan 8-byte jenis WINUSB_SETUP_PACKET.

[out] Buffer

Buffer yang dialokasikan penelepon yang berisi data yang akan ditransfer. Panjang buffer ini tidak boleh melebihi 4KB.

[in] BufferLength

Jumlah byte yang akan ditransfer, tidak termasuk paket penyiapan. Angka ini harus kurang dari atau sama dengan ukuran, dalam byte, dari Buffer.

[out, optional] LengthTransferred

Penunjuk ke variabel ULONG yang menerima jumlah aktual byte yang ditransfer. Jika aplikasi tidak mengharapkan data apa pun ditransfer selama fase data (BufferLength adalah nol), LengthTransferred dapat berupa NULL.

[in, optional] Overlapped

Penunjuk opsional ke struktur TUMPANG TINDIH , yang digunakan untuk operasi asinkron. Jika parameter ini ditentukan, WinUsb_ControlTransfer segera kembali, dan peristiwa disinyalir ketika operasi selesai. Jika Tumpang tindih tidak disediakan, fungsi WinUsb_ControlTransfer mentransfer data secara sinkron.

Mengembalikan nilai

WinUsb_ControlTransfer mengembalikan TRUE jika operasi berhasil. Jika tidak, rutinitas ini mengembalikan FALSE, dan pemanggil dapat mengambil kesalahan yang dicatat dengan memanggil GetLastError.

GetLastError dapat mengembalikan salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_INVALID_HANDLE	Pemanggil melewati NULL dalam parameter InterfaceHandle .
ERROR_NOT_ENOUGH_MEMORY	Menunjukkan bahwa memori tidak cukup untuk melakukan operasi.

Keterangan

Permintaan kontrol selalu dikirim oleh host ke titik akhir default perangkat USB tetapi penerima permintaan dapat menjadi seluruh perangkat, antarmuka, atau titik akhir dalam pengaturan alternatif yang dipilih. Dalam panggilan WinUsb_ControlTransfer , aplikasi harus menunjukkan penerima melalui dua parameter: InterfaceHandle dan SetupPacket.

Jika penerima permintaan kontrol adalah seluruh perangkat, antarmuka pertama, atau titik akhir apa pun di antarmuka tersebut, aplikasi harus menggunakan handel yang dikembalikan oleh WinUsb_Initialize. Jika penerima adalah antarmuka lain atau titik akhirnya, maka aplikasi harus mendapatkan handel WinUSB yang terkait dengan antarmuka target dengan memanggil WinUsb_GetAssociatedInterface, lalu memanggil WinUsb_ControlTransfer dengan menentukan handel antarmuka yang diperoleh.

Sesuai Bagian 9.3 dari spesifikasi USB resmi, token pengaturan transfer kontrol berisi informasi tentang permintaan tersebut. Untuk aplikasi WinUSB, token penyiapan tersebut dijelaskan dengan menggunakan struktur WINUSB_SETUP_PACKET .

Dalam token penyiapan, bidang bmRequestType dan wIndex digunakan untuk menunjukkan penerima permintaan. Bidang-bidang tersebut masing-masing sesuai dengan anggota RequestType dan IndexWINUSB_SETUP_PACKET.

Dua bit requestType terendah menunjukkan penerima permintaan. Penerima dapat berupa perangkat, antarmuka, titik akhir, atau lainnya (untuk permintaan vendor). Bergantung pada penerima, byte Indeks yang lebih rendah menunjukkan indeks penerima yang ditentukan perangkat. Nilai Indeks tergantung pada jenis permintaan. Misalnya, untuk permintaan kontrol standar, nilainya adalah 0, atau menunjukkan antarmuka atau nomor titik akhir. Untuk jenis permintaan standar tertentu, seperti permintaan GET_DESCRIPTOR untuk mendapatkan deskriptor string, nilai Indeks menunjukkan ID Bahasa.

Jika penerima adalah perangkat, aplikasi harus mengatur nilai RequestType dan Index . Dua bit terendah dari nilai RequestType harus 0. Byte nilai Indeks yang lebih rendah tergantung pada jenis permintaan. InterfaceHandle harus berupa handel WinUSB yang dikembalikan oleh WinUsb_Initialize.

Jika penerima permintaan adalah antarmuka, aplikasi harus mengatur dua bit requestType terendah ke 0x01. Aplikasi tidak diperlukan untuk mengatur byte Indeks yang lebih rendah untuk semua jenis permintaan. Untuk permintaan standar, kelas, dan vendor, Winusb.sys menetapkan nilai ke nomor antarmuka antarmuka target. InterfaceHandle harus dikaitkan dengan antarmuka target. Aplikasi dapat memperoleh handel tersebut dengan memanggil WinUsb_GetAssociatedInterface.

Jika penerima adalah titik akhir, aplikasi harus mengatur dua bit RequestType terendah ke 0x02 dan byte Indeks yang lebih rendah ke alamat titik akhir. Dalam hal ini, InterfaceHandle dikaitkan dengan antarmuka yang berisi titik akhir. Aplikasi dapat memperoleh handel tersebut dengan memanggil WinUsb_GetAssociatedInterface.