fungsi USBD_UrbAllocate (usbdlib.h)

Artikel
02/26/2024

Rutinitas USBD_UrbAllocate mengalokasikan Usb Request Block (URB).

Sintaks

NTSTATUS USBD_UrbAllocate(
  [in]  USBD_HANDLE USBDHandle,
  [out] PURB        *Urb
);

Parameter

[in] USBDHandle

Handel USBD yang diambil oleh driver klien dalam panggilan sebelumnya ke rutinitas USBD_CreateHandle .

[out] Urb

Arahkan ke struktur URB yang baru dialokasikan. Semua anggota struktur diatur ke nol. Driver klien harus membebaskan URB ketika driver telah selesai menggunakannya dengan memanggil USBD_UrbFree.

Nilai kembali

Rutinitas USBD_UrbAllocate mengembalikan STATUS_SUCCESS jika permintaan berhasil. Jika tidak, USBD_UrbAllocate mengatur Urb ke NULL dan mengembalikan kode kegagalan.

Nilai yang mungkin termasuk, tetapi tidak terbatas pada, STATUS_INVALID_PARAMETER, yang menunjukkan pemanggil diteruskan dalam NULL ke USBDHandle atau Urb.

Keterangan

Rutinitas USBD_UrbAllocate memungkinkan tumpukan driver USB yang mendasar untuk mengalokasikan konteks URB buram untuk URB. Dengan menggunakan konteks URB, tumpukan driver USB dapat memproses permintaan dengan lebih efisien dan andal. Pengoptimalan tersebut disediakan oleh tumpukan driver USB 3.0 yang disertakan dalam Windows 8. Driver klien tidak dapat mengakses konteks URB; konteks digunakan secara internal oleh pengemudi bus.

Terlepas dari versi protokol USB pengontrol host, tumpukan driver USB yang mendasar, sistem operasi target, driver klien harus selalu memanggil USBD_UrbAllocate untuk mengalokasikan struktur URB . USBD_UrbAllocate menggantikan mekanisme alokasi sebelumnya, seperti ExAllocatePoolWithTag, atau mengalokasikannya pada tumpukan.

Driver klien tidak boleh menggunakan USBD_UrbAllocate,

Untuk mengalokasikan URB yang memiliki panjang variabel, seperti URB untuk transfer isochronous. Sebagai gantinya, driver klien harus memanggil USBD_IsochUrbAllocate.
Jika sistem operasi target adalah Windows XP dengan Paket Layanan 2 (SP2) atau versi Windows yang lebih lama.

Untuk informasi selengkapnya tentang rutinitas penggantian, lihat Mengalokasikan dan Membangun URL.

Anda harus memanggil USBD_UrbFree untuk merilis URB yang dialokasikan oleh USBD_UrbAllocate.

Contoh

Contoh kode berikut menunjukkan cara mengalokasikan, mengirimkan, dan merilis URB. Contoh mengirimkan URB secara sinkron. Untuk implementasi fungsi SubmitUrbSync, lihat bagian contoh di Cara Mengirimkan URB.

NTSTATUS CreateandSubmitURBSynchronously (
    _In_ USBD_HANDLE USBDHandle 
{
    PURB    Urb = NULL;

    NTSTATUS status;

    status = USBD_UrbAllocate(USBDHandle, &Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    //Format the URB for the request. Not Shown.
    status = BuildURBForBulkTransfer (Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    status = SubmitUrbSync( TargetDeviceObject,
        Urb)  

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

CreateandSubmitURBExit:

    if (Urb)
    {
        USBD_UrbFree( USBDHandle, Urb); 
    }

    return status;

}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Membutuhkan WDK untuk Windows 8. Menargetkan Windows Vista dan versi yang lebih baru dari sistem operasi Windows.
Target Platform	Desktop
Header	usbdlib.h
Pustaka	Usbdex.lib
IRQL	DISPATCH_LEVEL

Lihat juga

Mengalokasikan dan Membangun URL

Mengirim Permintaan ke Perangkat USB

USBD_UrbFree

Bagikan melalui