Fungsi WdfUsbTargetDeviceRetrieveConfigDescriptor (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceRetrieveConfigDescriptor mengambil deskriptor konfigurasi USB untuk perangkat USB yang terkait dengan objek perangkat USB kerangka kerja tertentu.

Sintaks

NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
  [in]      WDFUSBDEVICE UsbDevice,
  [out]     PVOID        ConfigDescriptor,
  [in, out] PUSHORT      ConfigDescriptorLength
);

Parameter

[in] UsbDevice

Handel ke objek perangkat USB yang diperoleh dari panggilan sebelumnya ke WdfUsbTargetDeviceCreateWithParameters.

[out] ConfigDescriptor

Penunjuk ke buffer yang dialokasikan penelepon yang menerima struktur USB_CONFIGURATION_DESCRIPTOR , diikuti oleh satu atau beberapa struktur USB_INTERFACE_DESCRIPTOR dan USB_ENDPOINT_DESCRIPTOR . Parameter ini bersifat opsional dan dapat berupa NULL, dalam hal ini WdfUsbTargetDeviceRetrieveConfigDescriptor mengembalikan panjang buffer yang diperlukan. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

[in, out] ConfigDescriptorLength

Penunjuk ke lokasi yang memasok panjang buffer yang dirujuk ConfigDescriptor . Jika pointer yang disediakan untuk ConfigDescriptor adalah NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor mengembalikan panjang buffer yang diperlukan di lokasi yang ditunjukkan oleh ConfigDescriptorLength.

Nilai kembali

WdfUsbTargetDeviceRetrieveConfigDescriptor mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini dapat mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
STATUS_INVALID_DEVICE_STATE	Deskriptor konfigurasi tidak tersedia untuk target yang ditentukan.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi.
STATUS_BUFFER_TOO_SMALL	Ukuran buffer yang ditentukan terlalu kecil untuk data, atau pemanggil menyediakan NULL untuk parameter ConfigDescriptor .

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Metode WdfUsbTargetDeviceRetrieveConfigDescriptor mengambil semua informasi konfigurasi perangkat USB yang ditentukan (yaitu, deskriptor konfigurasi ditambah antarmuka atau deskriptor titik akhir apa pun yang mungkin ada). Untuk mempelajari tentang format informasi ini, lihat spesifikasi USB.

Anda dapat menggunakan WdfUsbTargetDeviceSelectConfig untuk memilih hanya konfigurasi USB pertama yang tercantum dalam daftar deskriptor, tetapi Anda dapat memilih beberapa antarmuka dalam konfigurasi tunggal ini.

Driver harus memanggil WdfUsbTargetDeviceRetrieveConfigDescriptor dua kali, sebagai berikut:

Atur penunjuk ConfigDescriptor ke NULL, sehingga WdfUsbTargetDeviceRetrieveConfigDescriptor akan mengembalikan ukuran buffer yang diperlukan di alamat yang ditunjuk oleh ConfigDescriptorLength .
Alokasikan ruang buffer untuk menyimpan informasi konfigurasi. Misalnya, driver mungkin memanggil ExAllocatePoolWithTag untuk mengalokasikan buffer, atau mungkin memanggil WdfMemoryCreate untuk membuat objek memori kerangka kerja.
Panggil WdfUsbTargetDeviceRetrieveConfigDescriptor lagi, berikan penunjuk ke buffer baru dan ukuran buffer.

Setelah panggilan kedua ke WdfUsbTargetDeviceRetrieveConfigDescriptor kembali, buffer yang ditunjukkan oleh ConfigDescriptor berisi struktur USB_CONFIGURATION_DESCRIPTOR , diikuti oleh satu atau beberapa struktur USB_INTERFACE_DESCRIPTOR dan USB_ENDPOINT_DESCRIPTOR . Struktur terakhir ini diatur dalam urutan yang dijelaskan dalam spesifikasi USB.

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

Contoh

Contoh kode berikut memanggil WdfUsbTargetDeviceRetrieveConfigDescriptor untuk mendapatkan ukuran buffer yang diperlukan, memanggil WdfMemoryCreate untuk membuat objek memori dan buffer, lalu memanggil WdfUsbTargetDeviceRetrieveConfigDescriptor lagi untuk mendapatkan informasi konfigurasi perangkat.

USHORT  size;
NTSTATUS  ntStatus;
PMY_DEVICE_CONTEXT  myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR  configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES  objectAttribs;
WDFMEMORY  memoryHandle;

myDeviceContext = GetDeviceContext(Device);

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            NULL,
                                            &size
                                            );

if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
    return ntStatus;
}

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;

ntStatus = WdfMemoryCreate(
                           &objectAttribs,
                           NonPagedPool,
                           POOL_TAG,
                           size,
                           &memoryHandle,
                           (PVOID)&configurationDescriptor
                           );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
                                            myDeviceContext->WdfUsbTargetDevice,
                                            configurationDescriptor,
                                            &size
                                            );
if (!NT_SUCCESS(ntStatus)) {
    return ntStatus;
}

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)