LPWSPSEND コールバック関数 (ws2spi.h)

LPWSPSend 関数は、接続されたソケットでデータを送信します。

構文

LPWSPSEND Lpwspsend;

int Lpwspsend(
  [in]  SOCKET s,
  [in]  LPWSABUF lpBuffers,
  [in]  DWORD dwBufferCount,
  [out] LPDWORD lpNumberOfBytesSent,
  [in]  DWORD dwFlags,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [in]  LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
  [in]  LPWSATHREADID lpThreadId,
  [out] LPINT lpErrno
)
{...}

パラメーター

[in] s

接続されているソケットを識別する記述子。

[in] lpBuffers

WSABUF 構造体の配列へのポインター。 各 WSABUF 構造体には、バッファーへのポインターとバッファーの長さ (バイト単位) が含まれます。 Winsock アプリケーションの場合、 LPWSPSend 関数が呼び出されると、システムはこれらのバッファーを所有し、アプリケーションがそれらにアクセスできない可能性があります。 各 WSABUF 構造体で参照されるデータ バッファーはシステムによって所有されており、アプリケーションが呼び出しの有効期間にわたってアクセスできない場合があります。

[in] dwBufferCount

lpBuffers 配列内の WSABUF 構造体の数。

[out] lpNumberOfBytesSent

この呼び出しによって送信されたバイト数へのポインター。

[in] dwFlags

呼び出しの方法を指定するフラグのセット。

[in] lpOverlapped

WSAOverlapped 構造体へのポインター (オーバーラップされていないソケットの場合は無視されます)。

[in] lpCompletionRoutine

種類: _In_opt_ LPWSAOVERLAPPED_COMPLETION_ROUTINE

送信操作が完了したときに呼び出される完了ルーチンへのポインター (オーバーラップされていないソケットの場合は無視されます)。

[in] lpThreadId

WPUQueueApc への後続の呼び出しでプロバイダーによって使用される WSATHREADID 構造体へのポインター。 プロバイダーは、WPUQueueApc 関数が返されるまで、参照先の WSATHREADID 構造体 (同じへのポインターではない) を格納する必要があります。

[out] lpErrno

エラー コードへのポインター。

戻り値

エラーが発生せず、送信操作がすぐに完了した場合、 LPWSPSend は 0 を返します。 この場合、完了ルーチン (指定されている場合) は既にキューに登録されていることに注意してください。 それ以外の場合は、SOCKET_ERRORの値が返され、 lpErrno で特定のエラー コードを使用できます。 エラー コード WSA_IO_PENDING は、重複した操作が正常に開始され、その完了が後で示されることを示します。 その他のエラー コードは、重複する操作が開始されておらず、完了の兆候が発生しなかったことを示します。

解説

LPWSPSend 関数は、 で指定された接続指向ソケット上の 1 つ以上のバッファーから送信データを書き込むのに使用されます。 ただし、 LPWSPConnect 関数を介して確立された既定のピア アドレスが規定されているコネクションレス ソケットでも使用できます。

重複するソケット (フラグ WSA_FLAG_OVERLAPPEDを持つ LPWSPSocket を使用して作成) の場合、 lpOverlapped と lpCompletionRoutine の両方が null でない限り、重複した I/O を使用して発生します。この場合、ソケットはオーバーラップされていないソケットとして扱われます。 指定されたバッファーがトランスポートによって使用されると、完了表示 (完了ルーチンの呼び出しまたはイベント オブジェクトの設定) が発生します。 操作がすぐに完了しない場合は、完了ルーチンまたは LPWSPGetOverlappedResult を使用して最終的な完了状態が取得されます。

オーバーラップされていないソケットの場合、パラメーター lpOverlapped、 lpCompletionRoutine、 lpThreadId は無視され、 LPWSPSend は通常の同期セマンティクスを採用します。 データは、指定されたバッファーからトランスポートのバッファーにコピーされます。 ソケットが非ブロッキングでストリーム指向で、トランスポートのバッファーに十分な領域がない場合、 LPWSPSend は、指定されたバッファーの一部のみが消費された状態でを返します。 同じバッファー状況とブロッキング ソケットを指定すると、 LPWSPSend は、指定されたすべてのバッファー コンテンツが消費されるまでブロックします。

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

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

LPWSPSend が正常に完了しても、データが正常に配信されたことは示されないことに注意してください。

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

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

プロバイダーは、前の LPWSPRecv、LPWSPRecvFrom、LPWSPSend、LPWSPSendTo 関数の完了ルーチン内からこの関数を呼び出せるようにする必要があります。 ただし、特定のソケットでは、I/O 完了ルーチンを入れ子にすることはできません。 これにより、時間の影響を受けるデータ転送を、プリエンプティブ コンテキスト内で完全に実行できます。

lpOverlapped パラメーターは、重複する操作の間有効である必要があります。 複数の I/O 操作が同時に未処理の場合は、それぞれが個別の重複した構造を参照する必要があります。 WSAOverlapped 構造体は、独自の参照ページで定義されます。

lpCompletionRoutine パラメーターが null の場合、有効なイベント オブジェクト ハンドルが含まれている場合、重複した操作が完了すると、サービス プロバイダーは lpOverlapped の hEvent メンバーに通知します。 Windows ソケット SPI クライアントは 、LPWSPGetOverlappedResult を使用して、イベント オブジェクトを待機またはポーリングできます。

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

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

サービス プロバイダーは、 WPUQueueApc を呼び出すことによって、適切なスレッドで実行される関数を配置します。 この関数は、重複した操作を開始するために使用されたのと同じプロセス (ただし、必ずしも同じスレッドではない) のコンテキストで呼び出す必要があることに注意してください。 WPUQueueApc を呼び出す前に、このプロセス コンテキストがアクティブになるように調整するのはサービス プロバイダーの責任です。

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

クライアント提供の完了ルーチンのプロトタイプは次のとおりです。

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

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

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

要件

関連項目

WPUQueueApc

LPWSPGetOverlappedResult

LPWSPSocket