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 構造体へのポインター。 構造体のすべてのメンバーは 0 に設定されます。 クライアント ドライバーは、ドライバーが USBD_UrbFreeを呼び出して URB の使用を完了したときに解放する必要があります。

戻り値

要求が成功した場合、USBD_UrbAllocate ルーチンはSTATUS_SUCCESSを返します。 それ以外の場合、 USBD_UrbAllocateUrb を NULL に設定し、エラー コードを返します。

使用可能な値には、 USBDHandle または Urb に NULL で渡された呼び出し元を示すSTATUS_INVALID_PARAMETERが含まれますが、これらに限定されません。

注釈

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 を呼び出す必要があります。
  • 対象のオペレーティング システムが Windows XP Service Pack 2 (SP2) 以前のバージョンの Windows の場合。
置換ルーチンの詳細については、「 URB の割り当てとビルド」を参照してください。

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 オペレーティング システムを対象としています。
対象プラットフォーム デスクトップ
Header usbdlib.h
Library Usbdex.lib
IRQL DISPATCH_LEVEL

こちらもご覧ください

URB の割り当てと構築

USB デバイスへの要求の送信

USBD_UrbFree