Fungsi WdfUsbInterfaceSelectSetting (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbInterfaceSelectSetting memilih pengaturan alternatif tertentu untuk antarmuka USB tertentu.

Sintaks

NTSTATUS WdfUsbInterfaceSelectSetting(
  [in]           WDFUSBINTERFACE                          UsbInterface,
  [in, optional] PWDF_OBJECT_ATTRIBUTES                   PipesAttributes,
  [in]           PWDF_USB_INTERFACE_SELECT_SETTING_PARAMS Params
);

Parameter

[in] UsbInterface

Handel ke objek antarmuka USB yang diperoleh dengan memanggil WdfUsbTargetDeviceGetInterface.

[in, optional] PipesAttributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang menentukan atribut objek untuk objek pipa yang dibuat kerangka kerja untuk antarmuka. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[in] Params

Penunjuk ke struktur WDF_USB_INTERFACE_SELECT_SETTING_PARAMS yang disediakan penelepon yang berisi parameter pemilihan antarmuka.

Nilai kembali

WdfUsbInterfaceSelectSetting 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_INSUFFICIENT_RESOURCES	Memori tidak cukup untuk membuat objek pipa baru.

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfUsbInterfaceSelectSetting , lihat Kesalahan Pembuatan Objek Kerangka Kerja.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Setelah driver Anda memanggil WdfUsbTargetDeviceSelectConfig untuk memilih konfigurasi, driver dapat memanggil WdfUsbInterfaceSelectSetting untuk memilih pengaturan alternatif untuk salah satu antarmuka perangkat.

Driver Anda dapat memilih pengaturan alternatif antarmuka dengan menentukan deskriptor antarmuka USB atau URB, atau hanya dengan menyediakan pengaturan alternatif untuk antarmuka. Dalam semua kasus, driver harus menyediakan handel ke objek antarmuka.

Jika driver Anda hanya menyediakan pengaturan alternatif, kerangka kerja menggunakan objek antarmuka untuk menentukan antarmuka tempat pengaturan berada.

Jika driver Anda menentukan pendeskripsi antarmuka atau URB, kerangka kerja menggunakan antarmuka yang ditentukan dalam deskriptor atau URB.

Kerangka kerja membuat objek alur USB kerangka kerja untuk setiap pipa yang terkait dengan antarmuka, setelah menghapus objek pipa apa pun yang mungkin telah dibuat kerangka kerja sebelumnya untuk antarmuka. Untuk mendapatkan informasi tentang objek pipa antarmuka, driver Anda dapat memanggil WdfUsbInterfaceGetNumConfiguredPipes dan WdfUsbInterfaceGetConfiguredPipe.

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

Contoh

Contoh kode berikut menginisialisasi struktur WDF_OBJECT_ATTRIBUTES dengan atribut untuk objek pipa yang akan dibuat kerangka kerja. Kemudian, contoh menginisialisasi struktur WDF_USB_INTERFACE_SELECT_SETTING_PARAMS untuk menentukan pengaturan alternatif 1. Terakhir, contoh memanggil WdfUsbInterfaceSelectSetting untuk memilih pengaturan alternatif dan membuat objek pipa untuk pipa antarmuka.

WDF_OBJECT_ATTRIBUTES  pipesAttributes;
WDF_USB_INTERFACE_SELECT_SETTING_PARAMS  selectSettingParams;
NTSTATUS  Status;

WDF_OBJECT_ATTRIBUTES_INIT(&pipesAttributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &pipesAttributes,
                                       MY_PIPE_CONTEXT
                                       );

WDF_USB_INTERFACE_SELECT_SETTING_PARAMS_INIT_SETTING(
                                      &selectSettingParams,
                                      1
                                      );

Status = WdfUsbInterfaceSelectSetting(
                                      UsbInterface,
                                      &pipesAttributes,
                                      &selectSettingParams
                                      );

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)