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