Fungsi WdfUsbTargetDeviceSelectConfig (wdfusb.h)

Artikel
02/29/2024

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceSelectConfig memilih konfigurasi USB untuk perangkat, atau mendekonfigurasi perangkat.

Sintaks

NTSTATUS WdfUsbTargetDeviceSelectConfig(
  [in]           WDFUSBDEVICE                         UsbDevice,
  [in, optional] PWDF_OBJECT_ATTRIBUTES               PipeAttributes,
  [in, out]      PWDF_USB_DEVICE_SELECT_CONFIG_PARAMS Params
);

Parameter

[in] UsbDevice

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

[in, optional] PipeAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang dialokasikan penelepon yang berisi atribut untuk objek pipa USB kerangka kerja baru yang dibuat kerangka kerja untuk antarmuka perangkat. Untuk driver KMDF, parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES. Driver UMDF harus mengatur parameter ini ke NULL.

[in, out] Params

Penunjuk ke struktur WDF_USB_DEVICE_SELECT_CONFIG_PARAMS yang dialokasikan pemanggil dan kerangka kerja untuk menentukan parameter konfigurasi.

Nilai kembali

WdfUsbTargetDeviceSelectConfig mengembalikan nilai status penyelesaian target I/O 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_INFO_LENGTH_MISMATCH	Anggota Ukuran struktur WDF_USB_DEVICE_SELECT_CONFIG_PARAMS yang dipandang Params salah.
STATUS_INSUFFICIENT_RESOURCES	Buffer memori tidak dapat dialokasikan.
STATUS_NOT_SUPPORTED	Kerangka kerja mengembalikan nilai ini jika driver UMDF memanggil WdfUsbTargetDeviceSelectConfig denganJenisParams-> yang diatur ke salah satu hal berikut: WdfUsbTargetDeviceSelectConfigTypeDeconfig WdfUsbTargetDeviceSelectConfigTypeInterfacesDescriptor WdfUsbTargetDeviceSelectConfigTypeUrb Untuk informasi selengkapnya, lihat WdfUsbTargetDeviceSelectConfigType.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Driver Anda dapat memilih konfigurasi perangkat dengan menggunakan struktur WDF_USB_DEVICE_SELECT_CONFIG_PARAMS untuk menentukan deskriptor USB, URB, atau handel ke objek antarmuka USB kerangka kerja.

Kerangka kerja membuat objek pipa USB kerangka kerja untuk setiap pipa yang terkait dengan setiap antarmuka dalam konfigurasi, setelah menghapus objek pipa apa pun yang mungkin telah dibuat kerangka kerja sebelumnya untuk konfigurasi. Kerangka kerja menggunakan pengaturan alternatif nol untuk setiap antarmuka, kecuali driver menentukan pengaturan alternatif yang berbeda.

Untuk mendapatkan informasi tentang objek pipa antarmuka, driver dapat memanggil WdfUsbInterfaceGetNumConfiguredPipes dan WdfUsbInterfaceGetConfiguredPipe.

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

Perhatian

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.

Contoh

Contoh kode berikut memilih konfigurasi dengan satu antarmuka yang ditentukan.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
NTSTATUS  status;

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_SINGLE_INTERFACE(&configParams);

status = WdfUsbTargetDeviceSelectConfig(
                                        UsbDevice,
                                        WDF_NO_OBJECT_ATTRIBUTES,
                                        &configParams
                                        );

Contoh kode berikut memilih konfigurasi dengan beberapa antarmuka, menggunakan pengaturan alternatif nol pada semua antarmuka. Contoh ini hanya berlaku untuk driver KMDF.

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS  configParams;
PWDF_USB_INTERFACE_SETTING_PAIR settingPairs;
UCHAR numInterfaces;
NTSTATUS  status;

numInterfaces = WdfUsbTargetDeviceGetNumInterfaces(UsbDevice);

settingPairs = ExAllocatePoolWithTag(
    PagedPool,
    sizeof(WDF_USB_INTERFACE_SETTING_PAIR) * numInterfaces,
    MY_DRIVER_TAG
);

if (settingPairs == NULL){
    return STATUS_INSUFFICIENT_RESOURCES;
}

for (interfaceIndex = 0; interfaceIndex < numInterfaces; interfaceIndex++) {
        
    settingPairs[interfaceIndex].UsbInterface = 
                                    WdfUsbTargetDeviceGetInterface(
                                        UsbDevice,
                                        interfaceIndex);

    // Select alternate setting zero on all interfaces.
       
    settingPairs[interfaceIndex].SettingIndex = 0;
}

WDF_USB_DEVICE_SELECT_CONFIG_PARAMS_INIT_MULTIPLE_INTERFACES(
    &configParams,
    numInterfaces,
    settingPairs
);

status = WdfUsbTargetDeviceSelectConfig(
    UsbDevice,
    NULL,
    &configParams
);

if (!NT_SUCCESS(status)) {
    ExFreePoolWithTag(
        settingPairs,
        MY_DRIVER_TAG
    );
    return status;
}

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)