TransmitFile 関数 (mswsock.h)

  • [アーティクル]

TransmitFile 関数は、接続されているソケット ハンドル経由でファイル データを送信します。 この関数は、オペレーティング システムのキャッシュ マネージャーを使用してファイル データを取得し、ソケット経由で高パフォーマンスのファイル データ転送を提供します。

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

 

構文

BOOL TransmitFile(
  SOCKET                  hSocket,
  HANDLE                  hFile,
  DWORD                   nNumberOfBytesToWrite,
  DWORD                   nNumberOfBytesPerSend,
  LPOVERLAPPED            lpOverlapped,
  LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
  DWORD                   dwReserved
);

パラメーター

hSocket

接続されているソケットへのハンドル。 TransmitFile 関数は、このソケット経由でファイル データを送信します。 hSocket パラメーターで指定するソケットは、SOCK_STREAM、SOCK_SEQPACKET、またはSOCK_RDM型の接続指向ソケットである必要があります。

hFile

TransmitFile 関数が送信する開いているファイルへのハンドル。 オペレーティング システムはファイル データを順番に読み取るので、FILE_FLAG_SEQUENTIAL_SCANを使用してハンドルを開くことでキャッシュパフォーマンスを向上させることができます。

hFile パラメーターは省略可能です。 hFile パラメーターが NULL の場合は、ヘッダーまたは末尾バッファー内のデータのみが送信されます。 ソケットの切断や再利用などの追加アクションは、 dwFlags パラメーターで指定されたとおりに実行されます。

nNumberOfBytesToWrite

送信するファイル内のバイト数。 TransmitFile 関数は、指定したバイト数を送信したとき、またはエラーが発生したときに完了します。どちらか早い方が発生します。

ファイル全体を送信するには、このパラメーターを 0 に設定します。

nNumberOfBytesPerSend

各送信操作で送信されるデータの各ブロックのサイズ (バイト単位)。 このパラメーターは、送信操作のブロック サイズを決定するために、Windows のソケット レイヤーで使用されます。 既定の送信サイズを選択するには、このパラメーターを 0 に設定します。

nNumberOfBytesPerSend パラメーターは、個々の送信要求のサイズに制限があるプロトコルに役立ちます。

lpOverlapped

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

lpOverlapped パラメーターを使用すると、OVERLAPPED 構造体の Offset メンバーと OffsetHigh メンバーを設定することで、ファイル内でファイル データ転送を開始する 64 ビット オフセットを指定できます。 lpOverlapped が NULL ポインターの場合、データの転送は常にファイル内の現在のバイト オフセットから開始されます。

lpOverlapped が NULL でない場合、TransmitFile が返される前に、重複した I/O が終了しない可能性があります。 その場合、 TransmitFile 関数は FALSE を返し、 WSAGetLastError は ERROR_IO_PENDINGまたは WSA_IO_PENDINGを返します。 これにより、ファイル転送操作の完了時に呼び出し元が処理を続行できます。 Windows は、OVERLAPPED 構造体の hEvent メンバー、または hSocket で指定されたソケットで指定されたイベントを、データ転送要求の完了時にシグナル状態に設定します。

lpTransmitBuffers

ファイル データの送信前と送信後に送信するデータへのポインターを含む、 TRANSMIT_FILE_BUFFERS データ構造体へのポインター。 ファイル データのみを送信する場合は、このパラメーターを NULL ポインターに設定する必要があります。

dwReserved

TransmitFile 関数呼び出しの動作を変更するために使用されるフラグのセット。 dwFlags パラメーターには、Mswsock.h ヘッダー ファイルで定義されている次のオプションの組み合わせを含めることができます。

フラグ 説明
TF_DISCONNECT
 すべてのファイル データが伝送キューに置かれた後で、トランスポート レベルの接続解除を開始します。
TF_REUSE_SOCKET
 再利用するソケット ハンドルを準備します。 このフラグは、 TF_DISCONNECT も指定されている場合にのみ有効です。

TransmitFile 要求が完了すると、AcceptEx や ConnectEx などの接続を確立するために以前に使用した関数呼び出しにソケット ハンドルを渡すことができます。 このような再利用は相互に排他的です。たとえば、ソケットに対して AcceptEx 関数が呼び出された場合、再利用は AcceptEx 関数の後続の呼び出しに対してのみ許可され、 ConnectEx の後続の呼び出しでは許可されません。

メモ ソケット レベルのファイル送信は、基になるトランスポートの動作に従います。 たとえば、TCP ソケットは TCP TIME_WAIT状態の影響を受け、 TransmitFile 呼び出しが遅延する可能性があります。
 
TF_USE_DEFAULT_WORKER
 システムの既定のスレッドを使用して長い TransmitFile 要求を処理するように Windows ソケット サービス プロバイダーに指示します。 システムの既定のスレッドは、次のレジストリ パラメーターを REG_DWORDとして使用して調整できます。

Hkey_local_machine\CurrentControlSet\サービス\Afd\パラメーター\TransmitWorker
TF_USE_SYSTEM_THREAD
 システム スレッドを使用して長い TransmitFile 要求を処理するように Windows ソケット サービス プロバイダーに指示します。
TF_USE_KERNEL_APC
 ドライバーに、ワーカー スレッドではなくカーネル非同期プロシージャ 呼び出し (APC) を使用して、長い TransmitFile 要求を処理するように指示します。 Long TransmitFile 要求は、ファイルまたはキャッシュからの 1 つ以上の読み取りを必要とする要求として定義されます。したがって、要求はファイルのサイズと送信パケットの指定された長さに依存します。

TF_USE_KERNEL_APCを使用すると、パフォーマンス上の大きな利点が得られます。 ただし、コンテキスト TransmitFile が開始されるスレッドが大量の計算に使用されている可能性があります (ただし、可能性は低くなります)。この状況により、APCs の起動が妨げられる可能性があります。 Winsock カーネル モード ドライバーは、通常のカーネル APCs を使用します。これは、スレッドが待機状態のときに起動します。これは、ユーザー モードの APC とは異なり、ユーザー モードで開始されたアラート可能な待機状態のときに起動します)。
TF_WRITE_BEHIND
 TransmitFile 要求は、保留中なしですぐに完了します。 このフラグが指定され、 TransmitFile が成功した場合、データはシステムによって受け入れられますが、必ずしもリモート側で確認されるとは限りません。 この設定は、TF_DISCONNECTフラグとTF_REUSE_SOCKETフラグでは使用しないでください。
メモ 送信されるファイルがファイル システム キャッシュにない場合、要求は実行されます。
 

戻り値

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

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

注釈

TransmitFile 関数は、オペレーティング システムのキャッシュ マネージャーを使用してファイル データを取得し、ソケット経由で高パフォーマンスのファイル データ転送を提供します。

TransmitFile 関数は、SOCK_STREAM、SOCK_SEQPACKET、SOCK_RDM型の接続指向ソケットのみをサポートします。 SOCK_DGRAM 型とSOCK_RAW型のソケットはサポートされていません。 TransmitPackets 関数は、SOCK_DGRAM型のソケットで使用できます。

TransmitFile 関数の 1 回の呼び出しを使用して送信できる最大バイト数は 2,147,483,646 で、32 ビット整数の最大値から 1 を引いた値です。 1 回の呼び出しで送信する最大バイト数には、 lpTransmitBuffers パラメーターが指すファイル データの前後に送信されたデータと、送信するファイル データの長さについて nNumberOfBytesToWrite パラメーターで指定された値が含まれます。 アプリケーションが 2,147,483,646 バイトを超えるファイルを送信する必要がある場合は、 TransmitFile 関数への複数の呼び出しを、2,147,483,646 バイト以下で転送する各呼び出しで使用できます。 2,147,483,646 バイトを超えるファイルに対して nNumberOfBytesToWrite パラメーターを 0 に設定しても失敗します。この場合、 TransmitFile 関数は送信するバイト数の値としてファイルのサイズを使用するため、失敗します。

メモTransmitFile 関数の関数ポインターは、実行時に、指定されたSIO_GET_EXTENSION_FUNCTION_POINTERオペコードを使用して WSAIoctl 関数を呼び出すことによって取得する必要があります。 WSAIoctl 関数に渡される入力バッファーには、TransmitFile 拡張関数を識別する値を持つグローバル一意識別子 (GUID) WSAID_TRANSMITFILEが含まれている必要があります。 成功すると、 WSAIoctl 関数によって返される出力には 、TransmitFile 関数へのポインターが含まれます。 WSAID_TRANSMITFILE GUID は、Mswsock.h ヘッダー ファイルで定義されています。
 
メモTransmitFile は、独自のバッファリングを実行するトランスポートでは機能しません。 ADSP など、TDI_SERVICE_INTERNAL_BUFFERING フラグが設定されたトランスポートは、独自のバッファリングを実行します。 TransmitFile は、ファイル キャッシュから直接データを送信することでパフォーマンスを向上させます。 特定の接続でバッファー領域を使い果たしたトランスポートは TransmitFile によって処理されず、接続のバッファー領域が不足した結果、 TransmitFile はSTATUS_DEVICE_NOT_READYを返します。
 
TransmitFile 関数は、主に、ハイ パフォーマンス サーバー アプリケーション (Web サーバーや ftp サーバーなど) で使用するために Winsock に追加されました。

ワークステーションとクライアントバージョンの Windows では、システムで許可される TransmitFile の同時実行操作の数を最大 2 に制限することで、メモリとリソースの使用率を最小限に抑えるために TransmitFile 関数が最適化されます。 Windows Vista、Windows XP、Windows 2000 Professional、および Windows NT Workstation 3.51 以降では、2 つの未処理の TransmitFile 要求のみが同時に処理されます。3 番目の要求は、前の要求のいずれかが完了するまで待機します。

Windows のサーバー バージョンでは、高パフォーマンスのために TransmitFile 関数が最適化されます。 サーバー バージョンでは、システムで許可される TransmitFile の同時実行操作の数に既定の制限はありません。 サーバー バージョンの Windows で TransmitFile を使用する場合は、パフォーマンスの向上が期待されます。 Windows のサーバー バージョンでは、レジストリ エントリを作成し、次のREG_DWORDの値を設定することで、同時実行 TransmitFile 操作の最大数に制限を設定できます。

Hkey_local_machine\CurrentControlSet\サービス\Afd\パラメーター\MaxActiveTransmitFileCount

TransmitFile 関数が TCP ソケット (IPPROTO_TCPのプロトコル) で呼び出され、TF_DISCONNECTフラグとTF_REUSE_SOCKETフラグの両方が指定されている場合、次の 2 つの条件が満たされるまで呼び出しは完了しません。

  • TCP ソケット上のリモート側 (リモート側から FIN の前に受信) によって送信されたすべての保留中の受信データが読み取られます。
  • リモート側で接続が閉じられました (正常な TCP 接続のクローズが完了しました)。

lpOverlapped パラメーターを NULL に設定して TransmitFile 関数を呼び出すと、操作は同期 I/O として実行されます。 関数は、ファイルが送信されるまで完了しません。

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

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

QoS に関する注意事項

TransmitFile 関数を使用すると、TF_DISCONNECTまたはTF_REUSE_SOCKETの 2 つのフラグを設定して、ファイルの送信後にソケットを "切断された再利用可能な" 状態に戻すことができます。 サービス プロバイダーは、ファイル転送が完了する前にソケットに関連付けられているサービスの品質を直ちに削除できるため、これらのフラグは、サービスの品質が要求されているソケットでは使用しないでください。 QoS 対応ソケットの最適な方法は、これらのフラグに依存するのではなく、ファイル転送が完了したときに closesocket 関数を呼び出すだけです。

要件

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

こちらもご覧ください

ExitThread

OVERLAPPED

TRANSMIT_FILE_BUFFERS

TransmitPackets

WSASend

closesocket