WinUsb_ReadPipe関数 (winusb.h)

  • [アーティクル]

WinUsb_ReadPipe関数は、指定したパイプからデータを読み取ります。

構文

BOOL WinUsb_ReadPipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

パラメーター

[in] InterfaceHandle

パイプが関連付けられているエンドポイントを含むインターフェイスへの不透明なハンドル。

最初のインターフェイスのエンドポイントに関連付けられているパイプからデータを読み取る場合は、 WinUsb_Initializeによって返されるハンドルを使用します。 その他のすべてのインターフェイスでは、WinUsb_GetAssociatedInterfaceによって取得されたターゲット インターフェイスへのハンドル を使用します。

[in] PipeID

PipeID は、エンドポイント記述子の bEndpointAddress フィールドに対応します。 このフィールドのレイアウトについては、USB テクノロジの「ユニバーサル シリアル バス仕様リビジョン 2.0」の表 9-13 を参照してください。 bEndpointAddress フィールドのビット 7 は、エンドポイントの方向を示します。OUT の場合は 0 です。IN の場合は 1。

[out] Buffer

読み取られたデータを受信する呼び出し元によって割り当てられたバッファー。

[in] BufferLength

読み取る最大バイト数。 この数値は 、Buffer のサイズ (バイト単位) 以下である必要があります。

[out, optional] LengthTransferred

Buffer にコピーされた実際のバイト数を受け取る ULONG 変数へのポインター。 詳細については、「解説」を参照してください。

[in, optional] Overlapped

非同期操作に使用される OVERLAPPED 構造体への省略可能なポインター。 このパラメーターを指定した場合、 WinUsb_ReadPipe は、操作が完了するまで同期的に待機してからを返すのではなく、直ちにを返します。 操作が完了すると、イベントが通知されます。

戻り値

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

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

リターン コード 説明
ERROR_INVALID_HANDLE
 呼び出し元が InterfaceHandle パラメーターに NULL を渡しました。
ERROR_IO_PENDING
 重複した I/O 操作は進行中ですが、完了していません。 重複した操作をすぐに完了できない場合、関数は FALSE を 返し、 GetLastError 関数はERROR_IO_PENDINGを返し、操作がバックグラウンドで実行されていることを示します。 WinUsb_GetOverlappedResultを呼び出して、操作の成功または失敗をチェックします。
ERROR_NOT_ENOUGH_MEMORY
 操作を実行するためのメモリが不足しています。
ERROR_SEM_TIMEOUT
 USB スタック内 のWinUsb_ReadPipe によって開始された読み取り操作は、操作が完了する前にタイムアウトしました。

注釈

デバイスによって返されるデータが転送の最大長を超える場合、WinUSB は要求を最大転送長の小さな要求に分割し、それらをシリアルに送信します。 転送長がエンドポイントの最大パケット サイズ ( WINUSB_PIPE_INFORMATION 構造体の MaximumPacketSize メンバーを介して取得可能) の倍数でない場合、WinUSB は転送のサイズを MaximumPacketSize の次の倍数に増やします。

USB パケット サイズは、読み取り要求の転送には考慮されません。 クライアント バッファーに対して大きすぎるパケットでデバイスが応答する場合、読み取り要求の動作は、パイプに設定されているポリシーの種類に対応します。 パイプのポリシーの種類がALLOW_PARTIAL_READS場合、WinUSB は次の転送の先頭に残りのデータを追加します。 ALLOW_PARTIAL_READSが設定されていない場合、読み取り要求は失敗します。 ポリシーの種類の詳細については、「 パイプ ポリシーの変更のための WinUSB 関数」を参照してください。

アプリケーションが Overlapped パラメーター (同期操作) で NULL を渡す場合、読み取り操作で出力データが生成されない場合でも、アプリケーションは LengthTransferred が NULL ではないことを確認する必要があります。

Overlapped が NULL (非同期操作) でない場合は、LengthTransferred を NULL に設定できます。 重複する操作 (および LengthTransferred が NULL 以外の値の場合) の場合、WinUsb_ReadPipeが返された後に LengthTransferred で受け取った値は、重複する操作が完了するまで意味がありません。 パイプから読み取られた実際のバイト数を取得するには、 WinUsb_GetOverlappedResultを呼び出します。

エンドポイントで使用できるデータがない場合 (パイプが空の場合)、 WinUsb_ReadPipe はパイプ内にデータが存在するまで戻りません。 エラー状態が発生した場合、またはアプリケーション指定のタイムアウトが期限切れになった場合、 WinUsb_ReadPipe は常に FALSE を返します。 その戻り値の実際の理由を確認するには、常に GetLastError を呼び出します。 たとえば、このような場合、 GetLastError エラー値は実際の理由を示します。

  • アプリケーションがパイプ ポリシーでタイムアウト値を指定し、そのタイムアウトが期限切れになった場合、 WinUsb_ReadPipe は FALSE を返し、 GetLastError は ERROR_SEM_TIMEOUTを返します。
  • パイプからのデータの読み取り中にエラー状態が発生した場合、 WinUsb_ReadPipe は FALSE を返し、 GetLastError は ERROR_GEN_FAILUREを返します。

要件

要件 値
対象プラットフォーム ユニバーサル
Header winusb.h (Winusb.h を含む)
Library Winusb.lib
[DLL] Winusb.dll

こちらもご覧ください

WinUSB

WinUSB 関数

WinUsb_Initialize