TransmitFile 函式 (winsock.h)

發行項
03/13/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 時， 在 TransmitFile 傳回之前，重疊的 I/O 可能不會完成。在此情況下， 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	指示驅動程式使用核心異步過程調用 (APC) ，而不是背景工作線程來處理長時間的 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	因為先前的關閉呼叫已將該方向的通訊端關閉，所以不允許傳送或接收資料的要求。如果套接字已關閉以傳送，就會傳回此錯誤。在套接字上呼叫關機函式之後，無法使用參數設定為 SD_SEND 或 SD_BOTH，在套接字上呼叫 TransmitFile。
WSANOTINITIALISED	應用程式尚未呼叫 WSAStartup 函式，或 WSAStartup 失敗。使用 TransmitFile 函式之前，必須先進行成功的 WSAStartup 呼叫。
WSA_IO_PENDING	正在進行重疊的 I/O 作業。如果已成功起始重疊的 I/O 作業，則會傳回這個值，並指出稍後將會指出完成。
WSA_OPERATION_ABORTED	由於執行緒結束或應用程式的要求，因此已經中止 I/O 作業。如果因為套接字關閉而取消重疊的作業、 WSAIoctl 中的「SIO_FLUSH」命令執行，或起始重疊要求的線程在作業完成之前結束，就會傳回此錯誤。注意當該線程結束時，由指定線程起始的所有 I/O 都會取消。對於重疊的套接字，如果線程在異步操作完成之前關閉，擱置的異步操作可能會失敗。如需詳細資訊，請參閱 ExitThread。

備註

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

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 頭檔中。

注意TransportFile 無法在執行自己緩衝的傳輸上運作。具有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 工作站 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 連線關閉) 。

如果使用設定為 NULL 的 lpOverlapped 參數呼叫 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，將套接字傳回至檔案傳輸之後的「已中斷連線、可重複使用」狀態。這些旗標不應用於要求服務品質的套接字上，因為服務提供者可能會在文件傳輸完成之前立即刪除與套接字相關聯的任何服務品質。啟用 QoS 的套接字最佳方法是在檔案傳輸完成時直接呼叫 closesocket 函式，而不是依賴這些旗標。

規格需求

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