WinUsb_WritePipe (winusb.h)

Artikel
08/27/2023

Fungsi WinUsb_WritePipe menulis data ke pipa.

Sintaks

BOOL WinUsb_WritePipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [in]            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 menulis ke 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.

[in] Buffer

Buffer yang dialokasikan penelepon yang berisi data untuk ditulis.

[in] BufferLength

Jumlah byte yang akan ditulis. 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 ditulis ke pipa. Untuk informasi selengkapnya, lihat Keterangan.

[in, optional] Overlapped

Penunjuk opsional ke struktur YANG TUMPANG TINDIH, yang digunakan untuk operasi asinkron. Jika parameter ini ditentukan, WinUsb_WritePipe segera kembali, dan peristiwa disinyalkan saat operasi selesai.

Nilai kembali

WinUsb_WritePipe 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	Menunjukkan bahwa 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	Menunjukkan bahwa tidak ada cukup memori untuk melakukan operasi.
ERROR_SEM_TIMEOUT	Operasi tulis yang dimulai oleh WinUsb_WritePipe di tumpukan USB kehabisan waktu sebelum operasi dapat diselesaikan.

Keterangan

Untuk membuat permintaan tulis, Anda adalah aplikasi harus mengalokasikan buffer, mengisinya dengan data yang ingin Anda tulis ke perangkat, dan mengirim buffer ke pengontrol host dengan memanggil WinUsb_WritePipe.

Pembatasan berikut berlaku untuk ukuran buffer jika RAW_IO diatur:

Panjang buffer harus kelipatan dari ukuran paket titik akhir maksimum.
Panjangnya harus kurang dari atau sama dengan nilai MAXIMUM_TRANSFER_SIZE yang diambil oleh WinUsb_GetPipePolicy.

Tidak ada batasan pada ukuran buffer jika RAW_IO tidak ditetapkan sebagai jenis kebijakan pipa. Jika ukuran buffer lebih besar dari panjang transfer maksimum yang dilaporkan oleh MAXIMUM_TRANSFER_SIZE, WinUSB membagi permintaan menjadi permintaan yang lebih kecil dan mengirimkannya secara serial ke pengontrol host.

Permintaan tulis yang berisi data panjang nol diteruskan ke tumpukan USB.

Jika aplikasi melewati NULL dalam parameter Tumpang Tindih (operasi sinkron), aplikasi harus memastikan bahwa LengthTransferred bukan NULL, bahkan ketika operasi 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 WinUsb_WritePipe mengembalikan tidak berarti sampai operasi yang tumpang tindih selesai. Untuk mengambil jumlah byte aktual yang dikembalikan, panggil WinUsb_GetOverlappedResult.