LPFN_TRANSMITPACKETS回呼函式 (mswsock.h)

TransmitPackets 函式會透過連接的套接字傳輸記憶體內部數據或檔案數據。 TransmitPackets 函式會使用操作系統快取管理員來擷取檔案數據、鎖定記憶體以最短的時間傳輸，併產生有效率、高效能的傳輸。

注意 此函式是 Windows Sockets 規格的 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 設定為零，讓套接字層選取預設 傳送 大小。

將 nSendSize 設定為 0xFFFFFFF 可讓呼叫端控制每個傳送要求的大小和內容，方法是使用 lpPacketArray 參數中所指向之TRANSMIT_PACKETS_ELEMENT數位中的TP_ELEMENT_EOP旗標來達成。 這項功能適用於訊息通訊協議，這些通訊協定會限制個別 傳送 要求的大小。

lpOverlapped

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

dwFlags

一組旗標，用來自定義 TransmitPackets 函式的處理。 下表概述 dwFlags 參數的使用。

值	意義
TF_DISCONNECT	在所有檔案數據已排入佇列以進行傳輸之後，啟動傳輸層級的中斷連線。 僅適用於連線導向套接字。 針對不支援中斷連線語意的套接字指定此旗標， (例如數據報套接字) 會導致錯誤。
TF_REUSE_SOCKET	準備要重複使用的套接字句柄。 當 TransmitPackets 函式完成時，套接字句柄可以傳遞至 AcceptEx 函式。 只有在指定連接導向套接字和TF_DISCONNECT時才有效。 注意 套接字層級封包傳輸受限於基礎傳輸的行為。 例如，TCP 套接字可能會受到 TCP TIME_WAIT狀態，導致 TransmitPackets 呼叫延遲。
TF_USE_DEFAULT_WORKER	指示 Winsock 使用系統的預設線程來處理長時間 的 TransmitPackets 要求。 Long TransmitPackets 要求會定義為要求需要從檔案或快取讀取多個單一的要求;因此，長要求定義取決於檔案的大小和傳送封包的指定長度。 您可以使用下列登錄參數作為 REG_DWORD：HKEY_LOCAL_MACHINE\CurrentControlSet\Services\AFD\參數\TransmitWorker 來調整系統默認線程
TF_USE_SYSTEM_THREAD	指示 Winsock 使用系統線程來處理長時間 的 TransmitPackets 要求。 Long TransmitPackets 要求會定義為要求需要從檔案或快取讀取多個單一的要求;因此，長要求定義取決於檔案的大小和傳送封包的指定長度。
TF_USE_KERNEL_APC	指示 Winsock 使用核心 異步過程調用 (APC) ，而不是背景工作線程來處理長時間 的 TransmitPackets 要求。 Long TransmitPackets 要求會定義為要求需要從檔案或快取讀取多個單一的要求;因此，長要求定義取決於檔案的大小和傳送封包的指定長度。 如需詳細資訊，請參閱「備註」。

傳回值

如果 TransmitPackets 函式成功，則傳回值為 TRUE。 否則，傳回值為 FALSE。 若要取得擴充錯誤資訊，請呼叫 WSAGetLastError。 WSA_IO_PENDING或ERROR_IO_PENDING的錯誤碼表示重疊的作業已成功起始，且稍後將會指出完成。 任何其他錯誤碼都表示重疊的作業未成功起始，而且不會發生任何完成指示。 在此情況下，應用程式應該處理ERROR_IO_PENDING或WSA_IO_PENDING。

傳回碼	Description
WSAECONNABORTED	您主機機器中的軟體已中止建立的連接。 如果虛擬線路因逾時或其他失敗而終止，就會傳回此錯誤。
WSAECONNRESET	遠端主機已強制關閉一個現有連線。 當遠端重設虛擬線路時，數據流套接字會傳回此錯誤。 此通訊端無法再使用，應用程式應予以關閉。
WSAEFAULT	系統在嘗試在呼叫中使用指標自變數時偵測到無效的指標位址。 如果 lpPacketArray 或 lpOverlapped 參數未完全包含在使用者位址空間的有效部分，就會傳回此錯誤。
WSAEINVAL	提供的引數無效。 如果 dwFlags 參數已設定 TF_REUSE_SOCKET 旗標，但未設定 TF_DISCONNECT 旗標，就會傳回此錯誤。 如果 lpOverlapped 所指向之重疊結構中指定的位移不在檔案內，也會傳回這個錯誤。 如果要傳輸的位元組總數大於 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。

備註

TransmitPackets 函式會根據所使用的操作系統進行優化：

• 在 Windows Server 版本上， TransmitPackets 函式已針對高效能進行優化。
• 在 Windows 用戶端版本上， TransmitPackets 函式已針對最小記憶體和資源使用率進行優化。

使用單一呼叫 TransmitPackets 函式傳輸的最大位元元組數目為 2,147,483,646,32 位整數的最大值減 1。 如果應用程式需要傳輸大於 2,147,483,646 個字節的數據，則 對 TransmitPackets 函式的多個呼叫可以搭配每個呼叫使用，傳輸不超過 2,147,483,646 個字節。

注意 您必須在運行時間取得 TransmitPackets 函式的函式指標，方法是呼叫 WSAIoctl 函式並指定 SIO_GET_EXTENSION_FUNCTION_POINTER opcode。 傳遞至 WSAIoctl 函式的輸入緩衝區必須包含 WSAID_TRANSMITPACKETS，這是全域唯一標識碼 (GUID) ，其值會識別 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 會將重疊結構的 hEvent 成員或 hSocket 所指定的套接字所指定的事件設定為訊號狀態，並在完成時將通知傳遞至與套接字相關聯的任何完成埠。 使用 GetOverlappedResult 或 WSAGetOverlappedResult 或 GetQueuedCompletionStatus 來擷取傳輸的最終狀態和位元組數目。

傳輸套件和異步過程調用 (APC)

使用 TF_USE_KERNEL_APC 旗標可提供顯著的效能優勢。 如果起始 TransmitPackets 函式呼叫的線程正用於大量計算，雖然不太可能，但無法啟動該 APC。

注意 核心與使用者模式 APC 之間有差異：

• 當線程處於等候狀態時，核心 APC 就會啟動。
• 當線程處於可警示的等候狀態時，使用者模式 APC 就會啟動。

 

Windows Phone 8：Windows Phone 8 和更新版本 Windows Phone 市集應用程式支援此函式。

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

規格需求

需求	值
最低支援的用戶端	Windows 8.1、Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台	Windows
標頭	mswsock.h

另請參閱

AcceptEx

GetOverlappedResult

GetQueuedCompletionStatus

重疊

TRANSMIT_PACKETS_ELEMENT

TransmitFile

WSAAccept

WSAConnect

WSAGetOverlappedResult

WSAJoinLeaf

Winsock 函式

Winsock 參考

接受

connect

send