LPFN_WSAPOLL

コールバック

シグネチャ

INT LPFN_WSAPOLL(
    WSAPOLLFD* fdarray,
    DWORD nfds,
    INT timeout
);

パラメーター

フィールド

型

説明

fdarray

WSAPOLLFD*

状態を要求するソケットの集合を指定する、1 つ以上の POLLFD 構造体の配列です。この配列には、有効なソケットを持つ構造体が少なくとも 1 つ含まれている必要があります。戻り時には、このパラメーターは、状態の問い合わせ条件に一致した各ソケットについて revents 状態フラグメンバーが設定された、更新後のソケットを受け取ります。

nfds

DWORD

timeout

INT

待機動作を指定する値で、次の値のいずれかを指定します。

値	意味
0 より大きい値	待機する時間 (ミリ秒単位)。
0	直ちに戻ります。
0 より小さい値	無期限に待機します。

公式ドキュメント

WSAPoll 関数は、1 つ以上のソケットの状態を判定します。

戻り値

次のいずれかの値を返します。

戻り値	説明
0	タイマーが満了する前に、問い合わせた状態になったソケットはありませんでした。
0 より大きい値	fdarray の要素のうち、POLLFD 構造体の revents メンバーが 0 以外である要素の数です。
SOCKET_ERROR	エラーが発生しました。拡張エラーコードを取得するには WSAGetLastError 関数を呼び出してください。

拡張エラーコード	意味
WSAENETDOWN	ネットワークサブシステムが機能していません。
WSAEFAULT	ユーザーの入力パラメーターの読み取り中に例外が発生しました。
WSAEINVAL	無効なパラメーターが渡されました。このエラーは、ソケットの状態を要求する際に fdarray パラメーターが指す WSAPOLLFD 構造体に問題がある場合に返されます。また、fdarray パラメーターが指すいずれの WSAPOLLFD 構造体の fd メンバーにも、有効なソケットが指定されていなかった場合にも、このエラーが返されます。
WSAENOBUFS	関数は十分なメモリを割り当てられませんでした。

解説(Remarks)

WSAPoll 関数は、Windows Vista 以降で定義されています。

WSAPOLLFD 構造体です。アプリケーションは、対応する各ソケットについて要求する状態の種類を指定するために、WSAPOLLFD 構造体の events メンバーに適切なフラグを設定します。 WSAPoll 関数は、ソケットの状態を WSAPOLLFD 構造体の revents メンバーに返します。

呼び出し元は、ソケットごとに読み取りまたは書き込みの状態に関する情報を要求できます。エラー条件は常に返されるため、それらの情報を要求する必要はありません。

fdarray パラメーターが指す WSAPOLLFD 構造体です。これらの条件を満たさず、エラー条件もないソケットはすべて、対応する revents メンバーが 0 に設定されます。

あるソケットの状態を要求する際、そのソケットについて WSAPOLLFD 構造体には次のフラグを組み合わせて設定できます。

フラグ	説明
POLLPRI	優先データをブロックせずに読み取ることができます。このフラグは Microsoft Winsock プロバイダーではサポートされていません。
POLLRDBAND	優先帯域 (帯域外) のデータをブロックせずに読み取ることができます。
POLLRDNORM	通常のデータをブロックせずに読み取ることができます。
POLLWRNORM	通常のデータをブロックせずに書き込むことができます。

POLLIN フラグは、POLLRDNORM と POLLRDBAND のフラグ値の組み合わせとして定義されています。POLLOUT フラグは、POLLWRNORM フラグ値と同じものとして定義されています。

WSAPOLLFD 構造体には、Winsock プロバイダーがサポートする上記フラグの組み合わせのみを設定する必要があります。それ以外の値はエラーとみなされ、WSAPoll は SOCKET_ERROR を返します。続けて WSAGetLastError 関数を呼び出すと、拡張エラーコード WSAEINVAL が取得されます。Microsoft Winsock プロバイダーのソケットに POLLPRI フラグが設定されている場合、WSAPoll 関数は失敗します。

fdarray パラメーターが指す WSAPOLLFD 構造体でソケットの状態を示す場合は、次のとおりです。

フラグ	説明
POLLERR	エラーが発生しました。
POLLHUP	ストリーム指向の接続が切断されたか、中止されました。
POLLNVAL	無効なソケットが使用されました。
POLLPRI	優先データをブロックせずに読み取ることができます。このフラグは Microsoft Winsock プロバイダーからは返されません。
POLLRDBAND	優先帯域 (帯域外) のデータをブロックせずに読み取ることができます。
POLLRDNORM	通常のデータをブロックせずに読み取ることができます。
POLLWRNORM	通常のデータをブロックせずに書き込むことができます。

TCP ソケットおよび UDP ソケットについては、次のとおりです。

WSAPOLLFD 構造体では、通常のデータとして POLLRDNORM で示されます。
WSAPOLLFD 構造体。この場合、続く recv 操作はブロックせずに完了することが保証されます。
WSAPOLLFD 構造体では POLLWRNORM で示されます。
WSAPOLLFD 構造体では POLLRDNORM で示されます。続けて accept を呼び出した場合、ブロックせずに完了することが保証されます。
WSAPOLLFD 構造体では POLLRDBAND で示されます。
WSAPOLLFD 構造体。リモートピアが send 操作をシャットダウンした (TCP FIN を受信した) 場合です。続く recv 関数の要求は 0 バイトを返します。
WSAPOLLFD 構造体。リモートピアが正常な切断を開始した場合です。
WSAPOLLFD 構造体。リモートピアが突然切断したときに返されます。
WSAPOLLFD 構造体。ローカルソケットが閉じられた場合です。

fdarray 内の要素数 (ソケット数ではありません) は nfds で示されます。fdarray のメンバーのうち、fd メンバーが負の値に設定されているものは無視され、戻り時にその revents は POLLNVAL に設定されます。この動作は、fdarray の割り当てを固定して保持し、未使用の要素を取り除くために配列を詰めたりメモリを再割り当てしたりしないアプリケーションに役立ちます。WSAPoll を呼び出す前に、どの要素についても revents をクリアする必要はありません。

timeout 引数は、関数が戻るまでにどれだけ待機するかを指定します。正の値は、戻るまでに待機するミリ秒数を表します。値が 0 の場合、WSAPoll は直ちに戻ります。負の値は、WSAPoll が無期限に待機することを示します。

注 timeout パラメーターに負の値を指定して WSAPoll のようなブロッキング Winsock 呼び出しを発行した場合、Winsock は呼び出しを完了できるようになるまでネットワークイベントを待機する必要があることがあります。この状況で Winsock はアラート可能な待機を行うため、同じスレッドにスケジュールされた非同期プロシージャ呼び出し (APC) によって中断されることがあります。同じスレッドで実行中のブロッキング Winsock 呼び出しを中断した APC の内部で、さらに別のブロッキング Winsock 呼び出しを発行すると未定義の動作となるため、Winsock クライアントは決してこれを行ってはなりません。

注 Windows 10 バージョン 2004 以降では、TCP ソケットの接続に失敗した場合、(POLLHUP \| POLLERR \| POLLWRNORM) が示されます。

Windows 8.1 および Windows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされます。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)