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
STATUS_INVALID_PARAMETER
Parameter yang tidak valid terdeteksi.
STATUS_INSUFFICIENT_RESOURCES
Buffer memori tidak dapat dialokasikan.
STATUS_DEVICE_DATA_ERROR
Perangkat USB mengembalikan deskriptor yang tidak valid.
STATUS_BUFFER_OVERFLOW
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).
WdfUsbTargetDeviceQueryString menemukan deskriptor string USB yang ditentukan dan menyalin string Unicode dari deskriptor ke dalam buffer yang disediakan.

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

USB_CONFIGURATION_DESCRIPTOR

USB_DEVICE_DESCRIPTOR

USB_INTERFACE_DESCRIPTOR

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfUsbTargetDeviceAllocAndQueryString

WdfUsbTargetDeviceCreateWithParameters