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

Статья
02/07/2025

Подпрограмма 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.

Дополнительные сведения о подпрограммах замены см. в выделении и создании URI-объектов.

Чтобы освободить 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

См. также

выделение и создание

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

USBD_UrbFree

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