WSASendMsg 関数 (winsock2.h)
WSASendMsg 関数は、接続されたソケットと接続されていないソケットからデータとオプションの制御情報を送信します。
構文
int WSAAPI WSASendMsg(
[in] SOCKET Handle,
[in] LPWSAMSG lpMsg,
[in] DWORD dwFlags,
[out] LPDWORD lpNumberOfBytesSent,
[in] LPWSAOVERLAPPED lpOverlapped,
[in] LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
パラメーター
[in] Handle
ソケットを識別する記述子。
[in] lpMsg
Posix.1g msghdr 構造体を格納する WSAMSG 構造体。
[in] dwFlags
WSASendMsg 関数呼び出しの動作を変更するために使用されるフラグ。 詳細については、「解説」セクションの 「dwFlags の使用」を参照してください。
[out] lpNumberOfBytesSent
I/O 操作が直ちに完了した場合に、この呼び出しによって送信される数 (バイト単位) へのポインター。
lpOverlapped パラメーターが NULL でない場合は、このパラメーターに NULL を使用して、誤った結果を回避します。 このパラメーターは、lpOverlapped パラメーターが NULL でない場合にのみ NULL にすることができます。
[in] lpOverlapped
WSAOVERLAPPED 構造体へのポインター。 重複していないソケットの場合は無視されます。
[in] lpCompletionRoutine
種類: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE
送信操作が完了したときに呼び出される完了ルーチンへのポインター。 重複していないソケットの場合は無視されます。
戻り値
正常に完了し、すぐに完了した場合は 0 を返します。 0 が返されると、呼び出し元のスレッドが警告可能な状態のときに、指定された完了ルーチンが呼び出されます。
SOCKET_ERRORの戻り値と、WSA_IO_PENDINGを返す WSAGetLastError の後続の呼び出しは、重複した操作が正常に開始されたことを示します。その後、イベントや完了ポートなど、他の方法で完了が示されます。
失敗した場合、 は SOCKET_ERROR を返し、その後 の WSAGetLastError の呼び出しでは 、WSA_IO_PENDING以外の値が返されます。 次の表に、エラー コードの一覧を示します。
| エラー コード | 意味 |
|---|---|
| 要求されたアドレスはブロードキャスト アドレスですが、適切なフラグが設定されていません。 | |
| UDP データグラム ソケットの場合、このエラーは、以前の送信操作で ICMP "ポートに到達できません" というメッセージが発生したことを示します。 | |
| lpMsg、lpNumberOfBytesSent、lpOverlapped、または lpCompletionRoutine パラメーターは、ユーザー アドレス空間の有効な部分に完全には含まれていません。 このエラーは、lpMsg パラメーターが指す WSAMSG 構造体の名前メンバーが NULL ポインターであり、WSAMSG 構造体の namelen メンバーがゼロに設定されていない場合にも返されます。 このエラーは、lpMsg パラメーターが指す WSAMSG 構造体の Control.buf メンバーが NULL ポインターであり、WSAMSG 構造体の Control.len メンバーがゼロに設定されていない場合にも返されます。 | |
| ブロックしている Windows ソケット 1.1 呼び出しが進行中であるか、サービス プロバイダーがコールバック関数を処理しています。 | |
| ブロックしている Windows ソケット 1.1 呼び出しが WSACancelBlockingCall によって取り消されました。 | |
| ソケットが bind でバインドされていないか、重複するフラグでソケットが作成されていません。 | |
| ソケットはメッセージ指向であり、メッセージは基になるトランスポートでサポートされている最大値を超えています。 | |
| ネットワーク サブシステムが失敗しました。 | |
| データグラム ソケットに関して、このエラーは有効期限が切れたことを示します。 | |
| ネットワークに到達できません。 | |
| Windows ソケット プロバイダーは、バッファー デッドロックを報告します。 | |
| ソケットは接続されていません。 | |
| 記述子はソケットではありません。 | |
| ソケット操作はサポートされていません。 lpMsg パラメーターが指す WSAMSG 構造体の dwFlags メンバーに、WSASendMsg に無効なコントロール フラグが含まれている場合、このエラーが返されます。 | |
| ソケットがシャットダウンされました。SD_SENDまたはSD_BOTHに設定された方法でシャットダウンが呼び出された後、ソケットで WSASendMsg 関数を呼び出すことはできません。 | |
| ソケットがタイムアウトしました。このエラーは、 ソケットに SO_SNDTIMEO ソケット オプションを使用して指定された待機タイムアウトがあり、タイムアウトを超えた場合に返されます。 | |
| 重複するソケット: 未解決の重複した I/O 要求が多すぎます。 非オーバーラップ ソケット: ソケットは非ブロッキングとしてマークされ、送信操作をすぐに完了することはできません。 | |
| この関数を使用する前に 、WSAStartup 呼び出しが正常に行われる必要があります。 | |
| 重複した操作が正常に開始され、後で完了が示されます。 | |
| ソケットのクローズまたは WSAIoctl での SIO_FLUSH コマンドの実行により、重複した操作が取り消されました。 |
注釈
WSASendMsg 関数は、WSASend 関数と WSASendTo 関数の代わりに使用できます。 WSASendMsg 関数は、データグラムと生ソケットでのみ使用できます。 s パラメーターのソケット記述子は、ソケット型を SOCK_DGRAM または SOCK_RAW に設定して開く必要があります。
dwFlags パラメーターには、MSG_DONTROUTE、MSG_PARTIAL、MSG_OOBのコントロール フラグの組み合わせのみを含めることができます。 lpMsg パラメーターが指す WSAMSG 構造体の dwFlags メンバーは、入力では無視され、出力では使用されません。
重複するソケットは、WSA_FLAG_OVERLAPPED フラグが設定された WSASocket 関数呼び出しで作成されます。 重複するソケットの場合、 lpOverlapped と lpCompletionRoutine の両方が NULL でない限り、情報の送信では重複する I/O が使用されます。 lpOverlapped と lpCompletionRoutine が NULL の場合、ソケットはオーバーラップされていないソケットとして扱われます。 完了の兆候は、重複するソケットで発生します。バッファーまたはバッファーがトランスポートによって使用されると、完了ルーチンがトリガーされるか、イベント オブジェクトが設定されます。 操作がすぐに完了しない場合は、完了ルーチンまたは WSAGetOverlappedResult 関数を呼び出すことによって、最終的な完了状態が取得されます。
オーバーラップされていないソケットの場合、 lpOverlapped パラメーターと lpCompletionRoutine パラメーターは無視され、 WSASendMsg はsend 関数と同じブロッキング セマンティクスを採用します。データはバッファーまたはバッファーからトランスポートのバッファーにコピーされます。 ソケットが非ブロッキングでストリーム指向であり、トランスポートのバッファーに十分な領域がない場合、 WSASendMsg は アプリケーションのバッファーの一部のみが消費された状態でを返します。 これに対し、ブロッキング ソケット上のこのバッファー状況では、アプリケーションのすべてのバッファー コンテンツが使用されるまで WSASendMsg がブロックされます。
この関数が重複した方法で完了した場合、この呼び出しから戻る前に、この WSABUF 構造体をキャプチャするのは Winsock サービス プロバイダーの責任です。 これにより、アプリケーションは lpMsg パラメーターが指す WSAMSG 構造体の lpBuffers メンバーが指すスタック ベースの WSABUF 配列を構築できます。
メッセージ指向ソケットの場合は、基になるプロバイダーの最大メッセージ サイズを超えないように注意する必要があります。これは、ソケット オプション SO_MAX_MSG_SIZEの値を取得することで取得できます。 データが長すぎて基になるプロトコルをアトミックに通過できない場合は、 エラー WSAEMSGSIZE が返され、データは送信されません。
SOCK_DGRAMタイプまたはSOCK_RAWの IPv4 ソケットでは、アプリケーションは WSASendMsg 関数を使用して送信するために使用するローカル IP ソース アドレスを特定できます。 WSAMSG 構造体で WSASendMsg 関数に渡される制御データ・オブジェクトの 1 つに、送信に使用するローカル IPv4 ソース・アドレスを指定するために使用されるin_pktinfo構造が含まれている場合があります。
SOCK_DGRAMタイプまたはSOCK_RAWの IPv6 ソケットでは、アプリケーションは WSASendMsg 関数を使用して送信するために使用するローカル IP ソース・アドレスを指定できます。 WSAMSG 構造体で WSASendMsg 関数に渡される制御データ・オブジェクトの 1 つに、送信に使用するローカル IPv6 ソース・アドレスを指定するために使用されるin6_pktinfo構造体が含まれている場合があります。
WSASendMsg 関数を使用してデータグラムを送信し、アプリケーションで使用する特定のローカル IP ソース アドレスを指定する場合のデュアルスタック ソケットの場合、これを処理するメソッドは宛先 IP アドレスによって異なります。 IPv4 宛先アドレスまたは IPv4 マップト IPv6 宛先アドレスに送信する場合、lpMsg パラメーターが指す WSAMSG 構造体で渡される制御データ・オブジェクトの 1 つに、送信に使用するローカル IPv4 ソース・アドレスを含むin_pktinfo構造体が含まれている必要があります。 IPv4 マップ IPv6 アドレスではない IPv6 宛先アドレスに送信する場合、lpMsg パラメーターによって指される WSAMSG 構造体で渡される制御データ・オブジェクトの 1 つに、送信に使用するローカル IPv6 ソース・アドレスを含むin6_pktinfo構造が含まれている必要があります。
dwFlags
dwFlags 入力パラメーターを使用すると、関連付けられたソケットに指定されたオプションを超えて、関数呼び出しの動作に影響を与えることができます。 つまり、この関数のセマンティクスは、ソケット オプションと dwFlags パラメーターによって決定されます。 後者は、次のいずれかの値を持つビットごとの OR 演算子を使用して構築されます。| 値 | 意味 |
|---|---|
| MSG_DONTROUTE | データをルーティングの対象にしないことを指定します。 Windows ソケット サービス プロバイダーは、このフラグを無視することを選択できます。 |
| MSG_PARTIAL | lpMsg-lpBuffers> に部分的なメッセージのみが含まれていることを指定します。 エラー コード WSAEOPNOTSUPP は、部分的なメッセージ転送をサポートしていないトランスポートによって返されることに注意してください。 |
出力では、lpMsg パラメーターが指す WSAMSG 構造体の dwFlags メンバーは使用されません。
重複するソケット I/O
重複した操作がすぐに完了すると、 WSASendMsg は 0 の値を返し、 lpNumberOfBytesSent パラメーターは送信されたバイト数で更新されます。 重複した操作が正常に開始され、後で完了する場合、 WSASendMsg は SOCKET_ERRORを返し、エラー コード WSA_IO_PENDINGを示します。 この場合、 lpNumberOfBytesSent は更新されません。 重複する操作が完了すると、転送されるデータの量は、完了ルーチンの cbTransferred パラメーター (指定されている場合) または WSAGetOverlappedResult の lpcbTransfer パラメーターを使用して示されます。重複した I/O を使用する WSASendMsg 関数は、前の 、WSARecv、WSARecvFrom、LPFN_WSARECVMSG (WSARecvMsg)、WSASend、WSASendMsg、または WSASendTo 関数の完了ルーチン内から呼び出すことができます。 これにより、時間の影響を受けるデータ転送を、プリエンプティブ コンテキスト内で完全に実行できます。
lpOverlapped パラメーターは、重複する操作の間有効である必要があります。 複数の I/O 操作が同時に未処理の場合は、それぞれが個別の WSAOVERLAPPED 構造体を参照する必要があります。
lpCompletionRoutine パラメーターが NULL の場合、重複した操作が完了すると、lpOverlapped の hEvent パラメーターに有効なイベント オブジェクト ハンドルが含まれている場合に通知されます。 アプリケーションでは 、WSAWaitForMultipleEvents または WSAGetOverlappedResult を使用して、イベント オブジェクトを待機またはポーリングできます。
lpCompletionRoutine が NULL でない場合、hEvent パラメーターは無視され、アプリケーションがコンテキスト情報を完了ルーチンに渡すために使用できます。 NULL 以外の lpCompletionRoutine を渡し、同じ重複した I/O 要求に対して WSAGetOverlappedResult を呼び出す呼び出し元は、WSAGetOverlappedResult の呼び出しに対して fWait パラメーターを TRUE に設定できません。 この場合、 hEvent パラメーターの使用は未定義であり、 hEvent パラメーターを待機しようとすると予測できない結果が生成されます。
完了ルーチンは、Windows ファイル I/O 完了ルーチンに規定されているのと同じ規則に従います。 完了ルーチンは、スレッドがアラート可能な待機状態になるまで呼び出されません。たとえば、fAlertable パラメーターを TRUE に設定して WSAWaitForMultipleEvents が呼び出されます。
トランスポート プロバイダーを使用すると、アプリケーションはソケット I/O 完了ルーチンのコンテキスト内から送受信操作を呼び出し、特定のソケットに対して I/O 完了ルーチンが入れ子になることが保証されます。 これにより、時間の影響を受けるデータ転送を、プリエンプティブ コンテキスト内で完全に実行できます。
完了ルーチンのプロトタイプは次のとおりです。
void CALLBACK CompletionRoutine(
IN DWORD dwError,
IN DWORD cbTransferred,
IN LPWSAOVERLAPPED lpOverlapped,
IN DWORD dwFlags
);
CompletionRoutine 関数は、アプリケーション定義またはライブラリ定義の関数名のプレースホルダーです。 dwError パラメーターは、lpOverlapped パラメーターで示されているように、重複する操作の完了状態を指定します。 cbTransferred パラメーターは、送信されたバイト数を示します。 現在、フラグ値は定義されておらず、 dwFlags パラメーターは 0 になります。 CompletionRoutine 関数は値を返しません。
この関数から戻って、ソケットに対して別の保留中の完了ルーチンを呼び出すことができます。 警告可能なスレッドの待機がWSA_IO_COMPLETIONの戻りコードで満たされる前に、すべての待機完了ルーチンが呼び出されます。 完了ルーチンは任意の順序で呼び出すことができます。重複する操作が完了した順序は必ずしも同じではありません。 ただし、ポストされたバッファーは、指定した順序で送信することが保証されます。
Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストア アプリでサポートされています。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8.1、Windows Vista [デスクトップ アプリ |UWP アプリ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリ | UWP アプリ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winsock2.h (Mswsock.h を含む) |
| Library | Ws2_32.lib |
| [DLL] | Ws2_32.dll |
こちらもご覧ください
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示