Fungsi WdfUsbTargetDeviceAllocAndQueryString (wdfusb.h)

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceAllocAndQueryString mengalokasikan buffer, kemudian mengambil string Unicode yang terkait dengan perangkat USB tertentu dan nilai indeks deskriptor.

Sintaks

NTSTATUS WdfUsbTargetDeviceAllocAndQueryString(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES StringMemoryAttributes,
  [out]           WDFMEMORY              *StringMemory,
  [out, optional] 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] StringMemoryAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan penelepon yang berisi atribut yang disediakan pemanggil untuk objek memori baru. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] StringMemory

Penunjuk ke lokasi yang menerima handel ke objek memori yang berisi string Unicode. String dihentikan NULL hanya jika perangkat menyediakan string yang dihentikan NULL.

[out, optional] NumCharacters

Penunjuk ke lokasi yang menerima jumlah karakter yang terkandung dalam deskriptor string. Jika string Unicode dihentikan NULL, angka ini menyertakan karakter NULL. Parameter ini bersifat opsional dan dapat berupa NULL.

[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

WdfUsbTargetDeviceAllocAndQueryString 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

Metode WdfUsbTargetDeviceAllocAndQueryString , yang hanya perlu dipanggil driver Anda sekali untuk mendapatkan deskriptor string, adalah alternatif untuk metode WdfUsbTargetDeviceQueryString , yang harus dipanggil dua kali untuk mendapatkan string.

Metode ini menemukan deskriptor string USB yang ditentukan, menyalin string Unicode dari deskriptor ke dalam objek memori, dan mengembalikan handel ke objek memori.

Setelah memanggil WdfUsbTargetDeviceAllocAndQueryString, driver Anda dapat meneruskan handel StringMemory ke WdfMemoryGetBuffer untuk mengakses konten objek memori.

Untuk informasi selengkapnya tentang deskriptor string USB, lihat spesifikasi USB.

Untuk informasi selengkapnya tentang metode WdfUsbTargetDeviceAllocAndQueryString dan target I/O USB, lihat Target I/O USB.

Contoh

Contoh kode berikut memanggil WdfUsbTargetDeviceAllocAndQueryString 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;
WDFMEMORY  memoryHandle;
USHORT  numCharacters;

myDeviceContext = GetDeviceContext(device);

status = WdfUsbTargetDeviceAllocAndQueryString(
                                        myDeviceContext->UsbTargetDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &memoryHandle,
                                        &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_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryString