WSASendMsg

接続済み/非接続のソケットからデータとオプションの制御情報を送信する。注: この関数は Winsock 仕様に対する Microsoft 独自の拡張である。

WSASendMsg Handle, lpMsg, dwFlags, lpNumberOfBytesSent, lpOverlapped, lpCompletionRoutine

Handle : [int] ソケットを識別する記述子。
lpMsg : [var] Posix.1g msghdr 構造体を格納する WSAMSG 構造体。
dwFlags : [int] WSASendMsg の動作を変更するためのフラグ。詳細は備考の「Using dwFlags」を参照。
lpNumberOfBytesSent : [var] I/O 操作が即時完了した場合にこの呼び出しで送信したバイト数へのポインタ。lpOverlapped が NULL でない場合、誤った結果を避けるために本引数を NULL にする。本引数を NULL にできるのは lpOverlapped が NULL でない場合のみ。
lpOverlapped : [var] WSAOVERLAPPED 構造体へのポインタ。非オーバーラップソケットでは無視される。
lpCompletionRoutine : [int] 型: \_In_opt\_ [**LPWSAOVERLAPPED_COMPLETION_ROUTINE**](./nc-winsock2-lpwsaoverlapped_completion_routine.md) 送信操作が完了した時に呼び出される完了ルーチンへのポインタ。非オーバーラップソケットでは無視される。

(プラグイン / モジュール : ws2_32.dll)

解説

接続済み/非接続のソケットからデータとオプションの制御情報を送信する。注: この関数は Winsock 仕様に対する Microsoft
独自の拡張である。

[戻り値]

成功かつ即時完了の場合はゼロを返す。ゼロが返った場合、呼び出しスレッドがアラート可能状態になった時点で指定された完了ルーチンが呼び出される。SOCKET_ERROR
が返り、続く WSAGetLastError が WSA_IO_PENDING
を返す場合は、オーバーラップ操作が正常に開始されたことを示し、完了はイベントや完了ポートなど他の手段で通知される。失敗時は
SOCKET_ERROR が返り、WSAGetLastError は WSA_IO_PENDING
以外の値を返す。次の表はエラーコードの一覧である。
このドキュメントは省略されている。

[備考]
WSASendMsg 関数は WSASend および WSASendTo の代わりに使うことができる。WSASendMsg
はデータグラムおよび raw ソケットでのみ使える。s 引数のソケット記述子は、ソケット種別を SOCK_DGRAM または
SOCK_RAW として開いていなければならない。dwFlags 引数には次の制御フラグの組み合わせのみ指定できる:
MSG_DONTROUTE、MSG_PARTIAL、MSG_OOB。lpMsg が指す WSAMSG 構造体の dwFlags
メンバは入力時に無視され出力では使われない。
注: WSASendMsg の関数ポインタは、WSAIoctl 関数に
SIO_GET_EXTENSION_FUNCTION_POINTER オペコードを指定して実行時に取得する必要がある。WSAIoctl
に渡す入力バッファには、WSASendMsg 拡張関数を識別する GUID WSAID_WSASENDMSG を入れる。成功すれば
WSAIoctl の出力に WSASendMsg のポインタが格納される。WSAID_WSASENDMSG GUID は
Mswsock.h に定義されている。
オーバーラップソケットは WSA_FLAG_OVERLAPPED 付きで WSASocket
を呼ぶことで作成される。オーバーラップソケットでは lpOverlapped と lpCompletionRoutine の両方が
NULL でない限りオーバーラップ I/O で送信が行われる。両方が NULL
の場合は非オーバーラップソケットとして扱う。オーバーラップソケットでは、バッファが転送に消費された時点で完了ルーチンが呼ばれるかイベントオブジェクトがセットされる。操作が即時完了しない場合、最終的な完了状態は完了ルーチンまたは
WSAGetOverlappedResult で取得する。非オーバーラップソケットでは lpOverlapped と
lpCompletionRoutine は無視され、WSASendMsg は send
と同じブロッキングセマンティクスを持つ。すなわちデータはバッファからトランスポートのバッファへコピーされる。ソケットが非ブロッキングかつストリーム指向で、トランスポートのバッファ容量が不足している場合、WSASendMsg
はアプリケーションのバッファの一部のみ消費して戻る。一方、ブロッキングソケットでは全バッファが消費されるまで WSASendMsg
はブロックする。
この関数がオーバーラップ方式で完了する場合、Winsock サービスプロバイダは呼び出しから戻る前に WSABUF
構造体を取り込む責任がある。これによりアプリケーションは lpMsg が指す WSAMSG の lpBuffers にスタック上の
WSABUF 配列を指すこともできる。メッセージ指向ソケットでは、下位プロバイダの最大メッセージサイズ (SO_MAX_MSG_SIZE
ソケットオプションで取得可能)
を超えないよう注意する必要がある。データが下位プロトコルでアトミックに送信するには長すぎる場合、WSAEMSGSIZE
エラーが返り何も送信されない。
IPv4 の SOCK_DGRAM または SOCK_RAW ソケットでは、アプリケーションは WSAMSG の制御データオブジェクトに
in_pktinfo 構造体を含めて送信元 IPv4 アドレスを指定できる。IPv6 の SOCK_DGRAM または SOCK_RAW
ソケットでは、in6_pktinfo 構造体を含めて送信元 IPv6 アドレスを指定できる。デュアルスタックソケットでは、宛先 IP
に応じて方法が異なる。IPv4 宛先または IPv4 マップ IPv6 宛先に送る場合は in_pktinfo を、IPv4 マップでない
IPv6 宛先に送る場合は in6_pktinfo を使う。注: SO_SNDTIMEO
ソケットオプションはブロッキングソケットにのみ適用される。注: WSASendMsg
の成功完了は、データが正常に配信されたことを示すものではない。注: lpOverlapped を NULL にして WSASendMsg
のようなブロッキング Winsock 呼び出しを発行すると、Winsock
はネットワークイベントを待つ場合がある。この待機はアラート可能で APC で中断されうる。中断中の APC 内から別のブロッキング
Winsock 呼び出しを発行すると未定義動作となる。dwFlags
このドキュメントは省略されている。

情報