TransmitFile 函式 (mswsock.h)

發行項
02/29/2024

TransmitFile 函式會透過連接的套接字句柄傳輸檔案數據。此函式會使用作業系統的快取管理員來擷取檔案數據，並透過套接字提供高效能的檔案數據傳輸。

注意此函式是 Windows Sockets 規格的 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 函式已傳送指定的位元元組數目，或發生錯誤時，會先完成該函式。

將此參數設定為零，以便傳輸整個檔案。

nNumberOfBytesPerSend

每個傳送作業中傳送之每個數據區塊的大小，以位元組為單位。 Windows 套接字層會使用此參數來判斷傳送作業的區塊大小。若要選取預設傳送大小，請將此參數設定為零。

nNumberOfBytesPerSend 參數適用於具有個別傳送要求大小限制的通訊協定。

lpOverlapped

重疊結構的指標。如果套接字句柄已開啟為重疊，請指定此參數，以達到重疊 (異步) I/O 作業。根據預設，套接字句柄會以重疊方式開啟。

您可以使用 lpOverlapped 參數，藉由設定 OVERLAPPED 結構的 Offset 和 OffsetHigh 成員，在檔案內指定 64 位位移，以啟動檔案數據傳輸。如果 lpOverlapped 是 NULL 指標，則數據傳輸一律會從檔案中的目前位元組位移開始。

當 lpOverlapped 不是 NULL 時，重疊的 I/O 可能不會在 TransmitFile 傳回之前完成。在此情況下， TransmitFile 函式會傳回 FALSE，而 WSAGetLastError 會傳回 ERROR_IO_PENDING 或 WSA_IO_PENDING。這可讓呼叫端在檔案傳輸作業完成時繼續處理。 Windows 會在完成數據傳輸要求時，將重疊結構的 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	指示 Windows Sockets 服務提供者使用系統的預設線程來處理長 TransmitFile 要求。您可以使用下列登入參數作為 REG_DWORD來調整系統預設線程： \ HKEY_LOCAL_MACHINECurrentControlSet\服務\漁農處\參數\TransmitWorker
TF_USE_SYSTEM_THREAD	指示 Windows Sockets 服務提供者使用系統線程來處理長 TransmitFile 要求。
TF_USE_KERNEL_APC	指示驅動程式使用核心異步過程調用 (API) ，而不是背景工作線程來處理長 TransmitFile 要求。 Long TransmitFile 要求會定義為要求需要多個從檔案或快取讀取的要求;因此，要求取決於檔案的大小和傳送封包的指定長度。使用TF_USE_KERNEL_APC可提供顯著的效能優勢。不過，雖然不太可能) (，但是起始 Context TransmitFile 的線程會用於大量計算;這種情況可能會防止 APC 啟動。請注意，Winsock 核心模式驅動程式會使用一般核心 APC，每當線程處於等候狀態時啟動，這與使用者模式 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。

傳回碼	Description
WSAECONNABORTED	您主機機器中的軟體已中止建立的連接。如果虛擬線路因逾時或其他失敗而終止，則會傳回此錯誤。
WSAECONNRESET	遠端主機已強制關閉一個現有連線。當遠端重設虛擬線路時，數據流套接字會傳回此錯誤。此通訊端無法再使用，應用程式應予以關閉。
WSAEFAULT	系統在嘗試在呼叫中使用指標自變數時偵測到無效的指標位址。如果 lpTransmitBuffers 或 lpOverlapped 參數未完全包含在使用者位址空間的有效部分，就會傳回此錯誤。
WSAEINVAL	提供的引數無效。如果 hSocket 參數指定類型為 SOCK_DGRAM 或 SOCK_RAW 的套接字，就會傳回此錯誤。如果 dwFlags 參數已設定 TF_REUSE_SOCKET 旗標，但未設定 TF_DISCONNECT 旗標，則會傳回此錯誤。如果 lpOverlapped 所指向之重疊結構中指定的位移不在檔案內，也會傳回此錯誤。如果 nNumberOfBytesToWrite 參數設定為大於 2,147,483,646 的值，則也會傳回此錯誤，這是 32 位整數減 1 的最大值。
WSAENETDOWN	套接字作業發生死網路。如果網路子系統失敗，就會傳回此錯誤。
WSAENETRESET	線上已中斷，因為持續運作活動偵測作業正在進行時失敗。
WSAENOBUFS	無法執行套接字上的作業，因為系統沒有足夠的緩衝區空間或佇列已滿。如果 Windows Sockets 提供者回報緩衝區死結，也會傳回此錯誤。
WSAENOTCONN	因為套接字未連線，所以不允許傳送或接收數據的要求。
WSAENOTSOCK	嘗試在不是套接字的內容上執行作業。如果 hSocket 參數不是套接字，則會傳回此錯誤。
WSAESHUTDOWN	因為先前的關閉呼叫已將該方向的通訊端關閉，所以不允許傳送或接收資料的要求。如果套接字已關閉以供傳送，則會傳回此錯誤。在套接字上呼叫 shutdown 函式之後，無法在套接字上呼叫 TransmitFile，並將參數設定為SD_SEND 或 SD_BOTH。
WSANOTINITIALISED	應用程式尚未呼叫 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 函式的單一呼叫傳輸的最大位元元組數目為 2,147,483,646,32 位整數的最大值減 1。在單一呼叫中傳送的最大位元元組數包括 lpTransmitBuffers 參數指向之檔案數據之前或之後傳送的任何數據，以及 nNumberOfBytesToWrite 參數中指定的值，以傳送檔案數據長度。如果應用程式需要傳輸大於 2,147,483,646 個字節的檔案，則 對 TransmitFile 函式的多個呼叫可以搭配傳輸不超過 2,147,483,646 個字節的每個呼叫使用。將大於 2,147,483,646 個字節的檔案將 nNumberOfBytesToWrite 參數設定為零，也會失敗，因為在此案例中 ，TransmitFile 函式會使用檔案的大小做為要傳輸位元組數的值。

注意若要在運行時間取得 TransmitFile 函式的函式指標，您必須呼叫 WSAIoctl 函式並指定 SIO_GET_EXTENSION_FUNCTION_POINTER opcode。傳遞至 WSAIoctl 函式的輸入緩衝區必須包含 WSAID_TRANSMITFILE，這是全域唯一標識碼 (GUID) ，其值會識別 TransmitFile 擴充函式。成功時， WSAIoctl 函式傳回的輸出會包含 TransmitFile 函式的指標。 WSAID_TRANSMITFILE GUID 定義於 Mswsock.h 頭檔中。

注意TransmitFile 無法在執行自己的緩衝處理的傳輸上運作。具有TDI_SERVICE_INTERNAL_BUFFERING旗標集的傳輸，例如ADSP，會執行自己的緩衝處理。因為 TransmitFile 會透過直接從檔案快取傳送數據來達到其效能提升。在特定連線上用盡緩衝區空間的傳輸不會由 TransmitFile 處理，而且因為連線上的緩衝區空間不足， TransmitFile 會傳回STATUS_DEVICE_NOT_READY。

TransmitFile 函式主要是新增至 Winsock，以供高效能伺服器應用程式 (Web 和 ftp 伺服器使用，例如) 。

工作站和用戶端版本的 Windows 會藉由限制系統上允許的並行 TransmitFile 作業數目，將 TransmitFile 函式優化以達到最小記憶體和資源使用率。在 Windows Vista、Windows XP、Windows 2000 Professional 和 Windows NT Workstation 3.51 和更新版本上，只會同時處理兩個未處理的 TransmitFile 要求;第三個要求會等到先前的其中一個要求完成為止。

伺服器版本的 Windows 會將 TransmitFile 函式優化，以達到高效能。在伺服器版本上，系統允許的並行 TransmitFile 作業數目沒有預設限制。在 Windows 的伺服器版本上使用 TransmitFile 時，預期會有更好的效能結果。在 Windows 的伺服器版本上，您可以建立登錄項目並設定下列REG_DWORD的值，來設定並行 TransmitFile 作業數目上限的限制：

\ HKEY_LOCAL_MACHINECurrentControlSet\服務\漁農處\參數\MaxActiveTransmitFileCount

如果使用 TCP 套接字 (通訊協定呼叫 TransmitFile 函式，IPPROTO_TCP) 并同时指定 TF_DISCONNECT 和 TF_REUSE_SOCKET 旗標，則呼叫將不會完成，直到符合下列兩個條件為止。

從 TCP 套接字上從遠端) 收到 FIN 之前，遠端 (所傳送的所有擱置接收數據。
遠端端已關閉連線， (已完成正常 TCP 連線關閉) 。

如果在將 lpOverlapped 參數設為 NULL 的情況下呼叫 TransmitFile 函式，作業會以同步 I/O 執行。函式在傳送檔案之前不會完成。

Windows Phone 8：Windows Phone 8 和更新版本上的 Windows Phone Store 應用程式支援此函式。

Windows 8.1 和 Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更新版本上的 Windows 市集應用程式支援此函式。

QoS 的注意事項

TransmitFile 函式允許在傳輸檔案之後，將套接字傳回「已中斷連線、可重複使用」狀態的兩個旗標TF_DISCONNECT或TF_REUSE_SOCKET。這些旗標不應該用於要求服務品質的套接字上，因為服務提供者可能會在文件傳輸完成之前立即刪除與套接字相關聯的任何服務品質。啟用 QoS 的套接字最佳方法是在文件傳輸完成時呼叫 closesocket 函式，而不是依賴這些旗標。

規格需求

需求	值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	mswsock.h (包含 Mswsock.h)
程式庫	Mswsock.lib
Dll	Mswsock.dll