USBD_QueryUsbCapability (usbdlib.h)
Rutinitas USBD_QueryUsbCapability dipanggil oleh driver klien WDM untuk menentukan apakah tumpukan driver USB yang mendasar dan perangkat keras pengontrol host mendukung kemampuan tertentu. Catatan untuk Driver Driver Framework Windows (WDF): Jika driver klien Anda adalah driver berbasis WDF, maka Anda harus memanggil metode WdfUsbTargetDeviceQueryUsbCapability alih-alih USBD_QueryUsbCapability.
Sintaks
NTSTATUS USBD_QueryUsbCapability(
[in] USBD_HANDLE USBDHandle,
[in] const GUID *CapabilityType,
[in] ULONG OutputBufferLength,
[in, out] PUCHAR OutputBuffer,
[out, optional] PULONG ResultLength
);
Parameter
[in] USBDHandle
Handel USBD yang diambil oleh driver klien dalam panggilan sebelumnya ke rutinitas USBD_CreateHandle .
[in] CapabilityType
Penunjuk ke GUID yang mewakili kemampuan yang ingin diambil oleh driver klien. Kemungkinan nilai PGUID adalah sebagai berikut:
- GUID_USB_CAPABILITY_CHAINED_MDLS
- GUID_USB_CAPABILITY_STATIC_STREAMS
- GUID_USB_CAPABILITY_SELECTIVE_SUSPEND
- GUID_USB_CAPABILITY_FUNCTION_SUSPEND
- GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE
- GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE
- GUID_USB_CAPABILITY_TIME_SYNC
[in] OutputBufferLength
Panjang, dalam byte, dari buffer yang diacu oleh OutputBuffer.
[in, out] OutputBuffer
Penunjuk ke buffer yang dialokasikan penelepon. Permintaan kemampuan tertentu mengembalikan informasi tambahan dalam buffer output. Untuk permintaan tersebut, Anda harus mengalokasikan buffer dan memberikan penunjuk ke buffer dalam parameter OutputBuffer . Saat ini, hanya permintaan kemampuan aliran statis yang memerlukan buffer output dari jenis USHORT. Buffer diisi oleh USBD_QueryUsbCapability dengan jumlah maksimum aliran yang didukung per titik akhir.
Permintaan kemampuan lainnya tidak memerlukan buffer output. Untuk permintaan tersebut, Anda harus mengatur OutputBuffer ke NULL dan OutputBufferLength ke 0.
[out, optional] ResultLength
Penunjuk ke variabel ULONG yang menerima jumlah byte aktual dalam buffer yang ditujukkan oleh OutputBuffer. Pemanggil dapat meneruskan NULL di ResultLength. Jika ResultLength bukan NULL, nilai yang diterima kurang dari atau sama dengan nilai OutputBufferLength .
Nilai kembali
Rutinitas USBD_QueryUsbCapability mengembalikan kode status NT.
Nilai yang mungkin termasuk, tetapi tidak terbatas pada, kode status yang tercantum dalam tabel berikut.
| Menampilkan kode | Deskripsi |
|---|---|
|
Permintaan berhasil dan kemampuan yang ditentukan didukung. |
|
Penelepon melewati nilai parameter yang tidak valid.
|
|
Kemampuan yang ditentukan tidak didukung oleh tumpukan driver USB yang mendasar. |
|
Kemampuan yang ditentukan tidak didukung baik oleh perangkat keras pengontrol host atau tumpukan driver USB. |
Keterangan
Windows 8 menyertakan tumpukan driver USB baru untuk mendukung perangkat USB 3.0. Tumpukan driver USB baru menyediakan beberapa kemampuan baru yang ditentukan seperti, dukungan streaming dan MDL berantai yang dapat digunakan oleh driver klien.
Driver klien dapat menentukan versi tumpukan driver USB yang mendasar dengan memanggil rutinitas IsInterfaceVersionSupported .
Driver klien dapat menggunakan kemampuan baru hanya jika tumpukan driver USB yang mendasar dan perangkat keras mendukungnya. Misalnya, untuk mengirim permintaan I/O ke aliran tertentu yang terkait dengan titik akhir massal, tumpukan driver USB yang mendasar, titik akhir, dan perangkat keras pengontrol host harus mendukung kemampuan aliran statis. Driver klien tidak boleh memanggil IsInterfaceVersionSupported dan mengasumsikan kemampuan tumpukan driver. Sebagai gantinya, driver klien harus selalu memanggil USBD_QueryUsbCapability untuk menentukan apakah tumpukan driver USB dan perangkat keras mendukung kemampuan tertentu.
Tabel berikut ini menjelaskan kemampuan khusus USB yang dapat dikueri driver klien melalui panggilan USBD_QueryUsbCapability .
| GUID kemampuan | Deskripsi |
|---|---|
| GUID_USB_CAPABILITY_CHAINED_MDLS | Jika tumpukan driver USB mendukung MDL berantai, driver klien dapat memberikan data transfer sebagai rantai MDL yang mereferensikan buffer tersegmentasi dalam memori fisik. Untuk informasi selengkapnya, lihat MDL. MDL berantai menghalangi kebutuhan untuk mengalokasikan dan menyalin memori untuk membuat buffer yang hampir berdekatan dan karenanya membuat transfer I/O lebih efisien. Untuk informasi selengkapnya, lihat Cara Mengirim MDL Berantai. |
| GUID_USB_CAPABILITY_STATIC_STREAMS |
Jika didukung, driver klien dapat mengirim permintaan I/O ke streaming di titik akhir massal.
Untuk permintaan kueri aliran statis, driver klien diperlukan untuk menyediakan buffer output (USHORT). Setelah panggilan selesai dan jika kemampuan aliran statis didukung, buffer output menerima jumlah maksimum aliran yang didukung oleh pengontrol host. Nilai buffer output tidak menunjukkan jumlah maksimum aliran yang didukung oleh titik akhir massal di perangkat. Untuk menentukan angka tersebut, driver klien harus memeriksa deskriptor pendamping titik akhir. Tumpukan driver USB di Windows 8 mendukung hingga 255 aliran. Jika aliran statis didukung, driver klien dapat mengirim permintaan I/O ke aliran pertama (juga disebut aliran default) dengan menggunakan handel pipa yang diperoleh melalui permintaan konfigurasi pemilihan. Untuk aliran lain di titik akhir, driver klien harus membuka aliran tersebut dan mendapatkan handel pipa untuk mereka untuk mengirim permintaan I/O. Untuk informasi selengkapnya tentang membuka aliran, lihat Cara Membuka dan Menutup Aliran Statis di Titik Akhir Massal USB. |
| GUID_USB_CAPABILITY_FUNCTION_SUSPEND |
Kemampuan ini menentukan apakah tumpukan driver USB yang mendasar mendukung fitur USB Function Suspend dan Remote Wake-Up. Jika didukung, tumpukan driver dapat memproses sinyal resume (untuk bangun jarak jauh) dari fungsi individual di perangkat komposit USB 3.0. Berdasarkan sinyal itu, driver fungsi individu dapat keluar dari status daya rendah fungsinya.
Kemampuan ini dimaksudkan untuk digunakan oleh driver komposit: driver yang dimuat sebagai objek perangkat fungsi (FDO) di tumpukan perangkat untuk perangkat komposit. Secara default, Driver Induk Generik USB yang disediakan Microsoft (Usbccgp.sys) dimuat sebagai FDO. Jika driver Anda mengganti Usbccgp.sys, driver harus dapat meminta bangun jarak jauh dan menyebarluaskan sinyal resume dari tumpukan driver USB. Sebelum menerapkan logika tersebut, driver harus menentukan dukungan tumpukan driver USB untuk fungsi menangguhkan kemampuan dengan memanggil USBD_QueryUsbCapability. Usbccgp.sys dalam Windows 8 mengimplementasikan penangguhan fungsi. Untuk contoh kode dan informasi selengkapnya tentang fungsi yang ditangguhkan, lihat Cara Menerapkan Fungsi Ditangguhkan dalam Driver Komposit. |
| GUID_USB_CAPABILITY_SELECTIVE_SUSPEND |
Menentukan apakah tumpukan driver USB yang mendasar mendukung penangguhan selektif.
Untuk informasi tentang penangguhan selektif, lihat Penangguhan Selektif USB. |
| GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE | Menentukan apakah bus beroperasi pada kecepatan tinggi atau lebih tinggi. |
| GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE | Menentukan apakah bus beroperasi di SuperSpeed atau lebih tinggi. |
| GUID_USB_CAPABILITY_TIME_SYNC | Menentukan apakah nomor bingkai dan fitur asosiasi QPC didukung pada pengontrol. |
Contoh
Cuplikan kode menunjukkan cara memanggil USBD_QueryUsbCapability untuk menentukan kemampuan tumpukan driver USB yang mendasar.
/*++
Routine Description:
This helper routine queries the underlying USB driver stack
for specific capabilities. This code snippet assumes that
USBD handle was retrieved by the client driver in a
previous call to the USBD_CreateHandle routine.
Parameters:
fdo: Pointer to the device object that is the current top
of the stack as reported by IoAttachDeviceToDeviceStack.
Return Value: VOID
--*/
VOID QueryUsbDriverStackCaps (PDEVICE_OBJECT fdo)
{
NTSTATUS ntStatus = STATUS_SUCCESS;
PDEVICE_EXTENSION deviceExtension;
deviceExtension = (PDEVICE_EXTENSION)fdo->DeviceExtension;
if (!deviceExtension->UsbdHandle)
{
return;
}
// Check if the underlying USB driver stack
// supports USB 3.0 devices.
if (!USBD_IsInterfaceVersionSupported(
deviceExtension->UsbdHandle,
USBD_INTERFACE_VERSION_602))
{
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Old USB stack loaded.\n" ));
}
else
{
// Call USBD_QueryUsbCapability to determine
// function suspend support.
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "New USB stack loaded.\n" ));
ntStatus = USBD_QueryUsbCapability ( deviceExtension->UsbdHandle,
(GUID*)&GUID_USB_CAPABILITY_FUNCTION_SUSPEND,
0,
NULL,
NULL);
if (NT_SUCCESS(ntStatus))
{
deviceExtension->FunctionSuspendSupported = TRUE;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Function suspend supported.\n" ));
}
else
{
deviceExtension->FunctionSuspendSupported = FALSE;
ntStatus = STATUS_SUCCESS;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Function suspend not supported.\n" ));
}
}
// Call USBD_QueryUsbCapability to determine
// chained MDL support.
ntStatus = USBD_QueryUsbCapability(
deviceExtension->UsbdHandle,
(GUID*)&GUID_USB_CAPABILITY_CHAINED_MDLS,
0,
NULL,
NULL);
if (NT_SUCCESS(ntStatus))
{
deviceExtension->ChainedMDLSupport = TRUE;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Chained MDLs supported.\n" ));
}
else
{
deviceExtension->ChainedMDLSupport = FALSE;
ntStatus = STATUS_SUCCESS;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Chained MDLs not supported.\n" ));
}
// Call USBD_QueryUsbCapability to determine
// stream support.
ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle,
(GUID*)&GUID_USB_CAPABILITY_STATIC_STREAMS,
sizeof(ULONG),
(PUCHAR) &deviceExtension->MaxSupportedStreams,
NULL);
if (!NT_SUCCESS(ntStatus))
{
deviceExtension->MaxSupportedStreams = 0;
ntStatus = STATUS_SUCCESS;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Static streams not supported.\n" ));
}
// Call USBD_QueryUsbCapability to determine
// selective suspend support.
ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle,
(GUID*)&GUID_USB_CAPABILITY_SELECTIVE_SUSPEND,
0,
NULL,
NULL);
if (!NT_SUCCESS(ntStatus))
{
ntStatus = STATUS_SUCCESS;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Selective suspend not supported.\n" ));
}
else
{
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Selective suspend supported.\n" ));
}
// Call USBD_QueryUsbCapability to determine
// device speed.
ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle,
(GUID*)&GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE,
0,
NULL,
NULL);
if (!NT_SUCCESS(ntStatus))
{
ntStatus = STATUS_SUCCESS;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at full speed or lower.\n The device can operate at high speed or higher." ));
}
else
{
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at high speed or higher.\n" ));
}
// Call USBD_QueryUsbCapability to determine
// device speed.
ntStatus = USBD_QueryUsbCapability (deviceExtension->UsbdHandle,
(GUID*)&GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE,
0,
NULL,
NULL);
if (!NT_SUCCESS(ntStatus))
{
ntStatus = STATUS_SUCCESS;
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at high speed or lower.\n The device can operate at Superspeed or higher." ));
}
else
{
KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "The device is operating at SuperSpeed or higher.\n" ));
}
return;
}
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung | Membutuhkan WDK untuk Windows 8. Menargetkan Windows Vista dan versi yang lebih baru dari sistem operasi Windows. |
| Target Platform | Desktop |
| Header | usbdlib.h (termasuk Usbdlib.h) |
| Pustaka | Usbdex.lib |
| IRQL | PASSIVE_LEVEL |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk