Fungsi WdfUsbTargetDeviceCreateIsochUrb (wdfusb.h)

Artikel
08/08/2023

[Berlaku untuk KMDF saja]

Metode WdfUsbTargetDeviceCreateIsochUrb mengalokasikan blok permintaan USB isochronous (URB).

Sintaks

NTSTATUS WdfUsbTargetDeviceCreateIsochUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            ULONG                  NumberOfIsochPackets,
  [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.

[in] NumberOfIsochPackets

Menentukan jumlah paket isochronous yang sistemnya mengalokasikan memori dalam URB.

[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 isochronous baru. Kerangka kerja menginisialisasi konten struktur URB ke nol. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfUsbTargetDeviceCreateIsochUrb 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 tersedia.

Metode ini juga mungkin mengembalikan nilai NTSTATUS lainnya.

Keterangan

Sebelum memanggil WdfUsbTargetDeviceCreateIsochUrb, driver harus memanggil WdfUsbTargetDeviceCreateWithParameters. Jika berhasil, WdfUsbTargetDeviceCreateIsochUrb mengembalikan handel ke objek memori kerangka kerja yang menjelaskan URB isochronous yang baru dialokasikan.

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

Biasanya, driver memanggil WdfUsbTargetDeviceCreateIsochUrb dari dalam handler permintaan.

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

Untuk informasi terkait, lihat bagian Keterangan dari WdfUsbTargetDeviceCreateUrb.

Contoh

Contoh kode berikut didasarkan pada rutinitas PerformIsochTransfer di driver sampel Isorwr. Contoh memanggil WdfUsbTargetDeviceCreateIsochUrb untuk mengalokasikan blok permintaan USB isochronous. Contoh menentukan jumlah byte yang diperlukan untuk menahan permintaan transfer isochronous, lalu mengonfigurasi header URB secara manual dan paket isochronous di URB. Pada titik ini, driver dapat memanggil WdfUsbTargetPipeFormatRequestForUrb, seperti yang ditunjukkan dalam contoh di WdfUsbTargetDeviceCreateUrb.


USBD_PIPE_HANDLE usbdPipeHandle;
ULONG numPackets = UserBufferLength/TransferSizePerFrame;
ULONG urbSize;
PURB urb;  
WDFMEMORY memory;

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

status = WdfUsbTargetDeviceCreateIsochUrb(
                                     pDevContext->WdfUsbTargetDevice,  
                                     &objectAttribs,  
                                     0, 
                                     numPackets, 
                                     &memory,  
                                     NULL  
                                     ); 
 
urb = WdfMemoryGetBuffer(urbMemory, &urbSize); 
urbSize = GET_ISO_URB_SIZE(numPackets);  

usbdPipeHandle = WdfUsbTargetPipeWdmGetPipeHandle(pipe);
urb->UrbIsochronousTransfer.Hdr.Length = GET_ISO_URB_SIZE(numPackets);  
urb->UrbIsochronousTransfer.Hdr.Function = URB_FUNCTION_ISOCH_TRANSFER;  
urb->UrbIsochronousTransfer.PipeHandle = usbdPipeHandle; 

for (packetId = 0; packetId < numberOfPackets; packetId++) {

     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].Offset = xxx;
     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].YYY = yyy;
}

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

WdfUsbTargetDeviceCreateUrb

WdfUsbTargetDeviceCreateWithParameters

Bagikan melalui