LPFN_TRANSMITPACKETS コールバック関数 (mswsock.h)

[アーティクル]
08/25/2023

TransmitPackets 関数は、接続されたソケット経由でメモリ内データまたはファイルデータを送信します。 TransmitPackets 関数は、オペレーティングシステムキャッシュマネージャーを使用してファイルデータを取得し、送信に必要な最小時間のメモリをロックし、効率的で高性能な転送を実現します。

メモこの関数は、Windows ソケット仕様に対する Microsoft 固有の拡張機能です。

構文

LPFN_TRANSMITPACKETS LpfnTransmitpackets;

BOOL LpfnTransmitpackets(
  SOCKET hSocket,
  LPTRANSMIT_PACKETS_ELEMENT lpPacketArray,
  DWORD nElementCount,
  DWORD nSendSize,
  LPOVERLAPPED lpOverlapped,
  DWORD dwFlags
)
{...}

パラメーター

hSocket

伝送で使用される接続ソケットへのハンドル。ソケットは接続指向回線である必要はありませんが、接続、WSAConnect 、accept、WSAAccept、AcceptEx、または WSAJoinLeaf 関数を使用して、既定の宛先/ピアが確立されている必要があります。

lpPacketArray

TRANSMIT_PACKETS_ELEMENT 型の配列。送信するデータを記述します。

nElementCount

lpPacketArray 内の要素の数。

nSendSize

送信操作で使用されるデータブロックのサイズ (バイト単位)。ソケットレイヤーが既定の送信サイズを選択できるようにするには、nSendSize を 0 に設定します。

nSendSize を 0xFFFFFFF に設定すると、呼び出し元は lpPacketArray パラメーターで指すTRANSMIT_PACKETS_ELEMENT配列の TP_ELEMENT_EOP フラグを使用して、各送信要求のサイズと内容を制御できます。この機能は、個々の送信要求のサイズに制限を設けたメッセージプロトコルに役立ちます。

lpOverlapped

OVERLAPPED 構造体へのポインター。 hSocket パラメーターで指定されたソケットハンドルが重複して開かれている場合は、このパラメーターを使用して非同期 (重複) I/O 操作を実現します。ソケットハンドルは、既定で重複して開かれます。

dwFlags

TransmitPackets 関数の処理をカスタマイズするために使用されるフラグのセット。次の表は、 dwFlags パラメーターの使用方法の概要を示しています。

値	意味
TF_DISCONNECT	転送のためにすべてのファイルデータがキューに入った後、トランスポートレベルの切断を開始します。接続指向ソケットにのみ適用されます。切断セマンティクス (データグラムソケットなど) をサポートしていないソケットに対してこのフラグを指定すると、エラーが発生します。
TF_REUSE_SOCKET	再利用するソケットハンドルを準備します。 TransmitPackets 関数が完了すると、ソケットハンドルを AcceptEx 関数に渡すことができます。接続指向のソケットとTF_DISCONNECTが指定されている場合にのみ有効です。メモソケットレベルのパケット送信は、基になるトランスポートの動作の影響を受ける。たとえば、TCP ソケットは TCP TIME_WAIT状態の影響を受け、 TransmitPackets 呼び出しが遅延する可能性があります。
TF_USE_DEFAULT_WORKER	システムの既定のスレッドを使用して、長い TransmitPackets 要求を処理するように Winsock に指示します。 Long TransmitPackets 要求は、ファイルまたはキャッシュからの 1 つ以上の読み取りを必要とする要求として定義されます。したがって、長い要求定義は、ファイルのサイズと送信パケットの指定された長さによって異なります。システムの既定のスレッドは、次のレジストリパラメーターを REG_DWORD:HKEY_LOCAL_MACHINE\CurrentControlSet\Services\AFD\パラメーター\TransmitWorker として使用して調整できます
TF_USE_SYSTEM_THREAD	システムスレッドを使用して長い TransmitPackets 要求を処理するように Winsock に指示します。 Long TransmitPackets 要求は、ファイルまたはキャッシュからの 1 つ以上の読み取りを必要とする要求として定義されます。したがって、長い要求定義は、ファイルのサイズと送信パケットの指定された長さによって異なります。
TF_USE_KERNEL_APC	ワーカースレッドではなくカーネル非同期プロシージャ呼び出し (APC) を使用して、長い TransmitPackets 要求を処理するように Winsock に指示します。 Long TransmitPackets 要求は、ファイルまたはキャッシュからの 1 つ以上の読み取りを必要とする要求として定義されます。したがって、長い要求定義は、ファイルのサイズと送信パケットの指定された長さによって異なります。詳細については、「解説」を参照してください。

戻り値

TransmitPackets 関数が成功した場合、戻り値は TRUE になります。それ以外の場合、戻り値は FALSE です。拡張エラー情報を取得するには、 WSAGetLastError を呼び出します。 WSA_IO_PENDINGまたはERROR_IO_PENDINGのエラーコードは、重複した操作が正常に開始され、完了が後で示されることを示します。その他のエラーコードは、重複した操作が正常に開始されず、完了の兆候が発生しないことを示します。この場合、アプリケーションはERROR_IO_PENDINGまたはWSA_IO_PENDINGを処理する必要があります。

リターンコード	説明
WSAECONNABORTED	確立された接続がホストコンピューターのソウトウェアによって中止されました。このエラーは、タイムアウトまたはその他の障害が原因で仮想回線が終了した場合に返されます。
WSAECONNRESET	リモートホストによって、既存の接続は強制的に切断されました。このエラーは、仮想回線がリモート側でリセットされたときに、ストリームソケットに対して返されます。ソケットが使用できないため、アプリケーションはソケットを閉じる必要があります。
WSAEFAULT	呼び出しでポインター引数を使用しようとしたときに、システムにより、無効なポインターアドレスが検出されました。 lpPacketArray パラメーターまたは lpOverlapped パラメーターがユーザーアドレス空間の有効な部分に完全に含まれていない場合、このエラーが返されます。
WSAEINVAL	無効な引数が指定されました。 dwFlags パラメーターに TF_REUSE_SOCKET フラグが設定されていても、TF_DISCONNECT フラグが設定されていない場合、このエラーが返されます。このエラーは、lpOverlapped が指す OVERLAPPED 構造体で指定されたオフセットがファイル内にない場合にも返されます。このエラーは、送信される合計バイト数が 2,147,483,646 を超える値で、32 ビット整数から 1 を引いた最大値である場合にも返されます。
WSAENETDOWN	ソケット操作で、ネットワークが停止しました。このエラーは、ネットワークサブシステムが失敗した場合に返されます。
WSAENETRESET	操作の実行中にキープアライブ動作によってエラーが検出されたため、接続が切断されました。このエラーは、障害を検出するキープアライブアクティビティが原因で接続が切断されたストリームソケットに対して返されます。
WSAENOBUFS	システムに十分なバッファー領域がないか、キューがいっぱいであるため、ソケットに対する操作を実行できませんでした。このエラーは、Windows ソケットプロバイダーがバッファーデッドロックを報告した場合にも返されます。
WSAENOTCONN	ソケットが接続されていないため、データの送受信要求が許可されませんでした。ストリームソケットに対してこのエラーが返されます。
WSAENOTSOCK	ソケットではないものに対して操作が試行されました。このエラーは、 hSocket パラメーターがソケットでない場合に返されます。
WSAESHUTDOWN	ソケットが以前のシャットダウンの呼び出しでシャットダウンされているため、データの送受信を要求することは禁じられています。このエラーは、ストリームソケットが送信用にシャットダウンされている場合に返されます。 shutdown 関数がソケットで呼び出された後、パラメーターをSD_SEND または SD_BOTH に設定した場合、ストリームソケットで TransmitFile を呼び出すことはできません。
WSANOTINITIALIZED	アプリケーションが WSAStartup 関数を呼び出していないか、 WSAStartup に失敗しました。 TransmitFile 関数を使用する前に、WSAStartup 呼び出しが正常に行われる必要があります。
WSA_IO_PENDING	重複した I/O 操作が進行中です。この値は、重複した I/O 操作が正常に開始され、完了が後で示されることを示す場合に返されます。
WSA_OPERATION_ABORTED	スレッドの終了またはアプリケーションの要求が原因で、I/O 操作が中止されました。このエラーは、ソケットのクローズ、 WSAIoctl での "SIO_FLUSH" コマンドの実行、または操作が完了する前に重複した要求を開始したスレッドが終了したために、重複した操作が取り消された場合に返されます。メモ特定のスレッドによって開始されたすべての I/O は、そのスレッドが終了すると取り消されます。重複するソケットの場合、非同期操作が完了する前にスレッドが閉じられた場合、保留中の非同期操作が失敗する可能性があります。詳細については、「 ExitThread」を参照してください。

注釈

TransmitPackets 関数は、使用されているオペレーティングシステムに応じて最適化されます。

Windows サーバーエディションでは、 TransmitPackets 関数はハイパフォーマンス用に最適化されています。
Windows クライアントエディションでは、 TransmitPackets 関数はメモリとリソースの使用率を最小限に抑える目的で最適化されています。

TransmitPackets 関数の 1 回の呼び出しを使用して送信できる最大バイト数は 2,147,483,646 で、32 ビット整数の最大値から 1 を引いた値です。アプリケーションが 2,147,483,646 バイトを超えるデータを送信する必要がある場合は、 TransmitPackets 関数への複数の呼び出しを、2,147,483,646 バイト以下で転送する各呼び出しで使用できます。

メモTransmitPackets 関数の関数ポインターは、実行時に、指定されたSIO_GET_EXTENSION_FUNCTION_POINTERオペコードを使用して WSAIoctl 関数を呼び出すことによって取得する必要があります。 WSAIoctl 関数に渡される入力バッファーには、TransmitPackets 拡張関数を識別する値を持つグローバル一意識別子 (GUID) WSAID_TRANSMITPACKETSが含まれている必要があります。成功すると、 WSAIoctl 関数によって返される出力には 、TransmitPackets 関数へのポインターが含まれます。 WSAID_TRANSMITPACKETS GUID は、Mswsock.h ヘッダーファイルで定義されています。

Windows Server 2003 で TransmitPackets 関数を使用する場合は、パフォーマンスの向上が期待できます。

lpOverlapped が NULL でない場合、TransmitPackets 関数が戻る前に、重複した I/O が終了しない可能性があります。これが発生した場合、 TransmitPackets 関数はを返し、 WSAGetLastError 関数の呼び出しはERROR_IO_PENDINGを返し、転送の完了時に呼び出し元が処理を続行できるようにします。

メモ特定のスレッドによって開始されたすべての I/O は、そのスレッドが終了すると取り消されます。重複するソケットの場合、保留中の非同期操作は、操作が完了する前にスレッドが閉じられた場合に失敗する可能性があります。詳細については、「 ExitThread 」を参照してください。

TransmitPackets 関数が TRUE を返すか、FALSE を返し、WSAGetLastError がERROR_IO_PENDINGを返すと、Windows は、OVERLAPPED 構造体の hEvent メンバーまたは hSocket で指定されたソケットによって指定されたイベントをシグナル状態に設定し、完了すると、ソケットに関連付けられているすべての完了ポートに通知を配信します。最終的な状態と送信バイト数を取得するには、 GetOverlappedResult、 WSAGetOverlappedResult、または GetQueuedCompletionStatus を使用します。

TransmitPackets と非同期プロシージャ呼び出し (APC)

TF_USE_KERNEL_APC フラグを使用すると、パフォーマンスに大きな利点があります。 TransmitPackets 関数呼び出しを開始するスレッドが大量の計算に使用されている場合、APC の起動を妨げる可能性はほとんどありません。

メモカーネルとユーザーモードの APC には違いがあります。

カーネル API は、スレッドが待機状態のときに起動します。
ユーザーモードの APC は、スレッドがアラート可能な待機状態のときに起動します。

Windows Phone 8: この関数は、Windows Phone 8 以降の Windows Phone ストアアプリでサポートされています。

Windows 8.1とWindows Server 2012 R2: この関数は、Windows 8.1、Windows Server 2012 R2 以降の Windows ストアアプリでサポートされています。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1、Windows Vista [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows Server 2003 [デスクトップアプリのみ \| UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	mswsock.h