Metode IWDFUsbTargetDevice::RetrieveDescriptor (wudfusb.h)

Artikel
08/08/2023

[Peringatan: UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2. Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.]

Metode RetrieveDescriptor mengambil deskriptor USB, yang dapat menjelaskan perangkat, konfigurasi, atau string.

Sintaks

HRESULT RetrieveDescriptor(
  [in]      UCHAR  DescriptorType,
  [in]      UCHAR  Index,
  [in]      USHORT LanguageID,
  [in, out] ULONG  *BufferLength,
  [out]     PVOID  Buffer
);

Parameter

[in] DescriptorType

Nilai yang menentukan jenis deskriptor yang akan dikembalikan. Parameter ini sesuai dengan bidang bDescriptorType dari deskriptor perangkat standar, yang nilainya dijelaskan dalam spesifikasi Universal Serial Bus . (Sumber daya ini mungkin tidak tersedia dalam beberapa bahasa

dan negara.) Beberapa nilai ini tercantum dalam deskripsi anggota DescriptorType dari struktur _URB_CONTROL_DESCRIPTOR_REQUEST .

[in] Index

Indeks deskriptor, sesuai dengan spesifikasi Universal Serial Bus . (Sumber daya ini mungkin tidak tersedia dalam beberapa bahasa

dan negara.)

[in] LanguageID

Pengidentifikasi bahasa, jika driver UMDF meminta deskriptor string; jika tidak, parameter ini adalah nol.

[in, out] BufferLength

Penunjuk ke variabel yang, pada input, berisi ukuran, dalam byte, dari buffer yang dituju buffer . Jika operasi berhasil, variabel menerima jumlah byte yang disalin kerangka kerja ke dalam buffer.

[out] Buffer

Penunjuk ke buffer yang disediakan penelepon yang menerima deskriptor USB. Jenis buffer harus cocok dengan nilai yang ditentukan dalam DescriptorType.

Nilai kembali

RetrieveDescriptor mengembalikan salah satu nilai berikut:

Menampilkan kode	Deskripsi
S_OK	RetrieveDescriptor berhasil mengambil deskriptor USB.
E_OUTOFMEMORY	RetrieveDescriptor mengalami kegagalan alokasi.
Kode kesalahan yang didefinisikan dalam Winerror.h	Nilai ini sesuai dengan kode kesalahan yang dikembalikan API WinUsb.

Keterangan

Untuk informasi tentang jenis deskriptor yang valid yang dapat diteruskan driver UMDF untuk parameter DescriptorType , lihat fungsi WinUsb_GetDescriptor .

Metode RetrieveDescriptor menghasilkan permintaan UMDF dan secara sinkron mengirim permintaan ke target I/O.

Contoh

Contoh kode berikut mengambil pendeskripsi konfigurasi USB.

HRESULT
CUmdfHidDevice::RetrieveConfigDescriptor(
    __out_bcount(ConfigDescriptorCb) PUSB_CONFIGURATION_DESCRIPTOR *ConfigDescriptor,
    __out ULONG *ConfigDescriptorCb
    )
{
    ULONG descriptorCb = sizeof(USB_CONFIGURATION_DESCRIPTOR);
    USB_CONFIGURATION_DESCRIPTOR descriptorHeader;
    PBYTE descriptorBuffer;
    HRESULT hr;

    //
    // Get the configuration descriptor at index 0
    //

    hr = m_UsbTargetDevice->RetrieveDescriptor(
                            USB_CONFIGURATION_DESCRIPTOR_TYPE,
                            0,
                            0,
                            &descriptorCb,
                            &descriptorHeader
                            );
    //
    // Store the buffer in the output parameter, or delete it.
    //
    if (SUCCEEDED(hr)) {
        *ConfigDescriptor = (PUSB_CONFIGURATION_DESCRIPTOR) (descriptorHeader);
        *ConfigDescriptorCb = descriptorCb;
    }
    else {
        delete[] descriptorHeader;
    }
    return hr;
}

Persyaratan

Persyaratan	Nilai
Akhir dukungan	Tidak tersedia di UMDF 2.0 dan yang lebih baru.
Target Platform	Desktop
Versi UMDF minimum	1,5
Header	wudfusb.h (termasuk Wudfusb.h)
DLL	WUDFx.dll

Lihat juga

IWDFUsbTargetDevice

WinUsb_GetDescriptor

Share via