Socket.BeginSendFile 方法

定義

命名空間:

System.Net.Sockets

組件:

System.Net.Sockets.dll

將檔案以非同步方式傳送至已連接的 Socket 物件。

多載

BeginSendFile(String, AsyncCallback, Object)	使用 Socket 旗標，將檔案 fileName 傳送至已連接的 UseDefaultWorkerThread 物件。
BeginSendFile(String, Byte[], Byte[], TransmitFileOptions, AsyncCallback, Object)	將檔案和資料緩衝區以非同步方式傳送至已連接的 Socket 物件。

BeginSendFile(String, AsyncCallback, Object)

來源:

Socket.cs

使用 Socket 旗標，將檔案 fileName 傳送至已連接的 UseDefaultWorkerThread 物件。

public:
 IAsyncResult ^ BeginSendFile(System::String ^ fileName, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult BeginSendFile (string? fileName, AsyncCallback? callback, object? state);

member this.BeginSendFile : string * AsyncCallback * obj -> IAsyncResult

Public Function BeginSendFile (fileName As String, callback As AsyncCallback, state As Object) As IAsyncResult

參數

fileName

String

字串，包含要傳送之檔案的路徑和名稱。 這個參數可以是 null。

callback

AsyncCallback

AsyncCallback 委派。

state

Object

物件，包含這個要求的狀態資訊。

傳回

IAsyncResult

IAsyncResult 物件，表示非同步傳送。

例外狀況

ObjectDisposedException

Socket物件已關閉。

NotSupportedException

通訊端未連線至遠端主機。

FileNotFoundException

找不到檔案 fileName。

SocketException

.NET Framework 和 .NET 5 和更早版本：嘗試存取套接字時發生錯誤。 請參閱以下註解章節。

備註

重要

這是相容性 API。 不建議使用 APM (Begin* 和 End*) 方法來進行新的開發。 請改用 Task以 為基礎的對等專案。

此多載會透過套接字傳送檔案 fileName 。 如果 fileName 位於本機目錄中，則只能使用檔名來識別，否則必須指定檔案的完整路徑和名稱。 通配符 (“。.\\myfile.txt 支援“) 和 UNC 共用 (”\\\shared directory\\myfile.txt“) 。 如果找不到檔案，則會擲回例外狀況 FileNotFoundException 。

您可以傳遞實作 AsyncCallback 的回呼給 BeginSendFile ，以取得作業完成的通知。 請注意，如果基礎網路堆疊以同步方式完成作業，回呼將會在呼叫 BeginSendFile期間內嵌執行。 在此情況下， CompletedSynchronously 傳回 IAsyncResult 之 上的屬性會設定為 true ，表示方法會以同步方式完成。 AsyncState使用 的 IAsyncResult 屬性，取得傳遞至 BeginSendFile 方法的狀態物件。

BeginSendFile作業必須藉由呼叫 EndSendFile 方法來完成。 一般而言，委派會叫用 AsyncCallback 方法。 EndSendFile 將會封鎖呼叫線程，直到作業完成為止。

雖然適用於連線導向的通訊協定， BeginSendFile 但也適用於無連線通訊協定，前提是您第一次呼叫 Connect 或 BeginConnect 方法來建立預設遠端主機。 使用無連線通訊協定時，您必須確定檔案的大小不會超過基礎服務提供者的封包大小上限。 如果這樣做，則不會傳送數據報，並 BeginSendFile 擲回例外狀況 SocketException 。

注意

如果您收到 SocketException 例外狀況，請使用 SocketException.ErrorCode 屬性來取得特定的錯誤碼。

注意

在應用程式中啟用網路追蹤時，這個成員會輸出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

注意

系統會針對異步 Socket 方法快取執行內容 (安全性內容、仿真的使用者和呼叫內容) 。 在第一次使用特定內容 (特定異步 Socket 方法、特定 Socket 實例和特定回呼) 之後，後續使用該內容將會看到效能改善。

BeginSendFile(String, Byte[], Byte[], TransmitFileOptions, AsyncCallback, Object)

來源:

Socket.cs

將檔案和資料緩衝區以非同步方式傳送至已連接的 Socket 物件。

public:
 IAsyncResult ^ BeginSendFile(System::String ^ fileName, cli::array <System::Byte> ^ preBuffer, cli::array <System::Byte> ^ postBuffer, System::Net::Sockets::TransmitFileOptions flags, AsyncCallback ^ callback, System::Object ^ state);

public IAsyncResult BeginSendFile (string? fileName, byte[]? preBuffer, byte[]? postBuffer, System.Net.Sockets.TransmitFileOptions flags, AsyncCallback? callback, object? state);

member this.BeginSendFile : string * byte[] * byte[] * System.Net.Sockets.TransmitFileOptions * AsyncCallback * obj -> IAsyncResult

Public Function BeginSendFile (fileName As String, preBuffer As Byte(), postBuffer As Byte(), flags As TransmitFileOptions, callback As AsyncCallback, state As Object) As IAsyncResult

參數

fileName

String

字串，包含要傳送之檔案的路徑和名稱。 這個參數可以是 null。

preBuffer

Byte[]

傳送檔案之前要傳送的數據。 這個參數可以是 null。

postBuffer

Byte[]

傳送檔案之後要傳送的數據。 這個參數可以是 null。

flags

TransmitFileOptions

列舉值的位元組合。

callback

AsyncCallback

這個作業完成時要叫用的 AsyncCallback 委派。 這個參數可以是 null。

state

Object

使用者定義的物件，包含這個要求的狀態資訊。 這個參數可以是 null。

傳回

IAsyncResult

IAsyncResult 物件，表示非同步作業。

例外狀況

ObjectDisposedException

Socket物件已關閉。

SocketException

.NET Framework 和 .NET 5 和更早版本：嘗試存取套接字時發生錯誤。 請參閱以下註解章節。

NotSupportedException

作業系統不是 Windows NT (含) 以後版本。

-或-

通訊端未連線至遠端主機。

FileNotFoundException

找不到檔案 fileName。

備註

重要

這是相容性 API。 不建議使用 APM (Begin* 和 End*) 方法來進行新的開發。 請改用 Task以 為基礎的對等專案。

此多載需要您想要傳送的檔名，以及值的位元組合 TransmitFileOptions 。 參數 preBuffer 包含您想要在檔案之前的任何數據。 postBuffer 包含您想要追蹤檔案的數據。 如果 fileName 位於本機目錄中，則只能使用檔名來識別，否則必須指定檔案的完整路徑和名稱。 通配符 (“。.\\myfile.txt 支援“) 和 UNC 共用 (”\\\shared directory\\myfile.txt“) 。 如果找不到檔案，則會擲回例外狀況 FileNotFoundException 。

參數 flags 會提供有關文件傳輸的其他資訊。 如需如何使用此參數的詳細資訊，請參閱 TransmitFileOptions。

您可以傳遞實作 AsyncCallback 的回呼給 BeginSendFile ，以取得作業完成的通知。 請注意，如果基礎網路堆疊以同步方式完成作業，回呼將會在呼叫 BeginSendFile期間內嵌執行。 在此情況下， CompletedSynchronously 傳回 IAsyncResult 之 上的屬性會設定為 true ，表示方法會以同步方式完成。 AsyncState使用 的 IAsyncResult 屬性，取得傳遞至 BeginSendFile 方法的狀態物件。

BeginSendFile作業必須藉由呼叫 EndSendFile 方法來完成。 一般而言，方法是由提供的 AsyncCallback 委派叫用。 EndSendFile 將會封鎖呼叫線程，直到作業完成為止。

雖然適用於連線導向的通訊協定， BeginSendFile 但也適用於無連線通訊協定，前提是您第一次呼叫 Connect 或 BeginConnect 方法來建立預設遠端主機。 使用無連線通訊協定時，您必須確定檔案的大小不會超過基礎服務提供者的封包大小上限。 如果這樣做，則不會傳送數據報，並 BeginSendFile 擲回例外狀況 SocketException 。

注意

如果您收到 SocketException 例外狀況，請使用 SocketException.ErrorCode 屬性來取得特定的錯誤碼。

注意

在應用程式中啟用網路追蹤時，這個成員會輸出追蹤資訊。 如需詳細資訊，請參閱 .NET Framework 中的網路追蹤。

注意

系統會針對異步 Socket 方法快取執行內容 (安全性內容、仿真的使用者和呼叫內容) 。 在第一次使用特定內容 (特定異步 Socket 方法、特定 Socket 實例和特定回呼) 之後，後續使用該內容將會看到效能改善。