USBD_UrbAllocate函式 (usbdlib.h)

USBD_UrbAllocate例程會配置 USB 要求區塊 (URB) 。

語法

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

參數

[in] USBDHandle

用戶端驅動程式在先前呼叫 USBD_CreateHandle 例程時擷取的USBD句柄。

[out] Urb

新配置的 URB 結構的指標。 結構的所有成員都會設定為零。 當驅動程式完成使用時，用戶端驅動程式必須藉由呼叫 USBD_UrbFree 來釋放 URB。

傳回值

如果要求成功， USBD_UrbAllocate 例程會傳回STATUS_SUCCESS。 否則，USBD_UrbAllocate會將 Urb 設定為 NULL 並傳回失敗碼。

可能的值包括但不限於STATUS_INVALID_PARAMETER，這表示傳入NULL至 USBDHandle 或 Urb的呼叫端。

備註

USBD_UrbAllocate例程可讓基礎 USB 驅動程式堆疊為 URB 配置不透明的 URB 內容。 藉由使用 URB 內容，USB 驅動程式堆疊可以更有效率且可靠地處理要求。 這些優化是由包含在 Windows 8的 USB 3.0 驅動程式堆疊所提供。 用戶端驅動程式無法存取 URB 內容;內容是由總線驅動程式在內部使用。

不論主機控制器的 USB 通訊協定版本為何，基礎 USB 驅動程式堆疊、目標操作系統，用戶端驅動程式都必須一律呼叫 USBD_UrbAllocate 來配置 URB 結構。 USBD_UrbAllocate 會取代先前的配置機制，例如 ExAllocatePoolWithTag，或在堆疊上配置它們。

用戶端驅動程式 不得 使用 USBD_UrbAllocate，

• 若要配置具有可變長度的 URB，例如 URB 進行連續傳輸。 相反地，用戶端驅動程序必須呼叫 USBD_IsochUrbAllocate。
• 如果目標操作系統是 Service Pack 2 (SP2) 或舊版 Windows 的 Windows XP。

如需取代例程的詳細資訊，請參閱 配置和建置 URI。

您必須呼叫 USBD_UrbFree ，以釋放 由 USBD_UrbAllocate 配置的 URB。

範例

下列程式代碼範例示範如何配置、提交和釋放 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;

}

規格需求

需求	值
最低支援的用戶端	Windows 8 需要 WDK。 以 Windows Vista 和更新版本的 Windows 作業系統為目標。
目標平台	桌面
標頭	usbdlib.h
程式庫	Usbdex.lib
IRQL	DISPATCH_LEVEL

另請參閱

配置和建置URL

將要求傳送至 USB 裝置

USBD_UrbFree