Socket.SendFile 方法

  • 參考

定義

命名空間:
System.Net.Sockets
組件:
System.Net.Sockets.dll
組件:
System.dll
組件:
netstandard.dll

將檔案和選擇性資料同步傳送至已連接的 Socket。

多載

SendFile(String)

使用 Socket 傳輸旗標，將檔案 fileName 傳送至已連接的 UseDefaultWorkerThread 物件。
SendFile(String, Byte[], Byte[], TransmitFileOptions)

使用指定的 TransmitFileOptions 值，將檔案 fileName 和資料緩衝區傳送到連接的 Socket 物件。
SendFile(String, ReadOnlySpan<Byte>, ReadOnlySpan<Byte>, TransmitFileOptions)

使用指定的 TransmitFileOptions 值，將檔案 fileName 和資料緩衝區傳送到連接的 Socket 物件。

SendFile(String)

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

public:
 void SendFile(System::String ^ fileName);
public void SendFile (string fileName);
public void SendFile (string? fileName);
member this.SendFile : string -> unit
Public Sub SendFile (fileName As String)

參數

fileName
String

包含要傳送之檔案的路徑與名稱的 String。 這個參數可以是 null。

例外狀況

NotSupportedException

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

ObjectDisposedException

Socket物件已關閉。

InvalidOperationException

Socket 物件不是處於封鎖模式，而且無法接受此同步呼叫。

FileNotFoundException

找不到檔案 fileName。

SocketException

嘗試存取通訊端時發生錯誤。

範例

下列程式碼範例會建立並連接通訊端，然後將檔案傳送至遠端主機。 檔案 「test.txt」 位於本機電腦的根目錄中。

// Establish the local endpoint for the socket.
IPHostEntry^ ipHost = Dns::GetHostEntry( Dns::GetHostName() );
IPAddress^ ipAddr = ipHost->AddressList[ 0 ];
IPEndPoint^ ipEndPoint = gcnew IPEndPoint( ipAddr,11000 );

// Create a TCP socket.
Socket^ client = gcnew Socket( AddressFamily::InterNetwork,SocketType::Stream,ProtocolType::Tcp );

// Connect the socket to the remote endpoint.
client->Connect( ipEndPoint );

// There is a text file test.txt located in the root directory.
String^ fileName = "C:\\test.txt";

// Send file fileName to remote device
Console::WriteLine( "Sending {0} to the host.", fileName );
client->SendFile( fileName );

// Release the socket.
client->Shutdown( SocketShutdown::Both );
client->Close();

// Establish the local endpoint for the socket.
IPHostEntry ipHost = Dns.GetHostEntry(Dns.GetHostName());
IPAddress  ipAddr = ipHost.AddressList[0];
IPEndPoint ipEndPoint = new IPEndPoint(ipAddr, 11000);

// Create a TCP socket.
Socket client = new Socket(AddressFamily.InterNetwork,
        SocketType.Stream, ProtocolType.Tcp);

// Connect the socket to the remote endpoint.
client.Connect(ipEndPoint);

// There is a text file test.txt located in the root directory.
string fileName = "C:\\test.txt";

// Send file fileName to remote device
Console.WriteLine("Sending {0} to the host.", fileName);
client.SendFile(fileName);

// Release the socket.
client.Shutdown(SocketShutdown.Both);
client.Close();

備註

此多載會將檔案 fileName 傳送至連接的通訊端。 參數 flags 預設為 UseDefaultWorkerThread (0) ，而 preBuffer 和 postBuffer 參數預設為 null 。 如果 fileName 位於本機目錄中，則只能使用檔案名來識別，否則必須指定檔案的完整路徑和名稱。 萬用字元 (「。. \\myfile.txt支援「) 和 UNC 共用名稱 (」 \ \ \ \shared 目錄 \\myfile.txt「) 。 如果找不到檔案，則會擲回例外狀況 FileNotFoundException 。

此方法會使用 TransmitFile Windows Sockets 2 API 中找到的 函式。 如需函 TransmitFile 式及其旗標的詳細資訊，請參閱Windows Sockets檔。

SendFile以同步方式將檔案傳送至 或 Accept 方法中指定的 Connect 遠端主機。 SendFile 可用於連線導向和無連線通訊協定。

如果您使用無連線通訊協定，您必須先呼叫 Connect ，再呼叫此方法，否則 SendFile 會 SocketException 擲回例外狀況。 如果您使用連線導向通訊協定，則必須使用 Connect 來建立遠端主機連線，或使用 Accept 來接受連入連線。

如果您使用連線導向通訊協定， SendFile 請封鎖直到傳送檔案為止。 在非封鎖模式中， SendFile 可能會在傳送整個檔案之前順利完成。 不保證您傳送的資料會立即出現在網路上。 為了提升網路效率，基礎系統可能會延遲傳輸，直到收集大量的傳出資料為止。 方法成功完成 SendFile 表示基礎系統有空間可緩衝處理網路傳送的資料。

注意

如果您收到 SocketException ，請使用 SocketException.ErrorCode 屬性來取得特定的錯誤碼。 取得此程式碼之後，請參閱Windows 通訊端第 2 版 API 錯誤碼檔，以取得錯誤的詳細描述。

注意

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

適用於

SendFile(String, Byte[], Byte[], TransmitFileOptions)

使用指定的 TransmitFileOptions 值，將檔案 fileName 和資料緩衝區傳送到連接的 Socket 物件。

public:
 void SendFile(System::String ^ fileName, cli::array <System::Byte> ^ preBuffer, cli::array <System::Byte> ^ postBuffer, System::Net::Sockets::TransmitFileOptions flags);
public void SendFile (string? fileName, byte[]? preBuffer, byte[]? postBuffer, System.Net.Sockets.TransmitFileOptions flags);
public void SendFile (string fileName, byte[] preBuffer, byte[] postBuffer, System.Net.Sockets.TransmitFileOptions flags);
member this.SendFile : string * byte[] * byte[] * System.Net.Sockets.TransmitFileOptions -> unit
Public Sub SendFile (fileName As String, preBuffer As Byte(), postBuffer As Byte(), flags As TransmitFileOptions)

參數

fileName
String

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

preBuffer
Byte[]

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

postBuffer
Byte[]

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

flags
TransmitFileOptions

列舉值的位元組合，指定檔案的傳輸方式。

例外狀況

NotSupportedException

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

-或-

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

ObjectDisposedException

Socket物件已關閉。

InvalidOperationException

Socket 物件不是處於封鎖模式，而且無法接受此同步呼叫。

FileNotFoundException

找不到檔案 fileName。

SocketException

嘗試存取通訊端時發生錯誤。

範例

下列程式碼範例會建立並連接通訊端。 檔案 「test.txt」 位於本機電腦的根目錄中。 在此範例中，我們會建立預先緩衝器和後置資料，並使用 檔案將它們傳送至遠端主機。 會使用預設值 TransmitFileOptions 。

// Establish the local endpoint for the socket.
IPHostEntry^ ipHost = Dns::GetHostEntry( Dns::GetHostName() );
IPAddress^ ipAddr = ipHost->AddressList[ 0 ];
IPEndPoint^ ipEndPoint = gcnew IPEndPoint( ipAddr,11000 );

// Create a TCP socket.
Socket^ client = gcnew Socket( AddressFamily::InterNetwork,SocketType::Stream,ProtocolType::Tcp );

// Connect the socket to the remote endpoint.
client->Connect( ipEndPoint );

// Send file fileName to the remote host with preBuffer and postBuffer data.
// There is a text file test.txt located in the root directory.
String^ fileName = "C:\\test.txt";

// Create the preBuffer data.
String^ string1 = String::Format( "This is text data that precedes the file.{0}", Environment::NewLine );
array<Byte>^preBuf = Encoding::ASCII->GetBytes( string1 );

// Create the postBuffer data.
String^ string2 = String::Format( "This is text data that will follow the file.{0}", Environment::NewLine );
array<Byte>^postBuf = Encoding::ASCII->GetBytes( string2 );

//Send file fileName with buffers and default flags to the remote device.
Console::WriteLine( "Sending {0} with buffers to the host.{1}", fileName, Environment::NewLine );
client->SendFile( fileName, preBuf, postBuf, TransmitFileOptions::UseDefaultWorkerThread );

// Release the socket.
client->Shutdown( SocketShutdown::Both );
client->Close();

// Establish the local endpoint for the socket.
IPHostEntry ipHost = Dns.GetHostEntry(Dns.GetHostName());
IPAddress  ipAddr = ipHost.AddressList[0];
IPEndPoint ipEndPoint = new IPEndPoint(ipAddr, 11000);

// Create a TCP socket.
Socket client = new Socket(AddressFamily.InterNetwork,
        SocketType.Stream, ProtocolType.Tcp);

// Connect the socket to the remote endpoint.
client.Connect(ipEndPoint);

// Send file fileName to the remote host with preBuffer and postBuffer data.
// There is a text file test.txt located in the root directory.
string fileName = "C:\\test.txt";

// Create the preBuffer data.
string string1 = String.Format("This is text data that precedes the file.{0}", Environment.NewLine);
byte[] preBuf = Encoding.ASCII.GetBytes(string1);

// Create the postBuffer data.
string string2 = String.Format("This is text data that will follow the file.{0}", Environment.NewLine);
byte[] postBuf = Encoding.ASCII.GetBytes(string2);

//Send file fileName with buffers and default flags to the remote device.
Console.WriteLine("Sending {0} with buffers to the host.{1}", fileName, Environment.NewLine);
client.SendFile(fileName, preBuf, postBuf, TransmitFileOptions.UseDefaultWorkerThread);

// Release the socket.
client.Shutdown(SocketShutdown.Both);
client.Close();

備註

此多載需要您想要傳送的檔案名，以及值的位元組合 TransmitFileOptions 。 參數 preBuffer 包含您想要在檔案之前的任何資料。 postBuffer 包含您想要追蹤檔案的資料。 如果 fileName 位於目前的工作目錄中，則只能使用檔案名來識別，否則必須指定檔案的完整路徑和名稱。 萬用字元 (「。. \\myfile.txt支援「) 和 UNC 共用名稱 (」 \ \ \ \shared 目錄 \\myfile.txt「) 。

參數 flags 會提供 Window Sockets 服務提供者，並提供檔案傳輸的其他資訊。 如需如何使用此參數的詳細資訊，請參閱 TransmitFileOptions 。

此方法會使用 TransmitFile Windows Sockets 2 API 中找到的 函式。 如需函 TransmitFile 式及其旗標的詳細資訊，請參閱Windows Sockets檔。

SendFile以同步方式將檔案傳送至 或 Accept 方法中指定的 Connect 遠端主機。 SendFile 可用於連線導向和無連線通訊協定。

如果您使用無連線通訊協定，您必須先呼叫 Connect ，才能呼叫此方法，否則 SendFile 會 SocketException 擲回 。 如果您使用連線導向通訊協定，則必須使用 Connect 來建立遠端主機連線，或使用 Accept 來接受連入連線。

如果您使用連線導向通訊協定， SendFile 請封鎖直到傳送整個檔案為止。 在非封鎖模式中， SendFile 可能會在傳送整個檔案之前順利完成。 不保證您傳送的資料會立即出現在網路上。 為了提升網路效率，基礎系統可能會延遲傳輸，直到收集大量的傳出資料為止。 方法成功完成 SendFile 表示基礎系統有空間可緩衝處理網路傳送的資料。

注意

如果您收到 SocketException ，請使用 SocketException.ErrorCode 屬性來取得特定的錯誤碼。 取得此程式碼之後，請參閱Windows 通訊端第 2 版 API 錯誤碼檔，以取得錯誤的詳細描述。

注意

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

適用於

SendFile(String, ReadOnlySpan<Byte>, ReadOnlySpan<Byte>, TransmitFileOptions)

使用指定的 TransmitFileOptions 值，將檔案 fileName 和資料緩衝區傳送到連接的 Socket 物件。

public:
 void SendFile(System::String ^ fileName, ReadOnlySpan<System::Byte> preBuffer, ReadOnlySpan<System::Byte> postBuffer, System::Net::Sockets::TransmitFileOptions flags);
public void SendFile (string? fileName, ReadOnlySpan<byte> preBuffer, ReadOnlySpan<byte> postBuffer, System.Net.Sockets.TransmitFileOptions flags);
member this.SendFile : string * ReadOnlySpan<byte> * ReadOnlySpan<byte> * System.Net.Sockets.TransmitFileOptions -> unit
Public Sub SendFile (fileName As String, preBuffer As ReadOnlySpan(Of Byte), postBuffer As ReadOnlySpan(Of Byte), flags As TransmitFileOptions)

參數

fileName
String

包含要傳送之檔案的路徑與名稱的 String。 這個參數可以是 null。

preBuffer
ReadOnlySpan<Byte>

， ReadOnlySpan<T> 其中包含在傳送檔案之前要傳送的資料。 此緩衝區可以是空的。

postBuffer
ReadOnlySpan<Byte>

， ReadOnlySpan<T> 包含傳送檔案之後要傳送的資料。 此緩衝區可以是空的。

flags
TransmitFileOptions

一或多個 TransmitFileOptions 值。

例外狀況

ObjectDisposedException

Socket物件已關閉。

NotSupportedException

物件 Socket 未連線到遠端主機。

InvalidOperationException

Socket 物件不是處於封鎖模式，而且無法接受此同步呼叫。

FileNotFoundException

找不到檔案 fileName。

SocketException

嘗試存取通訊端時發生錯誤。

適用於