函式原型:BOOL
PASCAL FAR
TransmitFile(
IN SOCKET hSocket,
IN HANDLE hFile,
IN DWORD nNumberOfBytesToWrite,
IN DWORD nNumberOfBytesPerSend,
IN LPOVERLAPPED lpOverlapped,
IN LPTRANSMIT_FILE_BUFFERS lpTransmitBuffers,
IN DWORD dwReserved);
參數說明:第一個參數是連線套接字。hFile 參數是一個打開檔案的句柄,這個參數可以是NULL,此時將傳輸 lpTransmitBuffer。當然,使用TransmitFile 來傳送僅用於存儲的緩衝區沒有什麼意義。nNumberOfBytesToWrite 參數是從檔案傳送的位元組數,取值為零時表示傳送整個檔案。nNumberOfBytesPerSend 參數指明每個傳送操作中所傳送的每個數據塊的大小,如果將其指定為零,系統就使用默認的傳送大小。Windows NT 工作站上默認的傳送大小是 4K,南昌在Windows伺服器上是64K。lpOVERLAPPED 結構可有可無,但得注意,如果忽略掉這個結構,檔案傳輸將從當前檔案指針的位置開始。lpTransmitBuffers 參數是一個 TRANSMIT_FILE_BUFFERS 結構,包含存儲緩衝區,這個存儲緩衝區將在檔案被傳輸之前或之後傳輸。lpTransmitBuffers 參數是一個可選參數。最後一個參數是可選標誌,它將影響檔案操作的行為。
TransmitFile標誌
標誌 | 意義 |
TF_DISCONNECT | 在 TransmitFile 操作進入等待佇列後,發起一個傳輸層斷開動作。 |
TF_REUSE_SOCKET | 為套接字句柄的重新使用作好準備。在 TransmitFile 完成後,套接字句柄可用作 AcceptEx 中的客戶機套接字,只有當 TF_DISCONNECT 也被指定時,這個標誌才會生效。 |
TF_USE_DEFAULT_WORKER | 指示檔案傳輸使用系統的默認執行緒,這對大型檔案的傳送很有用。 |
TF_USE_SYSTEM_THREAD | 這個選項也指示 TransmitFile 操作使用系統默認執行緒來執行。 |
TF_USE_KERNEL_APC | 指明應該使用核心異步過程調用來處理 TransmitFile 請求,而不用工作器執行緒。注意,如果應用程式處於等待狀態(儘管不一定非得是警覺等待狀態),則核心APC只能由應用程式安排時間來運行。 |
TF_WRITE_BEHIND | 指明 TransmitFile 請求應該立即返回,即使遠端可能還沒有確認已收到數據。這個標誌不能與 TF_DISCONNECT 或 TF_REUSE_SOCKET 標誌同時使用。 |
對基於檔案的I/O(如WEB伺服器)來說,TransmitFile 函式很有用。另外它的一個有用的特性,是能夠指定標誌 TF_DISCONNECT 和 TF_REUSE_SOCKET。如果兩個標誌都指定,一旦傳送操作完成,檔案和(或)存儲緩衝區都將被傳輸,套接字也將斷開。同時,傳遞到API的套接字句柄將被用作AcceptEx中的客戶機套接字,或用作AcceptEx中的連線套接字。因為套接字創建耗費非常之大,所以這一個極其有用。伺服器可以用AcceptEx來處理客戶機連線,然後用 TransmitFile 傳送數據(指定上述標誌),過後套接字句柄可以在隨後對的AcceptEx 調用中使用。
注意,可以使用空檔案句柄及空 lpTransmitBuffers 來調用 TransmitFile ,不過全然要指定 TF_DISCONNECT 和 TF_REUSE_SOCKET。這個調用不會傳送任何數據,只是會讓套接字在 AcceptEx 中重新使用。對於不支持 DisconnectEx API的平台來說,這是一個很好的變通方法。最後,Windows NT 4.0及後期版本均支持 TransmitFile 函式。同時,因為 TransmitFile 著重於伺服器應用程式,因此只有在 Window 的伺服器版本上,其功能才能得到完全發揮。對於家庭版或專業版,在任何時候,只可以有兩個未完成的 TransmitFile(或 TransmitPackets)調用。如果超過這個數目,則多餘的將排除等候,直到正在執行的調用結束之後,才會被處理。