WinUsb_ReadPipe (winusb.h)

Artikel
08/27/2023

Fungsi WinUsb_ReadPipe membaca data dari pipa yang ditentukan.

Sintaks

BOOL WinUsb_ReadPipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Parameter

[in] InterfaceHandle

Handel buram ke antarmuka yang berisi titik akhir yang dikaitkan dengan pipa.

Untuk membaca data dari pipa yang terkait dengan titik akhir di antarmuka pertama, gunakan handel yang dikembalikan oleh WinUsb_Initialize. Untuk semua antarmuka lainnya, gunakan handel ke antarmuka target, yang diambil oleh WinUsb_GetAssociatedInterface.

[in] PipeID

PipeID sesuai dengan bidang bEndpointAddress di deskriptor titik akhir. Untuk informasi tentang tata letak bidang ini, lihat Tabel 9-13 di "Universal Serial Bus Specification Revisi 2.0" di USB Technology. Di bidang bEndpointAddress , Bit 7 menunjukkan arah titik akhir: 0 untuk OUT; 1 untuk IN.

[out] Buffer

Buffer yang dialokasikan penelepon yang menerima data yang dibaca.

[in] BufferLength

Jumlah maksimum byte yang akan dibaca. Angka ini harus kurang dari atau sama dengan ukuran, dalam byte, dari Buffer.

[out, optional] LengthTransferred

Penunjuk ke variabel ULONG yang menerima jumlah byte aktual yang disalin ke dalam Buffer. Untuk informasi selengkapnya, lihat Keterangan.

[in, optional] Overlapped

Penunjuk opsional ke struktur TUMPANG TINDIH yang digunakan untuk operasi asinkron. Jika parameter ini ditentukan, WinUsb_ReadPipe segera kembali daripada menunggu secara sinkron agar operasi selesai sebelum kembali. Peristiwa disinyalkan ketika operasi selesai.

Nilai kembali

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

GetLastError dapat mengembalikan kode kesalahan berikut.

Menampilkan kode	Deskripsi
ERROR_INVALID_HANDLE	Pemanggil melewati NULL dalam parameter InterfaceHandle .
ERROR_IO_PENDING	Operasi I/O yang tumpang tindih sedang berlangsung tetapi belum selesai. Jika operasi yang tumpang tindih tidak dapat segera diselesaikan, fungsi mengembalikan FALSE dan fungsi GetLastError mengembalikan ERROR_IO_PENDING, menunjukkan bahwa operasi dijalankan di latar belakang. Panggil WinUsb_GetOverlappedResult untuk memeriksa keberhasilan atau kegagalan operasi.
ERROR_NOT_ENOUGH_MEMORY	Memori tidak cukup untuk melakukan operasi.
ERROR_SEM_TIMEOUT	Operasi baca yang dimulai oleh WinUsb_ReadPipe di tumpukan USB kehabisan waktu sebelum operasi dapat diselesaikan.

Keterangan

Jika data yang dikembalikan oleh perangkat lebih besar dari panjang transfer maksimum, WinUSB membagi permintaan menjadi permintaan yang lebih kecil dengan panjang transfer maksimum dan mengirimkannya secara serial. Jika panjang transfer bukan kelipatan ukuran paket maksimum titik akhir (dapat diambil melalui anggota MaximumPacketSize struktur WINUSB_PIPE_INFORMATION), WinUSB meningkatkan ukuran transfer ke kelipatan MaximumPacketSize berikutnya.

Ukuran paket USB tidak memperhitungkan transfer untuk permintaan baca. Jika perangkat merespons dengan paket yang terlalu besar untuk buffer klien, perilaku permintaan baca sesuai dengan jenis kebijakan yang ditetapkan pada pipa. Jika jenis kebijakan untuk pipa ALLOW_PARTIAL_READS, WinUSB menambahkan data yang tersisa ke awal transfer berikutnya. Jika ALLOW_PARTIAL_READS tidak diatur, permintaan baca gagal. Untuk informasi selengkapnya tentang jenis kebijakan, lihat Fungsi WinUSB untuk Modifikasi Kebijakan Pipa.

Jika aplikasi melewati NULL dalam parameter Tumpang Tindih (operasi sinkron), aplikasi harus memastikan bahwa LengthTransferred bukan NULL, bahkan ketika operasi baca tidak menghasilkan data output.

Jika Tumpang tindih bukan NULL (operasi asinkron), LengthTransferred dapat diatur ke NULL. Untuk operasi yang tumpang tindih (dan jika LengthTransferred adalah nilai non-NULL ), nilai yang diterima dalam LengthTransferred setelah pengembalian WinUsb_ReadPipe tidak berarti sampai operasi yang tumpang tindih selesai. Untuk mengambil jumlah byte aktual yang dibaca dari pipa, panggil WinUsb_GetOverlappedResult.

Ketika tidak ada data yang tersedia di titik akhir (pipa kosong), WinUsb_ReadPipe tidak kembali sampai ada data dalam pipa. Jika kondisi kesalahan terjadi atau batas waktu yang ditentukan aplikasi kedaluwarsa, WinUsb_ReadPipe selalu mengembalikan FALSE. Untuk menentukan alasan sebenarnya untuk nilai pengembalian tersebut, selalu panggil GetLastError. Misalnya, dalam kasus ini nilai kesalahan GetLastError menunjukkan alasan sebenarnya:

Jika aplikasi menentukan nilai batas waktu dalam kebijakan pipa dan batas waktu tersebut kedaluwarsa, WinUsb_ReadPipe mengembalikan FALSE dan GetLastError mengembalikan ERROR_SEM_TIMEOUT.
Jika kondisi kesalahan terjadi saat membaca data dari pipa, WinUsb_ReadPipe mengembalikan FALSE dan GetLastError mengembalikan ERROR_GEN_FAILURE.