функция USBD_UrbAllocate (usbdlib.h)

Статья
02/26/2024

Подпрограмма USBD_UrbAllocate выделяет блок запросов USB (URB).

Синтаксис

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

Параметры

[in] USBDHandle

Дескриптор USBD, полученный драйвером клиента при предыдущем вызове процедуры USBD_CreateHandle .

[out] Urb

Указатель на только что выделенную структуру URB . Все элементы структуры равны нулю. Драйвер клиента должен освободить URB после завершения использования драйвера путем вызова USBD_UrbFree.

Возвращаемое значение

Подпрограмма USBD_UrbAllocate возвращает STATUS_SUCCESS, если запрос выполнен успешно. В противном случае USBD_UrbAllocate присваивает Urb значение NULL и возвращает код сбоя.

Возможные значения включают, помимо прочего, STATUS_INVALID_PARAMETER, которые указывают, что вызывающий объект передается в ФОРМАТЕ NULL в USBDHandle или Urb.

Подпрограмма USBD_UrbAllocate позволяет базовому стеку драйверов USB выделять непрозрачный контекст URB для URB. С помощью контекста URB стек usb-драйвера может более эффективно и надежно обрабатывать запросы. Эти оптимизации обеспечиваются стеком драйверов USB 3.0, включенным в Windows 8. Драйвер клиента не может получить доступ к контексту URB; контекст используется для внутреннего использования водителем автобуса.

Независимо от версии протокола USB хост-контроллера, базового стека драйверов USB и целевой операционной системы драйвер клиента всегда должен вызывать USBD_UrbAllocate для выделения структуры URB . USBD_UrbAllocate заменяет более ранние механизмы выделения, такие как ExAllocatePoolWithTag или их выделение в стеке.

Драйвер клиента не должен использовать USBD_UrbAllocate.

Выделение URB с переменной длиной, например URB для изохронной передачи. Вместо этого драйвер клиента должен вызывать USBD_IsochUrbAllocate.
Если целевой операционной системой является Windows XP с пакетом обновления 2 (SP2) или более ранней версией Windows.

Дополнительные сведения о процедурах замены см. в разделе Выделение и создание urb.

Чтобы освободить URB, выделенный USBD_UrbAllocate, необходимо вызвать USBD_UrbFree.

Примеры

В следующем примере кода показано, как выделить, отправить и освободить URB. Пример отправляет URB синхронно. Сведения о реализации функции SubmitUrbSync см. в разделе примера статьи Отправка 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;

}

Требования

Требование	Значение
Минимальная версия клиента	Требуется WDK для Windows 8. Предназначен для Windows Vista и более поздних версий операционной системы Windows.
Целевая платформа	Персональный компьютер
Верхняя часть	usbdlib.h
Библиотека	Usbdex.lib
IRQL	DISPATCH_LEVEL

См. также раздел

Выделение и создание urb

Отправка запросов на USB-устройство

USBD_UrbFree

Поделиться через