Socket.SendFile Метод

Определение

Выполняет синхронную передачу файла и дополнительных данных на подключенный объект Socket.Sends a file and optional data synchronously to a connected Socket.

Перегрузки

SendFile(String)

Отправляет файл fileName на подключенный объект Socket, используя флаг передачи UseDefaultWorkerThread.Sends the file fileName to a connected Socket object with the UseDefaultWorkerThread transmit flag.

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

Отправляет файл fileName и буферы данных в подключенный объект Socket, используя указанное значение TransmitFileOptions.Sends the file fileName and buffers of data to a connected Socket object using the specified TransmitFileOptions value.

SendFile(String)

Отправляет файл fileName на подключенный объект Socket, используя флаг передачи 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. Этот параметр может иметь значение null.This 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.

Файл fileName не найден.The 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), а preBuffer postBuffer Параметры и по умолчанию null имеют значение.The 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-папок (" \ \ \ \шаред Directory \\myfile.txt ").Wildcards ("..\\myfile.txt") and UNC share names ("\\\\shared directory\\myfile.txt") are supported. Если файл не найден, FileNotFoundException возникает исключение.If the file is not found, the exception FileNotFoundException is thrown.

Этот метод использует TransmitFile функцию, обнаруженную в API Windows Sockets 2.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 синхронно отправляет файл на удаленный узел, указанный в Connect Accept методе или.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. После получения этого кода обратитесь к документации по коду ошибки API Windows Sockets версии 2 для получения подробного описания ошибки.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)

Отправляет файл fileName и буферы данных в подключенный объект Socket, используя указанное значение TransmitFileOptions.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)

Параметры

fileName
String

Параметр типа String, содержащий имя отправляемого файла и путь к нему.A String that contains the path and name of the file to be sent. Этот параметр может иметь значение null.This parameter can be null.

preBuffer
Byte[]

Массив Byte, содержащий данные, отправляемые перед передачей файла.A Byte array that contains data to be sent before the file is sent. Этот параметр может иметь значение null.This parameter can be null.

postBuffer
Byte[]

Массив Byte, содержащий данные, отправляемые после передачи файла.A Byte array that contains data to be sent after the file is sent. Этот параметр может иметь значение null.This 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.

Файл fileName не найден.The 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. В этом примере мы создадим предбуферную и буферизованную передачу данных и отправим их на удаленный узел с помощью файла.In this example, we create a prebuffer and postbuffer of data and send them to the remote host with the file. Используются значения по умолчанию TransmitFileOptions .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();

Комментарии

Для этой перегрузки требуется имя файла, который необходимо отправить, и побитовое сочетание 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-папок (" \ \ \ \шаред Directory \\myfile.txt ").Wildcards ("..\\myfile.txt") and UNC share names ("\\\\shared directory\\myfile.txt") are supported.

flagsПараметр предоставляет поставщику услуг Windows Sockets дополнительные сведения о переносе файлов.The flags parameter provides the Window Sockets service provider with additional information about the file transfer. Дополнительные сведения об использовании этого параметра см. в разделе TransmitFileOptions .For more information about how to use this parameter, see TransmitFileOptions.

Этот метод использует TransmitFile функцию, обнаруженную в API Windows Sockets 2.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 синхронно отправляет файл на удаленный узел, указанный в Connect Accept методе или.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. Если используется протокол, ориентированный на соединение, необходимо либо использовать 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. После получения этого кода обратитесь к документации по коду ошибки API Windows Sockets версии 2 для получения подробного описания ошибки.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.

Применяется к