แก้ไข

แชร์ผ่าน

Socket.SendFile Method

  • Reference

Definition

Namespace:
System.Net.Sockets
Assembly:
System.Net.Sockets.dll
Assembly:
System.dll
Assembly:
netstandard.dll

Sends a file and optional data synchronously to a connected Socket.

Overloads

SendFile(String)

Sends the file fileName to a connected Socket object with the UseDefaultWorkerThread transmit flag.
SendFile(String, Byte[], Byte[], TransmitFileOptions)

Sends the file fileName and buffers of data to a connected Socket object using the specified TransmitFileOptions value.
SendFile(String, ReadOnlySpan<Byte>, ReadOnlySpan<Byte>, TransmitFileOptions)

Sends the file fileName and buffers of data to a connected Socket object using the specified TransmitFileOptions value.

SendFile(String)

Source:
Socket.cs
Source:
Socket.cs
Source:
Socket.cs

Sends the file fileName to a connected Socket object with the UseDefaultWorkerThread transmit flag.

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)

Parameters

fileName
String

A String that contains the path and name of the file to be sent. This parameter can be null.

Exceptions

NotSupportedException

The socket is not connected to a remote host.

ObjectDisposedException

The Socket object has been closed.

InvalidOperationException

The Socket object is not in blocking mode and cannot accept this synchronous call.

FileNotFoundException

The file fileName was not found.

SocketException

An error occurred when attempting to access the socket.

Examples

The following code example creates and connects a socket and then sends a file to the remote host. The file "test.txt" is located in the root directory of the local machine.

// 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();

Remarks

This overload sends the file fileName to the connected socket. The flags parameter defaults to UseDefaultWorkerThread (0), and the preBuffer and postBuffer parameters default to null. If fileName is in the local directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards ("..\\myfile.txt") and UNC share names ("\\\\shared directory\\myfile.txt") are supported. If the file is not found, the exception FileNotFoundException is thrown.

This method uses the TransmitFile function found in the Windows Sockets 2 API. For more information about the TransmitFile function and its flags, see the Windows Sockets documentation.

SendFile synchronously sends a file to the remote host specified in the Connect or Accept method. SendFile can be used for both connection-oriented and for connectionless protocols.

If you are using a connectionless protocol, you must call Connect before calling this method, otherwise SendFile throws a SocketException exception. If you are using a connection-oriented protocol, you must either use Connect to establish a remote host connection or use Accept to accept an incoming connection.

If you are using a connection-oriented protocol, SendFile blocks until the file is sent. In nonblocking mode, SendFile may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the SendFile method means that the underlying system has had room to buffer your data for a network send.

Note

If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.

Note

This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in .NET Framework.

Applies to

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

Source:
Socket.cs
Source:
Socket.cs
Source:
Socket.cs

Sends the file fileName and buffers of data to a connected Socket object using the specified TransmitFileOptions value.

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)

Parameters

fileName
String

The path and name of the file to be sent. This parameter can be null.

preBuffer
Byte[]

The data to be sent before the file is sent. This parameter can be null.

postBuffer
Byte[]

The data to be sent after the file is sent. This parameter can be null.

flags
TransmitFileOptions

A bitwise combination of the enumeration values that specifies how the file is transferred.

Exceptions

NotSupportedException

The operating system is not Windows NT or later.

-or-

The socket is not connected to a remote host.

ObjectDisposedException

The Socket object has been closed.

InvalidOperationException

The Socket object is not in blocking mode and cannot accept this synchronous call.

FileNotFoundException

The file fileName was not found.

SocketException

An error occurred when attempting to access the socket.

Examples

The following code example creates and connects a socket. The file "test.txt" is located in the root directory of the local machine. In this example, we create a prebuffer and postbuffer of data and send them to the remote host with the file. The default TransmitFileOptions are used.

// 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();

Remarks

This overload requires the name of the file you want to send and a bitwise combination of TransmitFileOptions values. The preBuffer parameter contains any data you want to precede the file. postBuffer contains data you want to follow the file. If fileName is in the current working directory, it may be identified with just the name of the file; otherwise, the full path and name of the file must be specified. Wildcards ("..\\myfile.txt") and UNC share names ("\\\\shared directory\\myfile.txt") are supported.

The flags parameter provides the Window Sockets service provider with additional information about the file transfer. For more information about how to use this parameter, see TransmitFileOptions.

This method uses the TransmitFile function found in the Windows Sockets 2 API. For more information about the TransmitFile function and its flags, see the Windows Sockets documentation.

SendFile synchronously sends a file to the remote host specified in the Connect or Accept method. SendFile can be used for both connection-oriented and for connectionless protocols.

If you are using a connectionless protocol, you must call Connect before calling this method; otherwise SendFile throws a SocketException. If you are using a connection-oriented protocol, you must either use Connect to establish a remote host connection, or use Accept to accept an incoming connection.

If you are using a connection-oriented protocol, SendFile blocks until the entire file is sent. In nonblocking mode, SendFile may complete successfully before the entire file has been sent. There is no guarantee that the data you send will appear on the network immediately. To increase network efficiency, the underlying system may delay transmission until a significant amount of outgoing data is collected. A successful completion of the SendFile method means that the underlying system has had room to buffer your data for a network send.

Note

If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code. After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.

Note

This member outputs trace information when you enable network tracing in your application. For more information, see Network Tracing in .NET Framework.

Applies to

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

Source:
Socket.cs
Source:
Socket.cs
Source:
Socket.cs

Sends the file fileName and buffers of data to a connected Socket object using the specified TransmitFileOptions value.

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)

Parameters

fileName
String

A String that contains the path and name of the file to be sent. This parameter can be null.

preBuffer
ReadOnlySpan<Byte>

A ReadOnlySpan<T> that contains data to be sent before the file is sent. This buffer can be empty.

postBuffer
ReadOnlySpan<Byte>

A ReadOnlySpan<T> that contains data to be sent after the file is sent. This buffer can be empty.

flags
TransmitFileOptions

One or more of TransmitFileOptions values.

Exceptions

ObjectDisposedException

The Socket object has been closed.

NotSupportedException

The Socket object is not connected to a remote host.

InvalidOperationException

The Socket object is not in blocking mode and cannot accept this synchronous call.

FileNotFoundException

The file fileName was not found.

SocketException

An error occurred when attempting to access the socket.

Applies to