Fungsi WdfUsbTargetDeviceCreate (wdfusb.h)

[Berlaku untuk KMDF dan UMDF]

Metode WdfUsbTargetDeviceCreate membuat objek perangkat USB kerangka kerja untuk objek perangkat kerangka kerja tertentu dan membuka perangkat USB untuk operasi I/O.

Catatan Jika Anda membangun driver menggunakan KMDF 1.11 atau UMDF 2.0, atau yang lebih baru, kami sarankan Anda memanggil WdfUsbTargetDeviceCreateWithParameters alih-alihWdfUsbTargetDeviceCreate.

 

Sintaks

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

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja.

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang disediakan penelepon yang berisi atribut untuk objek perangkat USB 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

WdfUsbTargetDeviceCreate mengembalikan STATUS_SUCCESS 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 perangkat USB baru.
STATUS_UNSUCCESSFUL	Upaya untuk mendapatkan informasi konfigurasi USB gagal.

 

Untuk daftar nilai pengembalian lain yang mungkin dikembalikan oleh metode WdfUsbTargetDeviceCreate , 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

Driver yang menggunakan target USB I/O harus memanggil WdfUsbTargetDeviceCreate setelah perangkatnya memasuki status berfungsi (D0). Biasanya, driver memanggil WdfUsbTargetDeviceCreate dari dalam fungsi panggilan balik EvtDevicePrepareHardware . (Driver tidak dapat memanggil WdfUsbTargetDeviceCreate dari dalam fungsi panggilan balik EvtDriverDeviceAdd .)

WdfUsbTargetDeviceCreate mendapatkan deskriptor perangkat USB dan deskriptor konfigurasi USB pertama dari perangkat dan menyimpannya. Ini juga membuat objek antarmuka USB kerangka kerja untuk setiap antarmuka dalam konfigurasi pertama perangkat. Untuk menentukan jumlah antarmuka yang didukung konfigurasi, driver dapat memanggil WdfUsbTargetDeviceGetNumInterfaces.

Setelah memanggil WdfUsbTargetDeviceCreate, driver Anda dapat memanggil metode objek perangkat USB kerangka kerja tambahan.

Induk dari setiap objek perangkat USB adalah objek driver kerangka kerja driver. Driver tidak dapat mengubah induk ini, dan anggota ParentObject atau struktur WDF_OBJECT_ATTRIBUTES harus NULL.

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

Contoh

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

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

    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;
    }
 status = WdfUsbTargetDeviceCreate(
                                      Device,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        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), UsbDeviceCreate(kmdf), UsbDeviceCreateFail(kmdf), UsbDeviceCreateTarget(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Lihat juga

EvtDevicePrepareHardware

WDF_OBJECT_ATTRIBUTES

WdfUsbTargetDeviceGetNumInterfaces