LPWSPEVENTSELECT コールバック関数 (ws2spi.h)
LPWSPEventSelect 関数は、指定されたネットワーク イベントのセットに関連付けるイベント オブジェクトを指定します。
構文
LPWSPEVENTSELECT Lpwspeventselect;
int Lpwspeventselect(
[in] SOCKET s,
[in] WSAEVENT hEventObject,
[in] long lNetworkEvents,
[out] LPINT lpErrno
)
{...}
パラメーター
[in] s
ソケットを識別する記述子。
[in] hEventObject
指定されたネットワーク イベントのセットに関連付けられるイベント オブジェクトを識別するハンドル。
[in] lNetworkEvents
Windows ソケット SPI クライアントが関心を持つネットワーク イベントの組み合わせを指定するビットマスク。 これらの値のいずれかと共にビットごとの OR 演算子を使用して構築されます。
| 値 | 意味 |
|---|---|
|
読み取り準備の通知を発行します。 |
|
書き込み準備の通知を発行します。 |
|
OOB データの到着通知を発行します。 |
|
着信接続の通知を発行します。 |
|
完了した接続の通知に関する問題。 |
|
ソケットクロージャの通知を発行します。 |
|
ソケット (QoS) の変更の通知を発行します。 |
|
予約済み。 |
|
指定した宛先のルーティング インターフェイス変更の通知を発行します。 |
|
ソケットのアドレス ファミリのローカル アドレス一覧の変更の通知を発行します。 |
[out] lpErrno
エラー コードへのポインター。 詳細については、「 戻り値 」セクションを参照してください。
戻り値
Windows ソケット SPI クライアントによるネットワーク イベントの指定と、関連付けられたイベント オブジェクトが成功した場合、戻り値は 0 です。 それ以外の場合は、 SOCKET_ERROR 値が返され、 lpErrno で特定のエラー番号を使用できます。
| エラー コード | 意味 |
|---|---|
| ネットワーク サブシステムが失敗しました。 | |
| 指定したパラメーターのいずれかが無効であるか、指定されたソケットが無効な状態であることを示します。 | |
| Windows ソケット呼び出しのブロックが進行中であるか、サービス プロバイダーがコールバック関数を処理しています。 | |
| 記述子はソケットではありません。 |
注釈
この関数は、選択したネットワーク イベント lNetworkEvents に関連付けるイベント オブジェクト hEventObject を指定するために使用されます。 イベント オブジェクトが指定されているソケットは 、 によって識別されます。 イベント オブジェクトは、指定されたネットワーク イベントのいずれかが発生したときに設定されます。
LPWSPEventSelect は LPWSPAsyncSelect とよく似た動作をします。これは、指定されたネットワーク イベントが発生したときに実行されるアクションの違いです。 WSPAsyncSelect によって Windows ソケット SPI クライアント指定の Windows メッセージがポストされるのに対し、LPWSPEventSelect は関連付けられたイベント オブジェクトを設定し、このイベントの発生を内部ネットワーク イベント レコードに記録します。 Windows ソケット SPI クライアントは 、LPWSPEnumNetworkEvents を使用して内部ネットワーク イベント レコードの内容を取得し、どのネットワーク イベントが発生したのかを判断できます。
LPWSPEventSelect は、 LPWSPEnumNetworkEvents を使用してネットワーク アクティビティとエラーを記録および取得できるようにする唯一の関数です。 これらの関数がネットワーク アクティビティとエラーを報告する方法については、 LPWSPSelect と LPWSPAsyncSelect の説明を参照してください。
この関数は、lNetworkEvents の値に関係なく、ソケット s を非ブロッキング モードに自動的に設定します。
ソケットに 対して LPWSPEventSelect を 発行すると、同じソケットの以前の LPWSPAsyncSelect または LPWSPEventSelect が取り消され、内部ネットワーク イベント レコードがクリアされます。 たとえば、イベント オブジェクトをネットワーク イベントの読み取りと書き込みの両方に関連付けるには、Windows ソケット SPI クライアントは、次のように、FD_READとFD_WRITEの両方で LPWSPEventSelect を 呼び出す必要があります。
rc = WSPEventSelect(s, hEventObject, FD_READ | FD_WRITE);
ネットワーク イベントごとに異なるイベント オブジェクトを指定することはできません。 次のコードは機能しません。2 番目の呼び出しでは最初の 呼び出しの効果が取り消され、関連付けは hEventObject2 に関連付けられたFD_WRITEネットワーク イベントのみです。
// Incorrect example.
rc = WSPEventSelect(s, hEventObject1, FD_READ);
rc = WSPEventSelect(s, hEventObject2, FD_WRITE);
ソケット上のネットワーク イベントの関連付けと選択を取り消すには、 lNetworkEvents を 0 に設定する必要があります。この場合、 hEventObject パラメーターは無視されます。
rc = WSPEventSelect(s, hEventObject, 0);
LPWSPCloseSocket を使用してソケットを閉じると、ソケットの LPWSPEventSelect で指定されたネットワーク イベントの関連付けと選択も取り消されます。 ただし、Windows ソケット SPI クライアントでは、 WSACloseEvent を呼び出してイベント オブジェクトを明示的に閉じ、リソースを解放する必要があります。
LPWSPAccept'ed ソケットには、それを受け入れるために使用されるリッスン ソケットと同じプロパティがあるため、リッスンしているソケットに設定された LPWSPEventSelect 関連付けとネットワーク イベントの選択は、受け入れられたソケットに適用されます。 たとえば、リッスン しているソケットに hEventObject と FD_ACCEPT、FD_READ、および FD_WRITE の LPWSPEventSelect 関連付けがある場合、そのリッスン ソケットで受け入れられるソケットには、同じ hEventObject に関連付けられたFD_ACCEPT、FD_READ、FD_WRITEネットワーク イベントも含まれます。 別の hEventObject またはネットワーク イベントが必要な場合、Windows ソケット SPI クライアントは LPWSPEventSelect を呼び出し、受け入れられたソケットと必要な新しい情報を渡す必要があります。
ネットワーク イベントの発生を正常に記録し、関連付けられたイベント オブジェクトにシグナルを送信した後、Windows ソケット SPI クライアントが関数呼び出しを行い、そのネットワーク イベントの設定と関連付けられたイベント オブジェクトのシグナルを暗黙的に再度有効にするまで、そのネットワーク イベントに対してそれ以上のアクションは実行されません。
| ネットワーク イベント | 関数の再有効化 |
|---|---|
| FD_READ | LPWSPRecv または LPWSPRecvFrom |
| FD_WRITE | LPWSPSend または LPWSPSendTo |
| FD_OOB | LPWSPRecv または LPWSPRecvFrom |
| FD_ACCEPT | LPWSPAccept は、返されるエラー コードが条件関数から返されたことを示すWSATRY_AGAINでない限りCF_DEFER |
| FD_CONNECT | NONE |
| FD_CLOSE | NONE |
| FD_QOS | SIO_GET_QOSを使用した LPWSPIoctl |
| FD_GROUP_QOS | ソケット グループでの将来の使用のために予約済み: SIO_GET_GROUP_QOSを使用した LPWSPIoctl |
| FD_ROUTING_INTERFACE_CHANGE | コマンド SIO_ROUTING_INTERFACE_CHANGEを使用した LPWSPIoctl |
| FD_ADDRESS_LIST_CHANGE | コマンド SIO_ADDRESS_LIST_CHANGEを使用した LPWSPIoctl |
再有効化ルーチンを呼び出すと、失敗したルーチンであっても、関連するネットワーク イベントとイベント オブジェクトの記録とシグナルの再有効化が行われます。
ネットワーク イベントのFD_READ、FD_OOB、およびFD_ACCEPTの場合、ネットワーク イベントの記録とイベント オブジェクトのシグナリングは レベル によってトリガーされます。 つまり、再有効化ルーチンが呼び出され、関連するネットワーク条件が呼び出し後も有効な場合は、ネットワーク イベントが記録され、関連付けられているイベント オブジェクトが通知されます。 これにより、Windows ソケット SPI クライアントは、イベント ドリブンである一方で、一度に到着するデータの量を気にしないようにすることができます。 次の例を考えます。
- サービス プロバイダーは、ソケット s で 100 バイトのデータを受信し、FD_READネットワーク イベントを記録し、関連付けられているイベント オブジェクトに通知します。
- Windows ソケット SPI クライアントは、50 バイトの読み取りを発行
WSPRecv(s, buffptr, 50, 0)します。 - サービス プロバイダーは、FD_READネットワーク イベントを記録し、読み取るデータが残っているため、関連付けられているイベント オブジェクトにもう一度通知します。
これらのセマンティクスを使用すると、Windows ソケット SPI クライアントは、FD_READネットワーク イベントに応答して使用可能なすべてのデータを読み取る必要はありません。 代わりに、各FD_READネットワーク イベントに応答する 1 つの LPWSPRecv が適切です。
FD_QOSイベントとFD_GROUP_QOS イベントは エッジ トリガーと見なされます。 サービス品質 (QOS) の変更が発生すると、メッセージが 1 回だけ投稿されます。 サービス プロバイダーが QOS のさらなる変更を検出するか、Windows ソケット SPI クライアントがソケットの QOS を再ネゴシエーションするまで、それ以上の兆候は発行されません。
FD_ROUTING_INTERFACE_CHANGEイベントとFD_ADDRESS_LIST_CHANGE イベントは、 エッジ トリガー と見なされます。 Windows ソケット SPI クライアントが、SIO_ROUTING_INTERFACE_CHANGEまたはSIO_ADDRESS_LIST_CHANGEを使用して WSAIoctl を発行して通知を要求した後に変更が発生すると、メッセージは 1 回だけ投稿されます。 Windows ソケット SPI クライアントが IOCTL を 再発行し、IOCTL の発行後に別の変更が検出されるまで、それ以上のメッセージは表示されません。
Windows ソケット SPI クライアントが LPWSPEventSelect を呼び出すとき、または再有効化関数が呼び出されたときにネットワーク イベントが既に発生している場合は、ネットワーク イベントが記録され、関連するイベント オブジェクトが必要に応じて通知されます。 たとえば、次のシーケンスを考えてみましょう。
- Windows ソケット SPI クライアントは LPWSPListen を呼び出します。
- 接続要求は受信されましたが、まだ受け入れられません。
- Windows ソケット SPI クライアントは LPWSPEventSelect を呼び出し、ソケットのFD_ACCEPTネットワーク イベントに関心があることを指定します。 サービス プロバイダーは、FD_ACCEPTネットワーク イベントを記録し、関連付けられているイベント オブジェクトに直ちに通知します。
FD_WRITE ネットワーク イベントの処理方法は若干異なります。 FD_WRITE ネットワーク イベントは、ソケットが最初に LPWSPConnect で接続されるか、LPWSPAccept で受け入れられた後、LPWSPSend または LPWSPSendTo が WSAEWOULDBLOCK で失敗し、バッファー領域が使用可能になったときに記録されます。 したがって、Windows ソケット SPI クライアントは、最初のFD_WRITEネットワーク イベント設定から送信が可能であり、送信が WSAEWOULDBLOCK を返すまで持続すると想定できます。 このような障害が発生した後、Windows ソケット SPI クライアントは、FD_WRITEネットワーク イベントが記録され、関連付けられているイベント オブジェクトが通知されたときに、送信が再び可能であることを検出します。
FD_OOB ネットワーク イベントは、帯域外データを個別に受信するようにソケットが構成されている場合にのみ使用されます。 ソケットが帯域外データをインラインで受信するように構成されている場合、帯域外 (優先) データは通常のデータとして扱われます。Windows Sockets SPI クライアントは、ネットワーク イベント FD_OOBではなく、ネットワーク イベントFD_READ関心を登録し、取得します。 Windows ソケット SPI クライアントは、SO_OOBINLINE オプションに LPWSPSetSockOpt または LPWSPGetSockOpt を使用して、帯域外データの処理方法を設定または検査できます。
FD_CLOSE ネットワーク イベントのエラー コードは、ソケットのクローズが正常であったか、または中止されたかを示します。 エラー コードが 0 の場合、クローズは正常でした。エラー コードが WSAECONNRESET の場合は、ソケットの仮想回線がリセットされました。 これは、SOCK_STREAMなどの接続指向ソケットにのみ適用されます。
FD_CLOSE ネットワーク イベントは、ソケットに対応する仮想回線に対して近い表示が受信されたときに記録されます。 TCP 用語では、接続が FIN WAIT 状態または CLOSE WAIT 状態になると、FD_CLOSEが記録されることを意味します。 これは、リモート エンドが送信側で LPWSPShutdown または LPWSPCloseSocket を実行した結果です。
サービス プロバイダーは、仮想回線のクローズを示すために、FD_CLOSEネットワーク イベント のみを 記録する必要があります。FD_READネットワーク イベントを記録して、その状態を示 す べきではありません。
FD_QOSまたはFD_GROUP_QOSネットワーク イベントは、ソケット に関連付けられているフロー スペック内の任意のフィールド、または に属する ソケット グループにそれぞれ変更があった場合に記録されます。 この変更は、SIO_GET_QOSまたはSIO_GET_GROUP_QOSを使用して LPWSPIoctl 関数を使用して Windows ソケット SPI クライアントが使用できるようにする必要があります。ソケット s の場合は現在の QOS を取得するか、ソケット グループ s が属している場合は、それぞれを取得します。
FD_ROUTING_INTERFACE_CHANGE ネットワーク イベントは、 WSAIoctl で指定された宛先に到達するために使用する必要があるローカル インターフェイスが、このような IOCTL の発行 後 に変更SIO_ROUTING_INTERFACE_CHANGE記録されます。
FD_ADDRESS_LIST_CHANGE ネットワーク イベントは、SIO_ADDRESS_LIST_CHANGEを持つ WSAIoctl の後に Windows ソケット SPI クライアントが変更をバインドできるソケットのプロトコル ファミリのアドレスの一覧が発行されたときに記録されます。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 10 ビルド 20348 |
| サポートされている最小のサーバー | Windows 10 ビルド 20348 |
| Header | ws2spi.h |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示