Fungsi WdfUsbTargetDeviceCreateWithParameters (wdfusb.h)

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceCreateWithParameters membuat objek perangkat USB kerangka kerja untuk objek perangkat kerangka kerja tertentu dan membuka perangkat USB untuk operasi I/O. Metode ini juga menentukan informasi konfigurasi untuk objek perangkat USB kerangka kerja.

Sintaks

NTSTATUS WdfUsbTargetDeviceCreateWithParameters(
  [in]           WDFDEVICE                     Device,
  [in]           PWDF_USB_DEVICE_CREATE_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES        Attributes,
  [out]          WDFUSBDEVICE                  *UsbDevice
);

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in] Config

Penunjuk ke struktur WDF_USB_DEVICE_CREATE_CONFIG yang berisi informasi konfigurasi untuk objek perangkat USB kerangka kerja.

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang disediakan penelepon yang berisi atribut untuk objek perangkat USB kerangka kerja baru. (Anggota ParentObject struktur harus NULL.) Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] UsbDevice

Penunjuk ke lokasi yang menerima handel ke objek perangkat USB kerangka kerja baru.

Nilai kembali

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

Menampilkan kode	Deskripsi
STATUS_INFO_LENGTH_MISMATCH	Parameter Konfigurasi bukan ukuran yang benar.
STATUS_INSUFFICIENT_RESOURCES	Memori tidak cukup untuk membuat objek perangkat USB kerangka kerja baru.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid terdeteksi. Lihat bagian Keterangan untuk informasi selengkapnya.
STATUS_UNSUCCESSFUL	Upaya untuk mendapatkan informasi konfigurasi USB gagal.

 

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

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Windows 8 menyertakan tumpukan driver USB baru untuk mendukung perangkat USB 3.0.

Sebelum driver klien berbasis kerangka kerja dapat menggunakan kemampuan baru tumpukan driver USB untuk Windows 8, driver harus mendaftarkan dirinya dengan tumpukan driver USB dasar yang dimuat oleh Windows untuk perangkat. Untuk mendaftarkan driver klien, panggil WdfUsbTargetDeviceCreateWithParameters dan tentukan versi kontrak dalam struktur WDF_USB_DEVICE_CREATE_CONFIG .

Jika driver klien dimaksudkan untuk membangun, menjalankan, dan menggunakan peningkatan dan kemampuan baru pada Windows 8, versi kontrak klien USBD_CLIENT_CONTRACT_VERSION_602.

Biasanya, driver memanggil WdfUsbTargetDeviceCreateWithParameters dari dalam fungsi panggilan balik EvtDevicePrepareHardware . Driver juga dapat memanggil WdfUsbTargetDeviceCreateWithParameters dari dalam fungsi panggilan balik EvtDriverDeviceAdd .

Untuk informasi tentang bagaimana driver klien USB WDM berinteraksi dengan tumpukan driver USB 3.0, lihat Praktik Terbaik: Menggunakan URL.

Jika driver memanggil WdfUsbTargetDeviceCreateWithParameters untuk membuat objek perangkat USB kerangka kerja, driver harus membuat URB hanya dengan memanggil WdfUsbTargetDeviceCreateUrb atau WdfUsbTargetDeviceCreateIsochUrb.

Jika Anda memanggil metode ini dari driver UMDF, Anda harus menentukan direktif UmdfDispatcher dalam file INF driver. Jika tidak, metode ini dapat mengembalikan STATUS_INVALID_PARAMETER. Untuk informasi selengkapnya tentang arahan ini, lihat Menentukan Arahan WDF dalam File INF.

Contoh

Contoh kode berikut adalah bagian dari fungsi panggilan balik EvtDevicePrepareHardware yang memanggil WdfUsbTargetDeviceCreateWithParameters. Contoh menyimpan handel ke objek perangkat USB kerangka kerja di ruang konteks yang ditentukan driver.

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }
...
}

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1.11
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), RequestForUrbXrb(kmdf), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf)

Lihat juga

USBD_CreateHandle

WDF_USB_DEVICE_CREATE_CONFIG

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceBuat