Fungsi WdfUsbTargetDeviceQueryString (wdfusb.h)
[Berlaku untuk KMDF dan UMDF]
Metode WdfUsbTargetDeviceQueryString mengambil string Unicode yang terkait dengan perangkat USB dan nilai indeks deskriptor tertentu.
Sintaks
NTSTATUS WdfUsbTargetDeviceQueryString(
[in] WDFUSBDEVICE UsbDevice,
[in, optional] WDFREQUEST Request,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PUSHORT String,
[in, out] PUSHORT NumCharacters,
[in] UCHAR StringIndex,
[in, optional] USHORT LangID
);
Parameter
[in] UsbDevice
Handel ke objek perangkat USB yang diperoleh dari panggilan sebelumnya ke WdfUsbTargetDeviceCreateWithParameters.
[in, optional] Request
Handel ke objek permintaan kerangka kerja. Parameter ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[in, optional] RequestOptions
Penunjuk ke struktur WDF_REQUEST_SEND_OPTIONS yang dialokasikan pemanggil yang menentukan opsi untuk permintaan. Penunjuk ini bersifat opsional dan dapat berupa NULL. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.
[out, optional] String
Penunjuk ke buffer yang dialokasikan pemanggil yang menerima string Unicode yang diminta. String dihentikan NULL hanya jika perangkat menyediakan string yang dihentikan NULL. Jika pointer ini NULL, WdfUsbTargetDeviceQueryString mengembalikan ukuran buffer yang diperlukan (yaitu, jumlah karakter Unicode yang diperlukan) di lokasi yang ditunjuk oleh NumCharacters .
[in, out] NumCharacters
Penunjuk ke variabel yang dialokasikan penelepon. Pemanggil menyediakan jumlah karakter Unicode yang dapat ditahan oleh buffer. Ketika WdfUsbTargetDeviceQueryString kembali, variabel menerima jumlah karakter (termasuk terminator NULL, jika disediakan) yang ada dalam string Unicode yang diterima buffer String .
[in] StringIndex
Nilai indeks yang mengidentifikasi string Unicode. Nilai indeks ini diperoleh dari struktur USB_DEVICE_DESCRIPTOR, USB_CONFIGURATION_DESCRIPTOR, atau USB_INTERFACE_DESCRIPTOR .
[in, optional] LangID
Pengidentifikasi bahasa. String Unicode akan diambil untuk bahasa yang ditentukan pengidentifikasi ini. Untuk informasi tentang mendapatkan pengidentifikasi bahasa yang didukung perangkat, lihat spesifikasi USB.
Nilai kembali
WdfUsbTargetDeviceQueryString mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:
Menampilkan kode | Deskripsi |
---|---|
|
Parameter yang tidak valid terdeteksi. |
|
Buffer memori tidak dapat dialokasikan. |
|
Perangkat USB mengembalikan deskriptor yang tidak valid. |
|
Buffer yang disediakan terlalu kecil. |
Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.
Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.
Keterangan
Driver harus memanggil WdfUsbTargetDeviceQueryString dua kali, dengan menggunakan langkah-langkah berikut:
- Atur penunjuk String ke NULL, sehingga WdfUsbTargetDeviceQueryString akan mengembalikan ukuran buffer yang diperlukan dalam alamat yang ditunjuk parameter NumCharacters .
- Alokasikan ruang buffer untuk menahan jumlah karakter Unicode yang ada dalam string yang diminta. Misalnya, driver mungkin memanggil ExAllocatePoolWithTag untuk mengalokasikan buffer, atau mungkin memanggil WdfMemoryCreate untuk membuat objek memori kerangka kerja.
- Panggil WdfUsbTargetDeviceQueryString lagi, atur nilai String ke penunjuk ke buffer baru dan atur NumCharacters ke panjang buffer (yaitu, jumlah karakter Unicode, bukan panjang byte).
Jika driver Anda menentukan nilai non-NULL untuk parameter Permintaan , kerangka kerja menggunakan objek permintaan yang ditentukan, dan utas driver lain dapat memanggil WdfRequestCancelSentRequest, jika perlu, untuk mencoba membatalkan permintaan kueri string. Jika driver menentukan nilai NULL untuk Permintaan, kerangka kerja menggunakan objek permintaan internal yang tidak dapat dibatalkan oleh driver.
Driver Anda dapat menentukan parameter RequestOptionsnon-NULL, baik driver menyediakan parameter permintaannon-NULL atau NULL. Anda dapat, misalnya, menggunakan parameter RequestOptions untuk menentukan nilai waktu habis.
Untuk informasi selengkapnya tentang deskriptor string USB, lihat spesifikasi USB.
Untuk informasi selengkapnya tentang metode WdfUsbTargetDeviceQueryString dan target I/O USB, lihat Target I/O USB.
Contoh
Contoh kode berikut memanggil WdfUsbTargetDeviceQueryString untuk mendapatkan ukuran buffer yang diperlukan, memanggil WdfMemoryCreate untuk membuat objek memori dan buffer, lalu memanggil WdfUsbTargetDeviceQueryString lagi untuk mendapatkan string nama produsen, dalam bahasa Inggris AS (0x0409), dari deskriptor perangkat USB. (Driver sebelumnya menyimpan deskriptor dalam ruang konteks yang ditentukan driver.)
PMY_DEVICE_CONTEXT myDeviceContext;
USHORT numCharacters;
PUSHORT stringBuf;
WDFMEMORY memoryHandle;
myDeviceContext = GetDeviceContext(device);
status = WdfUsbTargetDeviceQueryString(
myDeviceContext->UsbTargetDevice,
NULL,
NULL,
NULL,
&numCharacters,
myDeviceContext->UsbDeviceDescr.iManufacturer,
0x0409
);
ntStatus = WdfMemoryCreate(
WDF_NO_OBJECT_ATTRIBUTES,
NonPagedPool,
POOL_TAG,
numCharacters * sizeof(WCHAR),
&memoryHandle,
(PVOID)&stringBuf
);
if (!NT_SUCCESS(ntStatus)) {
return ntStatus;
}
status = WdfUsbTargetDeviceQueryString(
myDeviceContext->UsbTargetDevice,
NULL,
NULL,
stringBuf,
&numCharacters,
myDeviceContext->UsbDeviceDescr.iManufacturer,
0x0409
);
Persyaratan
Persyaratan | Nilai |
---|---|
Target Platform | Universal |
Versi KMDF minimum | 1,0 |
Versi UMDF minimum | 2.0 |
Header | wdfusb.h (termasuk Wdfusb.h) |
Pustaka | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
Aturan kepatuhan DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf) |
Lihat juga
Saran dan Komentar
https://aka.ms/ContentUserFeedback.
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:Kirim dan lihat umpan balik untuk