WinUsb_GetOverlappedResult関数 (winusb.h)

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

WinUsb_GetOverlappedResult関数は、指定したファイルに対して重複した操作の結果を取得します。

構文

BOOL WinUsb_GetOverlappedResult(
  [in]  WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]  LPOVERLAPPED            lpOverlapped,
  [out] LPDWORD                 lpNumberOfBytesTransferred,
  [in]  BOOL                    bWait
);

パラメーター

[in] InterfaceHandle

WinUsb_Initialize によって返される、デバイス上の最初のインターフェイスへの不透明なハンドル。

[in] lpOverlapped

重なり合った操作が開始されたときに指定された OVERLAPPED 構造体へのポインター。

[out] lpNumberOfBytesTransferred

読み取りまたは書き込み操作によって実際に転送されたバイト数を受け取る変数へのポインター。

[in] bWait

このパラメーターが TRUE の場合、関数は操作が完了するまで戻りません。このパラメーターが FALSE で、操作がまだ保留中の場合、関数は FALSE を 返し、 GetLastError 関数はERROR_IO_INCOMPLETEを返します。

戻り値

関数が成功した場合、戻り値は 0 以外の任意の数値になります。関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

この関数は Win32 API ルーチン GetOverlappedResult に似ていますが、 CreateFile から返されるファイルハンドルを渡す代わりに、呼び出し元は WinUsb_Initialize から返されるインターフェイスハンドルを渡します。適切なハンドルが渡された場合、呼び出し元はいずれかの API ルーチンを使用できます。 WinUsb_GetOverlappedResult関数は、インターフェイスハンドルからファイルハンドルを抽出し、GetOverlappedResult を呼び出します。

WinUsb_GetOverlappedResult関数によって報告される結果は、指定した OVERLAPPED 構造体が指定された、操作の結果が保留中であった、指定されたハンドルの最後の重複した操作の結果です。保留中の操作は、操作を開始した関数が FALSE を返し、 GetLastError ルーチンがERROR_IO_PENDINGを返したときに示されます。 I/O 操作が保留中の場合、操作を開始した関数は OVERLAPPED 構造体の hEvent メンバーを非署名状態にリセットします。その後、保留中の操作が完了すると、システムはイベントオブジェクトをシグナル状態に設定します。

呼び出し元は、 OVERLAPPED 構造体でイベントオブジェクトを手動でリセットすることを指定できます。自動リセットイベントオブジェクトを使用する場合、重複した操作を開始してから WinUsb_GetOverlappedResult の呼び出しまでの間隔で、イベントハンドルを他の待機操作で指定することはできません。たとえば、イベントオブジェクトは、操作が完了するまで待機する待機ルーチンのいずれかで指定される場合があります。待機ルーチンが戻ると、システムは自動リセットイベントの状態を非署名に設定し、bWait パラメーターを TRUE に設定してWinUsb_GetOverlappedResultを連続して呼び出すと、関数が無期限にブロックされます。

bWait パラメーターが TRUE の場合、WinUsb_GetOverlappedResultは、イベントオブジェクトがシグナル状態になるのを待って、保留中の操作が完了したかどうかを判断します。

OVERLAPPED 構造体の hEvent メンバーが NULL の場合、システムはファイルハンドルの状態を使用して、操作が完了したことを通知します。この目的でファイルハンドルを使用しないでください。同じファイルに対して複数の重複した操作が同時に実行された場合に発生する可能性がある混乱のため、イベントオブジェクトを使用することをお勧めします。この状況では、オブジェクトの状態がシグナル通知される原因となった操作を把握できません。