WinUsb_ControlTransfer関数 (winusb.h)

[アーティクル]
08/27/2023

WinUsb_ControlTransfer関数は、既定の制御エンドポイントに制御データを送信します。

構文

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

パラメーター

[in] InterfaceHandle

選択した構成のインターフェイスへの不透明なハンドル。

コントロール要求の受信者をデバイス全体または最初のインターフェイスとして指定するには、 WinUsb_Initializeによって返されるハンドルを使用します。他のすべてのインターフェイスについて、 WinUsb_GetAssociatedInterfaceを呼び出してターゲットインターフェイスへのハンドルを取得し、取得したインターフェイスハンドルを指定して WinUsb_ControlTransfer を呼び出します。

[in] SetupPacket

WINUSB_SETUP_PACKET型の 8 バイトセットアップパケット。

[out] Buffer

転送するデータを含む呼び出し元によって割り当てられたバッファー。このバッファーの長さは 4 KB を超えることはできません。

[in] BufferLength

セットアップパケットを含まない、転送するバイト数。この数値は 、Buffer のサイズ (バイト単位) 以下である必要があります。

[out, optional] LengthTransferred

転送された実際のバイト数を受け取る ULONG 変数へのポインター。データフェーズ中にデータが転送されることをアプリケーションが想定していない場合 (BufferLength はゼロ) 、LengthTransferred に NULL を指定できます。

[in, optional] Overlapped

非同期操作に使用される OVERLAPPED 構造体への省略可能なポインター。このパラメーターを指定すると、 WinUsb_ControlTransfer はすぐに戻り、操作が完了するとイベントが通知されます。 Overlapped が指定されていない場合、WinUsb_ControlTransfer関数はデータを同期的に転送します。

戻り値

操作が 成功した場合、WinUsb_ControlTransfer は TRUE を 返します。それ以外の場合、このルーチンは FALSE を返し、呼び出し元は GetLastError を呼び出すことによってログに記録されたエラーを取得できます。

GetLastError は 、次のいずれかのエラーコードを返すことができます。

リターンコード	説明
ERROR_INVALID_HANDLE	呼び出し元は InterfaceHandle パラメーターに NULL を渡しました。
ERROR_NOT_ENOUGH_MEMORY	操作を実行するためのメモリが不足していることを示します。

注釈

コントロール要求は常にホストによって USB デバイスの既定のエンドポイントに送信されますが、要求の受信者は、選択した代替設定のデバイス全体、インターフェイス、またはエンドポイントにすることができます。 WinUsb_ControlTransfer呼び出しでは、アプリケーションは、InterfaceHandle と SetupPacket の 2 つのパラメーターを使用して受信者を示す必要があります。

コントロール要求の受信者がデバイス全体、最初のインターフェイス、またはそのインターフェイス内の任意のエンドポイントである場合、アプリケーションは、WinUsb_Initializeによって返されるハンドルを使用する必要があります。受信者が他のインターフェイスまたはそのエンドポイントである場合、アプリケーションは、 WinUsb_GetAssociatedInterfaceを呼び出してターゲットインターフェイスに関連付けられている WinUSB ハンドルを取得し、取得したインターフェイスハンドルを指定して WinUsb_ControlTransfer を呼び出す必要があります。

公式 USB 仕様のセクション 9.3 に従って、コントロール転送のセットアップトークンには要求に関する情報が含まれています。 WinUSB アプリケーションの場合、そのセットアップトークンは、WINUSB_SETUP_PACKET 構造体を使用して記述されます。

セットアップトークン内では、 bmRequestType フィールドと wIndex フィールドを使用して、要求の受信者を示します。これらのフィールドは、それぞれ WINUSB_SETUP_PACKET の RequestType メンバーと Index メンバーに対応します。

RequestType の最小 2 ビットは、要求の受信者を示します。受信者は、デバイス、インターフェイス、エンドポイント、またはその他の (ベンダー要求の場合) にすることができます。受信者に応じて、 Index の下位バイトは受信者のデバイス定義インデックスを示します。 Index の値は、要求の種類によって異なります。たとえば、標準の制御要求の場合、値は 0、インターフェイスまたはエンドポイント番号を示します。文字列記述子を取得するGET_DESCRIPTOR要求など、特定の種類の標準要求の 場合、Index 値は言語 ID を示します。

受信者がデバイスの場合は、アプリケーションで RequestType と Index の値を設定する必要があります。 RequestType 値の最小 2 ビットは 0 である必要があります。 Index 値の下位バイトは、要求の種類によって異なります。 InterfaceHandle は、WinUsb_Initializeによって返される WinUSB ハンドルである必要があります。

要求の受信者がインターフェイスである場合、アプリケーションは RequestType の最小 2 ビットを 0x01 に設定する必要があります。アプリケーションは、任意の種類の要求に対して Index の下位バイトを設定する必要はありません。標準、クラス、ベンダーの要求の場合、Winusb.sys ターゲットインターフェイスのインターフェイス番号に値を設定します。 InterfaceHandle はターゲットインターフェイスに関連付けられている必要があります。アプリケーションは、WinUsb_GetAssociatedInterfaceを呼び出すことによって、そのハンドルを取得できます。

受信者がエンドポイントの場合、アプリケーションは RequestType の最小 2 ビットを 0x02 に設定し、Index の下位バイトをエンドポイントアドレスに設定する必要があります。この場合、 InterfaceHandle はエンドポイントを含むインターフェイスに関連付けられます。アプリケーションは、WinUsb_GetAssociatedInterfaceを呼び出すことによって、そのハンドルを取得できます。