Fungsi WdfUsbTargetDeviceCreateUrb (wdfusb.h)

  • Artikel

[Berlaku untuk KMDF saja]

Metode WdfUsbTargetDeviceCreateUrb mengalokasikan blok permintaan USB (URB).

Sintaks

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

Parameter

[in] UsbDevice

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

[in, optional] Attributes

Penunjuk ke struktur WDF_OBJECT_ATTRIBUTES yang disediakan penelepon yang berisi atribut untuk objek memori baru. Jika driver menyediakan parameter ini, anggota ParentObject struktur harus menjadi objek perangkat USB (WDFUSBDEVICE) atau objek permintaan (WDFREQUEST) yang dibuat oleh kerangka kerja, atau objek apa pun yang rantai induknya mengarah ke salah satu jenis ini. Parameter ini bersifat opsional dan dapat WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

Penunjuk ke lokasi yang diketik WDFMEMORY yang menerima handel ke objek memori kerangka kerja.

[out, optional] Urb

Penunjuk ke struktur URB yang menerima alamat URB yang baru dialokasikan. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfUsbTargetDeviceCreateUrb 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_INVALID_DEVICE_STATE
 Driver tidak menentukan versi kontrak klien ketika disebut WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES
 Memori tidak cukup untuk membuat URB baru.
 

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

Keterangan

Sebelum memanggil WdfUsbTargetDeviceCreateUrb, driver harus memanggil WdfUsbTargetDeviceCreateWithParameters. Jika berhasil, WdfUsbTargetDeviceCreateUrb mengembalikan handel ke objek memori kerangka kerja yang menjelaskan URB yang baru dialokasikan. Biasanya, driver memanggil WdfUsbTargetDeviceCreateUrb dari dalam handler permintaan.

Driver dapat memanggil WdfUsbTargetDeviceCreateUrb untuk mengalokasikan struktur URB sebelum memanggil WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb mirip dengan WdfMemoryCreate. Kedua metode mengalokasikan objek memori kerangka kerja, dan kedua metode juga menyediakan opsi untuk menerima buffer (dalam hal ini, URB) yang terkait dengan objek memori. Dalam kedua kasus, pemanggil juga dapat mengambil buffer nanti dengan memanggil WdfMemoryGetBuffer.

Jika driver menyediakan parameter Urb saat memanggil WdfUsbTargetDeviceCreateUrb, Anda dapat memformat URB secara manual atau dengan memanggil rutinitas UsbBuildXxx.

Objek memori dan buffernya dihapus ketika objek induk dihapus. Driver juga dapat menghapus objek memori dan buffernya dengan memanggil WdfObjectDelete.

Contoh

Contoh kode berikut mendeklarasikan objek memori kerangka kerja. Contoh memanggil WdfUsbTargetDeviceCreateUrb untuk mengalokasikan blok permintaan USB, lalu memanggil WdfUsbTargetDeviceFormatRequestForUrb untuk memformat permintaan yang menggunakan konten struktur URB. Terakhir, contoh mendaftarkan fungsi panggilan balik CompletionRoutine dan mengirim permintaan ke target I/O.

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista
Target Platform Universal
Versi KMDF minimum 1.11
Header wdfusb.h (termasuk Wdfusb.h)
Pustaka Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL <=DISPATCH_LEVEL
Aturan kepatuhan DDI DriverCreate(kmdf)

Lihat juga

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb