Socket.SendFile 方法

定义

将文件和可选数据异步发送到连接的 SocketSends a file and optional data synchronously to a connected Socket.

重载

SendFile(String)

使用 Socket 传输标志,将文件 fileName 发送到连接的 UseDefaultWorkerThread 对象。Sends the file fileName to a connected Socket object with the UseDefaultWorkerThread transmit flag.

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

通过指定的 TransmitFileOptions 值,将文件 fileName 和数据缓冲区发送到连接的 Socket 对象。Sends the file fileName and buffers of data to a connected Socket object using the specified TransmitFileOptions value.

SendFile(String)

使用 Socket 传输标志,将文件 fileName 发送到连接的 UseDefaultWorkerThread 对象。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);
member this.SendFile : string -> unit
Public Sub SendFile (fileName As String)

参数

fileName
String

一个 String,它包含要发送的文件的路径和名称。A String that contains the path and name of the file to be sent. 此参数可以为 nullThis parameter can be null.

异常

套接字未连接到远程主机。The socket is not connected to a remote host.

Socket 对象已关闭。The Socket object has been closed.

Socket 对象未处于阻止模式,无法接受此同步调用。The Socket object is not in blocking mode and cannot accept this synchronous call.

未找到文件 fileNameThe file fileName was not found.

尝试访问套接字时出错。An error occurred when attempting to access the socket.

示例

下面的代码示例创建并连接套接字,然后将文件发送到远程主机。The following code example creates and connects a socket and then sends a file to the remote host. 文件 "test.txt" 位于本地计算机的根目录中。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();

注解

此重载将文件 fileName 发送到连接的套接字。This overload sends the file fileName to the connected socket. flags 参数默认为 UseDefaultWorkerThread (0),preBufferpostBuffer 参数默认为 nullThe flags parameter defaults to UseDefaultWorkerThread (0), and the preBuffer and postBuffer parameters default to null. 如果 fileName 位于本地目录中,则只能用该文件的名称进行标识;否则,必须指定文件的完整路径和名称。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. 通配符(".。。支持\\myfile.txt ")和 UNC 共享名称("\\\\shared 目录\\myfile.txt ")。Wildcards ("..\\myfile.txt") and UNC share names ("\\\\shared directory\\myfile.txt") are supported. 如果找不到该文件,则将引发异常 FileNotFoundExceptionIf the file is not found, the exception FileNotFoundException is thrown.

此方法使用在 Windows Socket 2 API 中找到的 TransmitFile 函数。This method uses the TransmitFile function found in the Windows Sockets 2 API. 有关 TransmitFile 函数及其标志的详细信息,请参阅Windows 套接字文档。For more information about the TransmitFile function and its flags, see the Windows Sockets documentation.

SendFile 将文件同步发送到 ConnectAccept 方法中指定的远程主机。SendFile synchronously sends a file to the remote host specified in the Connect or Accept method. SendFile 可用于面向连接的协议和无连接协议。SendFile can be used for both connection-oriented and for connectionless protocols.

如果使用的是无连接协议,则必须在调用此方法之前调用 Connect,否则 SendFile 会引发 SocketException 异常。If you are using a connectionless protocol, you must call Connect before calling this method, otherwise SendFile throws a SocketException exception. 如果使用面向连接的协议,则必须使用 Connect 来建立远程主机连接,或使用 Accept 来接受传入连接。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.

如果使用面向连接的协议,则在发送文件之前 SendFile 阻止。If you are using a connection-oriented protocol, SendFile blocks until the file is sent. 在非阻止模式下,在发送整个文件之前,SendFile 可能会成功完成。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. 成功完成 SendFile 方法意味着基础系统具有空间来缓冲用于网络发送的数据。A successful completion of the SendFile method means that the underlying system has had room to buffer your data for a network send.

备注

如果收到 SocketException,请使用 SocketException.ErrorCode 属性获取特定的错误代码。If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code. 获取此代码后,请参阅Windows 套接字版本 2 API 错误代码文档,以获取有关错误的详细说明。After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.

备注

当你在应用程序中启用网络跟踪后,此成员将输出跟踪信息。This member outputs trace information when you enable network tracing in your application. 有关详细信息,请参阅.NET Framework 中的网络跟踪For more information, see Network Tracing in the .NET Framework.

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

通过指定的 TransmitFileOptions 值,将文件 fileName 和数据缓冲区发送到连接的 Socket 对象。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);
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

一个 String,它包含要发送的文件的路径和名称。A String that contains the path and name of the file to be sent. 此参数可以为 nullThis parameter can be null.

preBuffer
Byte[]

一个 Byte 数组,它包含发送文件前要发送的数据。A Byte array that contains data to be sent before the file is sent. 此参数可以为 nullThis parameter can be null.

postBuffer
Byte[]

一个 Byte 数组,它包含发送文件后要发送的数据。A Byte array that contains data to be sent after the file is sent. 此参数可以为 nullThis parameter can be null.

flags
TransmitFileOptions

一个或多个 TransmitFileOptions 值。One or more of TransmitFileOptions values.

异常

操作系统不是 Windows NT 或更高版本。The operating system is not Windows NT or later.

-or-

套接字未连接到远程主机。The socket is not connected to a remote host.

Socket 对象已关闭。The Socket object has been closed.

Socket 对象未处于阻止模式,无法接受此同步调用。The Socket object is not in blocking mode and cannot accept this synchronous call.

未找到文件 fileNameThe file fileName was not found.

尝试访问套接字时出错。An error occurred when attempting to access the socket.

示例

下面的代码示例创建并连接套接字。The following code example creates and connects a socket. 文件 "test.txt" 位于本地计算机的根目录中。The file "test.txt" is located in the root directory of the local machine. 在此示例中,我们将创建 prebuffer 和以增大 postbuffer 数据,并使用该文件将其发送到远程主机。In this example, we create a prebuffer and postbuffer of data and send them to the remote host with the file. 使用默认 TransmitFileOptionsThe 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();

注解

此重载要求要发送的文件的名称和 TransmitFileOptions 值的按位组合。This overload requires the name of the file you want to send and a bitwise combination of TransmitFileOptions values. preBuffer 参数包含要置于该文件之前的所有数据。The preBuffer parameter contains any data you want to precede the file. postBuffer 包含要跟踪文件的数据。postBuffer contains data you want to follow the file. 如果 fileName 在当前工作目录中,则可以只使用文件的名称进行标识;否则,必须指定文件的完整路径和名称。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. 通配符(".。。支持\\myfile.txt ")和 UNC 共享名称("\\\\shared 目录\\myfile.txt ")。Wildcards ("..\\myfile.txt") and UNC share names ("\\\\shared directory\\myfile.txt") are supported.

flags 参数为窗口套接字服务提供程序提供有关文件传输的其他信息。The flags parameter provides the Window Sockets service provider with additional information about the file transfer. 有关如何使用此参数的详细信息,请参阅 TransmitFileOptionsFor more information about how to use this parameter, see TransmitFileOptions.

此方法使用在 Windows Socket 2 API 中找到的 TransmitFile 函数。This method uses the TransmitFile function found in the Windows Sockets 2 API. 有关 TransmitFile 函数及其标志的详细信息,请参阅Windows 套接字文档。For more information about the TransmitFile function and its flags, see the Windows Sockets documentation.

SendFile 将文件同步发送到 ConnectAccept 方法中指定的远程主机。SendFile synchronously sends a file to the remote host specified in the Connect or Accept method. SendFile 可用于面向连接的协议和无连接协议。SendFile can be used for both connection-oriented and for connectionless protocols.

如果使用的是无连接协议,则必须在调用此方法之前调用 Connect;否则 SendFile 会引发 SocketExceptionIf you are using a connectionless protocol, you must call Connect before calling this method; otherwise SendFile throws a SocketException. 如果使用面向连接的协议,则必须使用 Connect 建立远程主机连接,或使用 Accept 来接受传入连接。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.

如果使用面向连接的协议,则在发送整个文件之前 SendFile 会阻止。If you are using a connection-oriented protocol, SendFile blocks until the entire file is sent. 在非阻止模式下,在发送整个文件之前,SendFile 可能会成功完成。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. 成功完成 SendFile 方法意味着基础系统具有空间来缓冲用于网络发送的数据。A successful completion of the SendFile method means that the underlying system has had room to buffer your data for a network send.

备注

如果收到 SocketException,请使用 SocketException.ErrorCode 属性获取特定的错误代码。If you receive a SocketException, use the SocketException.ErrorCode property to obtain the specific error code. 获取此代码后,请参阅Windows 套接字版本 2 API 错误代码文档,以获取有关错误的详细说明。After you have obtained this code, refer to the Windows Sockets version 2 API error code documentation for a detailed description of the error.

备注

当你在应用程序中启用网络跟踪后,此成员将输出跟踪信息。This member outputs trace information when you enable network tracing in your application. 有关详细信息,请参阅.NET Framework 中的网络跟踪For more information, see Network Tracing in the .NET Framework.

适用于