struktur _URB_HEADER (usb.h)

Artikel
08/07/2023

Struktur _URB_HEADER digunakan oleh driver klien USB untuk memberikan informasi dasar tentang permintaan yang dikirim ke driver pengontrol host.

Sintaks

struct _URB_HEADER {
  USHORT      Length;
  USHORT      Function;
  USBD_STATUS Status;
  PVOID       UsbdDeviceHandle;
  ULONG       UsbdFlags;
};

Anggota

Length

Menentukan panjang, dalam byte, dari URB. Untuk permintaan URB yang menggunakan struktur data selain _URB_HEADER, anggota ini harus diatur ke panjang seluruh struktur permintaan URB, bukan ukuran _URB_HEADER.

Function

Menentukan kode numerik yang menunjukkan operasi yang diminta untuk URB ini. Salah satu nilai berikut harus diatur:

URB_FUNCTION_SELECT_CONFIGURATION

Menunjukkan kepada driver pengontrol host bahwa konfigurasi akan dipilih. Jika diatur, URB digunakan dengan URB_SELECT_CONFIGURATION sebagai struktur data.

URB_FUNCTION_SELECT_INTERFACE

Menunjukkan kepada driver pengontrol host bahwa pengaturan antarmuka alternatif sedang dipilih untuk antarmuka. Jika diatur, URB digunakan dengan _URB_SELECT_INTERFACE sebagai struktur data.

URB_FUNCTION_ABORT_PIPE

Menunjukkan bahwa semua permintaan yang beredar untuk pipa harus dibatalkan. Jika diatur, URB digunakan dengan _URB_PIPE_REQUEST sebagai struktur data. Permintaan tujuan umum ini memungkinkan klien untuk membatalkan transfer yang tertunda untuk pipa yang ditentukan. Status pipa dan status titik akhir tidak terpengaruh. Permintaan batalkan mungkin selesai sebelum semua permintaan yang terutang telah selesai. Jangan berasumsi bahwa penyelesaian permintaan batalkan menyiratkan bahwa semua permintaan terutang lainnya telah selesai.

URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL

Fungsi URB ini tidak digunakan lagi di sistem operasi Windows 2000 dan yang lebih baru dan tidak didukung oleh Microsoft. Jangan gunakan. Jika Anda menentukan fungsi ini dengan permintaan URB, permintaan akan gagal dan sistem akan melaporkan kesalahan.

URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

URB_FUNCTION_GET_FRAME_LENGTH

Fungsi URB ini tidak digunakan lagi di sistem operasi Windows 2000 dan yang lebih baru dan tidak didukung oleh Microsoft. Jangan gunakan. Jika Anda menggunakan fungsi ini dengan permintaan URB, permintaan akan gagal dan sistem akan melaporkan kesalahan.

URB_FUNCTION_SET_FRAME_LENGTH

Fungsi URB ini tidak digunakan lagi di sistem operasi Windows 2000 dan yang lebih baru dan tidak didukung oleh Microsoft. Jangan gunakan. Jika Anda menggunakannya dengan permintaan URB, permintaan akan gagal dan sistem akan melaporkan kesalahan.

URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Meminta nomor bingkai saat ini dari driver pengontrol host. Jika diatur, URB digunakan dengan _URB_GET_CURRENT_FRAME_NUMBER sebagai struktur data.

URB_FUNCTION_CONTROL_TRANSFER

Mentransfer data ke atau dari pipa kontrol. Jika diatur, URB digunakan dengan _URB_CONTROL_TRANSFER sebagai struktur data.

URB_FUNCTION_CONTROL_TRANSFER_EX

Mentransfer data ke atau dari pipa kontrol tanpa batas waktu yang ditentukan oleh nilai batas waktu. Jika diatur, URB digunakan dengan URB_CONTROL_TRANSFER_EX sebagai struktur data.

Tersedia di Windows Vista dan sistem operasi yang lebih baru.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Mentransfer data dari pipa massal atau mengganggu pipa atau ke pipa massal. Jika diatur, URB digunakan dengan _URB_BULK_OR_INTERRUPT_TRANSFER sebagai struktur data.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER_USING_CHAINED_MDL

Mentransfer data ke dan dari pipa massal atau pipa interupsi, dengan menggunakan MDL berantai. Jika diatur, URB digunakan dengan _URB_BULK_OR_INTERRUPT_TRANSFER sebagai struktur data. Driver klien harus mengatur anggota TransferBufferMDL ke struktur MDL pertama dalam rantai yang berisi buffer transfer. Tumpukan driver USB mengabaikan anggota TransferBuffer saat memproses URB ini.

Tersedia dalam Windows 8. Untuk informasi tentang menggunakan MDL berantai, lihat Cara Mengirim MDL Berantai">Cara Mengirim MDL Berantai.

URB_FUNCTION_ISOCH_TRANSFER

Mentransfer data ke atau dari pipa isochronous. Jika diatur, URB digunakan dengan _URB_ISOCH_TRANSFER sebagai struktur data.

URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_MDL

Mentransfer data ke atau dari pipa isochronous dengan menggunakan MDL berantai. Jika diatur, URB digunakan dengan _URB_ISOCH_TRANSFER sebagai struktur data. Driver klien harus mengatur anggota TransferBufferMDL ke MDL pertama dalam rantai yang berisi buffer transfer. Tumpukan driver USB mengabaikan anggota TransferBuffer saat memproses URB ini.

Tersedia dalam Windows 8. Untuk informasi tentang menggunakan MDL berantai, lihat Cara Mengirim MDL Berantai">Cara Mengirim MDL Berantai.

URB_FUNCTION_RESET_PIPE

Lihat URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL

Mengatur ulang pipa yang ditunjukkan. Jika diatur, URB ini digunakan dengan _URB_PIPE_REQUEST.

Catatan

URB ini menggantikan URB_FUNCTION_RESET_PIPE.

Pengemudi bus menyelesaikan tiga tugas sebagai respons terhadap URB ini:

Pertama, untuk semua pipa kecuali pipa isochronous, URB ini mengirimkan permintaan CLEAR_FEATURE untuk menghapus fitur ENDPOINT_HALT perangkat.

Kedua, driver bus USB mengatur ulang pengalih data di sisi host, seperti yang diperlukan oleh spesifikasi USB. Perangkat USB harus mengatur ulang pengalih data di sisi perangkat ketika driver bus menghapus fitur ENDPOINT_HALT. Karena beberapa perangkat yang tidak sesuai tidak mendukung fitur ini, Microsoft menyediakan dua URL tambahan: URB_FUNCTION_SYNC_CLEAR_STALL dan URB_FUNCTION_SYNC_RESET_PIPE. Ini memungkinkan driver klien untuk menghapus fitur ENDPOINT_HALT pada perangkat, atau mengatur ulang pipa di sisi host, masing-masing, tanpa memengaruhi pengalih data di sisi host. Jika perangkat tidak mengatur ulang pengalih data kapan seharusnya, maka driver klien dapat mengkompensasi cacat ini dengan tidak mengatur ulang pengalih data sisi host. Jika pengalih data diatur ulang di sisi host tetapi tidak di sisi perangkat, paket akan keluar dari urutan, dan perangkat mungkin menghilangkan paket.

Ketiga, setelah pengemudi bus berhasil mengatur ulang pipa, ia melanjutkan transfer dengan URB antrean berikutnya.

Setelah reset pipa, transfer dilanjutkan dengan URB antrean berikutnya.

Tidak perlu menghapus kondisi berhenti pada pipa kontrol default. Pipa kontrol default harus selalu menerima paket penyiapan, sehingga jika berhenti, tumpukan USB akan menghapus kondisi berhenti secara otomatis. Driver klien tidak perlu mengambil tindakan khusus untuk menghapus kondisi berhenti pada pipa default.

Semua transfer harus dibatalkan atau dibatalkan sebelum mencoba mengatur ulang pipa.

URB ini harus dikirim pada PASSIVE_LEVEL.

URB_FUNCTION_SYNC_RESET_PIPE

Menghapus kondisi berhenti di sisi host pipa. Jika diatur, URB ini digunakan dengan _URB_PIPE_REQUEST sebagai struktur data.

URB ini memungkinkan klien untuk menghapus status pipa yang dihentikan tanpa mengatur ulang pengalih data dan tanpa menghapus kondisi stall titik akhir (fitur ENDPOINT_HALT). Untuk menghapus kondisi berhenti pada pipa, ajarkan ulang pengalih data sisi host dan hapus stall pada perangkat dengan satu operasi, gunakan URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

Kode status berikut penting dan memiliki arti yang ditunjukkan:

USBD_STATUS_INVALID_PIPE_HANDLE

PipeHandle tidak valid

USBD_STATUS_ERROR_BUSY

Titik akhir memiliki transfer aktif tertunda.

Tidak perlu menghapus kondisi berhenti pada pipa kontrol default. Pipa kontrol default harus selalu menerima paket penyiapan, dan jadi jika berhenti, tumpukan USB akan menghapus kondisi berhenti secara otomatis. Driver klien tidak perlu mengambil tindakan khusus untuk menghapus kondisi berhenti pada pipa default.

Semua transfer harus dibatalkan atau dibatalkan sebelum mencoba mengatur ulang pipa.

URB ini harus dikirim pada PASSIVE_LEVEL.

Tersedia di Windows XP dan sistem operasi yang lebih baru.

URB_FUNCTION_SYNC_CLEAR_STALL

Membersihkan kondisi kios pada titik akhir. Untuk semua pipa kecuali pipa isochronous, URB ini mengirimkan permintaan CLEAR_FEATURE untuk menghapus fitur ENDPOINT_HALT perangkat. Namun, tidak seperti fungsi RB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL, fungsi URB ini tidak mengatur ulang pengalih data di sisi host pipa. Spesifikasi USB mengharuskan perangkat untuk mengatur ulang pengalih data sisi perangkat setelah klien menghapus fitur ENDPOINT_HALT perangkat, tetapi beberapa perangkat yang tidak patuh tidak mengatur ulang pengalih datanya dengan benar. Driver klien yang mengelola perangkat tersebut dapat mengimbangi cacat ini dengan membersihkan kondisi kios secara langsung dengan URB_FUNCTION_SYNC_CLEAR_STALL alih-alih mengatur ulang pipa dengan URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL. URB_FUNCTION_SYNC_CLEAR_STALL menghapus kondisi kios pada perangkat tanpa mengatur ulang pengalih data sisi host. Ini mencegah perangkat yang tidak patuh menginterpretasikan paket berikutnya sebagai transmisi ulang dan menghilangkan paket.

Jika diatur, URB digunakan dengan _URB_PIPE_REQUEST sebagai struktur data.

Fungsi URB ini harus dikirim pada PASSIVE_LEVEL

Tersedia di Windows XP dan sistem operasi yang lebih baru.

URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Mengambil deskriptor perangkat dari perangkat USB tertentu. Jika diatur, URB digunakan dengan _URB_CONTROL_DESCRIPTOR_REQUEST sebagai struktur data.

URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT

Mengambil deskriptor dari titik akhir pada antarmuka untuk perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_DESCRIPTOR_REQUEST sebagai struktur data.

URB_FUNCTION_SET_DESCRIPTOR_TO_DEVICE

Mengatur pendeskripsi perangkat pada perangkat. Jika diatur, URB digunakan dengan _URB_CONTROL_DESCRIPTOR_REQUEST sebagai struktur data.

URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT

Mengatur deskriptor titik akhir pada titik akhir untuk antarmuka. Jika diatur, URB digunakan dengan _URB_CONTROL_DESCRIPTOR_REQUEST sebagai struktur data.

URB_FUNCTION_SET_FEATURE_TO_DEVICE

Mengatur fitur yang ditentukan USB pada perangkat. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_SET_FEATURE_TO_INTERFACE

Mengatur fitur yang ditentukan USB pada antarmuka untuk perangkat. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_SET_FEATURE_TO_ENDPOINT

Mengatur fitur yang ditentukan USB pada titik akhir untuk antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_SET_FEATURE_TO_OTHER

Mengatur fitur yang ditentukan USB pada target yang ditentukan perangkat pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE

Menghapus fitur yang ditentukan USB pada perangkat. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE

Menghapus fitur yang ditentukan USB pada antarmuka untuk perangkat. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT

Menghapus fitur yang ditentukan USB pada titik akhir, untuk antarmuka, pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Menghapus fitur yang ditentukan USB pada target yang ditentukan perangkat pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_FEATURE_REQUEST sebagai struktur data.

URB_FUNCTION_GET_STATUS_FROM_DEVICE

Mengambil status dari perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_GET_STATUS_REQUEST sebagai struktur data.

URB_FUNCTION_GET_STATUS_FROM_INTERFACE

Mengambil status dari antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_GET_STATUS_REQUEST sebagai struktur data.

URB_FUNCTION_GET_STATUS_FROM_ENDPOINT

Mengambil status dari titik akhir untuk antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_GET_STATUS_REQUEST sebagai struktur data.

URB_FUNCTION_GET_STATUS_FROM_OTHER

Mengambil status dari target yang ditentukan perangkat pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_GET_STATUS_REQUEST sebagai struktur data.

URB_FUNCTION_VENDOR_DEVICE

Mengirim perintah khusus vendor ke perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_VENDOR_INTERFACE

Mengirim perintah khusus vendor untuk antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_VENDOR_ENDPOINT

Mengirim perintah khusus vendor untuk titik akhir pada antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_VENDOR_OTHER

Mengirim perintah khusus vendor ke target yang ditentukan perangkat pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_CLASS_DEVICE

Mengirim perintah khusus kelas yang ditentukan USB ke perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_CLASS_INTERFACE

Mengirim perintah khusus kelas yang ditentukan USB ke antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_CLASS_ENDPOINT

Mengirim perintah khusus kelas yang ditentukan USB ke titik akhir, pada antarmuka, pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_CLASS_OTHER

Mengirim perintah khusus kelas yang ditentukan USB ke target yang ditentukan perangkat pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_VENDOR_OR_CLASS_REQUEST sebagai struktur data.

URB_FUNCTION_GET_CONFIGURATION

Mengambil konfigurasi saat ini pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_GET_CONFIGURATION_REQUEST sebagai struktur data.

URB_FUNCTION_GET_INTERFACE

Mengambil pengaturan saat ini untuk antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_GET_INTERFACE_REQUEST sebagai struktur data.

Tersedia di Windows 2000, dan Windows Vista dan sistem operasi yang lebih baru. Tidak tersedia di Windows XP.

URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE

Mengambil deskriptor dari antarmuka untuk perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_DESCRIPTOR_REQUEST sebagai struktur data.

URB_FUNCTION_SET_DESCRIPTOR_TO_INTERFACE

Mengatur deskriptor untuk antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_CONTROL_DESCRIPTOR_REQUEST sebagai struktur data.

URB_FUNCTION_GET_MS_FEATURE_DESCRIPTOR

Mengambil pendeskripsi fitur Microsoft OS dari perangkat USB atau antarmuka pada perangkat USB. Jika diatur, URB digunakan dengan _URB_OS_FEATURE_DESCRIPTOR_REQUEST sebagai struktur data.

Tersedia di Windows XP dan sistem operasi yang lebih baru.

URB_FUNCTION_OPEN_STATIC_STREAMS

Membuka aliran di titik akhir massal yang ditentukan. Jika diatur, URB digunakan dengan _URB_OPEN_STATIC_STREAMS sebagai struktur data.

Tersedia di Windows 8. Untuk informasi tentang memformat URB untuk permintaan open-stream, lihat Cara Membuka dan Menutup Aliran Statis di Titik Akhir Massal USB.

URB_FUNCTION_CLOSE_STATIC_STREAMS

Menutup semua aliran yang dibuka di titik akhir massal yang ditentukan. Jika diatur, URB digunakan dengan _URB_PIPE_REQUEST sebagai struktur data.

Tersedia di Windows 8. Untuk informasi tentang memformat URB untuk permintaan open-stream, lihat Cara Membuka dan Menutup Aliran Statis di Titik Akhir Massal USB.

Status

Berisi kode USBD_STATUS_XXX saat dikembalikan dari driver pengontrol host.

UsbdDeviceHandle

Dicadangkan. Jangan gunakan.

UsbdFlags

Dicadangkan. Jangan gunakan.

Keterangan

Struktur _URB_HEADER adalah anggota dari semua permintaan USB yang merupakan bagian dari struktur URB. Struktur _URB_HEADER digunakan untuk memberikan informasi umum tentang setiap permintaan ke driver pengontrol host.

Anggota yang dicadangkan dari struktur ini harus diperlakukan sebagai buram dan disediakan untuk penggunaan sistem.