LPWSPSENDTO

LPWSPSendTo 関数は、オーバーラップ I/O を使用して特定の宛先にデータを送信します。

エラーが発生せず、操作が即座に完了した場合、LPWSPSendTo は 0 を返します。この場合、完了ルーチンが指定されていれば、それは既にキューに登録されている点に注意してください。それ以外の場合は SOCKET_ERROR が返され、具体的なエラーコードは lpErrno で取得できます。エラーコード WSA_IO_PENDING は、オーバーラップ操作が正常に開始され、完了が後で通知されることを示します。それ以外のエラーコードは、オーバーラップ操作が開始されておらず、完了通知も発生しないことを示します。

LPWSPSendTo 関数は通常、s で指定されたコネクションレスソケットで使用し、1 つ以上のバッファーに格納されたデータグラムを、lpTo パラメーターで識別される特定のピアソケットへ送信します。コネクションレスソケットが事前に LPWSPConnect 関数で特定のアドレスに接続されている場合でも、lpTo はそのデータグラムに限って宛先アドレスを上書きします。コネクション指向のソケットでは、lpTo と iToLen パラメーターは無視され、この場合 LPWSPSendTo 関数は LPWSPSend と等価です。

オーバーラップソケット (WSA_FLAG_OVERLAPPED フラグを指定して LPWSPSocket で作成されたソケット) では、この処理はオーバーラップ I/O を使用して行われます。ただし、lpOverlapped と lpCompletionRoutine の両方が NULL の場合、そのソケットは非オーバーラップソケットとして扱われます。指定されたバッファーがトランスポートによって消費されると、完了通知 (完了ルーチンの呼び出し、またはイベントオブジェクトのシグナル設定) が発生します。操作が即座に完了しない場合、最終的な完了状態は完了ルーチンまたは LPWSPGetOverlappedResult を通じて取得します。

非オーバーラップソケットでは、lpOverlapped、lpCompletionRoutine、lpThreadId の各パラメーターは無視され、LPWSPSendTo は通常の同期的なセマンティクスに従います。データは、指定されたバッファーからトランスポートのバッファーへコピーされます。ソケットが非ブロッキングかつストリーム指向で、トランスポートのバッファーに十分な空きがない場合、LPWSPSendTo は Windows Sockets SPI クライアントのバッファーの一部だけが消費された状態で戻ります。同じバッファー状況でブロッキングソケットの場合、LPWSPSendTo は Windows Sockets SPI クライアントのバッファーの内容がすべて消費されるまでブロックします。

lpBuffers パラメーターが指す WSABUF 構造体の配列は一時的なものです。この操作がオーバーラップ方式で完了する場合、この呼び出しから戻る前にこれらの WSABUF 構造体を取り込むのは、サービスプロバイダーの責任です。これにより、アプリケーションはスタック上に WSABUF の配列を構築できます。

メッセージ指向のソケットでは、基になるトランスポートの最大メッセージサイズを超えないように注意する必要があります。この値は、ソケットオプション SO_MAX_MSG_SIZE の値を取得することで得られます。データが長すぎて、基になるプロトコルでアトミックに渡せない場合は、エラー WSAEMSGSIZE が返され、データは送信されません。

LPWSPSendTo が正常に完了しても、データが正常に配信されたことを示すわけではない点に注意してください。

iFlags パラメーターを使用すると、関連付けられたソケットに指定されたオプションの範囲を超えて、この関数呼び出しの動作に影響を与えることができます。つまり、この関数のセマンティクスは、ソケットオプションと dwFlags パラメーターによって決まります。後者は、次の値をビットごとの OR 演算子で組み合わせて構成します。

オーバーラップ操作が即座に完了した場合、LPWSPSendTo は 0 を返し、lpNumberOfBytesSent パラメーターは送信されたバイト数に更新されます。オーバーラップ操作が正常に開始され、後で完了する場合、LPWSPSendTo は SOCKET_ERROR を返し、エラーコード WSA_IO_PENDING を示します。この場合、lpNumberOfBytesSent は更新されません。オーバーラップ操作が完了すると、転送されたデータ量は、完了ルーチンの cbTransferred パラメーター (指定されている場合)、または LPWSPGetOverlappedResult の lpcbTransfer パラメーターを通じて示されます。

プロバイダーは、直前の LPWSPRecv、LPWSPRecvFrom、LPWSPSend、または LPWSPSendTo 関数の完了ルーチン内から、この関数が呼び出されることを許可する必要があります。ただし、特定のソケットについて、I/O 完了ルーチンを入れ子にすることはできません。これにより、時間的制約のあるデータ送信をプリエンプティブなコンテキスト内で完結させることができます。

lpOverlapped パラメーターは、オーバーラップ操作が継続している間、有効である必要があります。複数の I/O 操作が同時に未処理の状態にある場合は、それぞれが別個のオーバーラップ構造体を参照する必要があります。WSAOverlapped 構造体は、専用のリファレンスページで定義されています。

lpCompletionRoutine パラメーターが null の場合、サービスプロバイダーは、lpOverlapped の hEvent メンバーが有効なイベントオブジェクトハンドルを保持していれば、オーバーラップ操作の完了時にそれをシグナル状態にします。Windows Sockets SPI クライアントは、LPWSPGetOverlappedResult を使用して、そのイベントオブジェクトを待機またはポーリングできます。

lpCompletionRoutine が null でない場合、hEvent メンバーは無視され、Windows Sockets SPI クライアントが完了ルーチンにコンテキスト情報を渡すために使用できます。null 以外の lpCompletionRoutine を渡したクライアントが、同じオーバーラップ I/O 要求に対して後から WSAGetOverlappedResult を呼び出す場合、その WSAGetOverlappedResult の呼び出しで fWait パラメーターを TRUE に設定することはできません。この場合、hEvent メンバーの用途は未定義であり、hEvent メンバーを待機しようとすると予測できない結果になります。

オーバーラップ操作が完了したときに、クライアントが指定した完了ルーチンが呼び出されるように手配するのは、サービスプロバイダーの責任です。完了ルーチンは、オーバーラップ操作を開始したスレッドと同じスレッドのコンテキストで実行される必要があるため、サービスプロバイダーから直接呼び出すことはできません。Ws2_32.dll は、完了ルーチンの呼び出しを容易にする非同期プロシージャ呼び出し (APC) のメカニズムを提供します。

サービスプロバイダーは、WPUQueueApc を呼び出すことで、適切なスレッドで関数が実行されるように手配します。この関数は任意のプロセスおよびスレッドのコンテキストから呼び出すことができ、オーバーラップ操作の開始に使用されたスレッドやプロセスとは異なるコンテキストからでも呼び出せます。

WPUQueueApc 関数は、入力パラメーターとして、WSATHREADID 構造体へのポインター (lpThreadId 入力パラメーターでプロバイダーに渡されたもの)、呼び出される APC 関数へのポインター、および後で APC 関数に渡されるコンテキスト値を受け取ります。利用できるコンテキスト値は 1 つだけであるため、APC 関数自体をクライアント指定の完了ルーチンにすることはできません。代わりにサービスプロバイダーは、自身の APC 関数へのポインターを指定する必要があります。その APC 関数は、渡されたコンテキスト値を使用してオーバーラップ操作に必要な結果情報にアクセスし、クライアントが指定した完了ルーチンを呼び出します。

クライアントが用意する完了ルーチンのプロトタイプは次のとおりです。

void CALLBACK 
CompletionRoutine(  
  IN DWORD           dwError, 
  IN DWORD           cbTransferred, 
  IN LPWSAOVERLAPPED lpOverlapped, 
  IN DWORD           dwFlags 
);

CompletionRoutine は、クライアントが用意する関数名のプレースホルダーです。dwError は、lpOverlapped で示されるオーバーラップ操作の完了状態を表します。cbTransferred は、送信されたバイト数を表します。現在、フラグ値は定義されておらず、dwFlags の値は 0 になります。この関数は値を返しません。

完了ルーチンは任意の順序で呼び出される可能性があり、必ずしもオーバーラップ操作が完了した順序と同じとは限りません。ただしサービスプロバイダーは、ポストされたバッファーが指定された順序どおりに送信されることをクライアントに保証します。