Socket.BeginSendFile メソッド

定義

接続された Socket オブジェクトに、ファイルを非同期的に送信します。Sends a file asynchronously to a connected Socket object.

オーバーロード

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

接続された Socket オブジェクトに、ファイルとデータのバッファーを非同期的に送信します。Sends a file and buffers of data asynchronously to a connected Socket object.

BeginSendFile(String, AsyncCallback, Object)

UseDefaultWorkerThread フラグを使用して、接続されている Socket オブジェクトにファイル fileName を送信します。Sends the file fileName to a connected Socket object using the UseDefaultWorkerThread flag.

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

接続された Socket オブジェクトに、ファイルとデータのバッファーを非同期的に送信します。Sends a file and buffers of data asynchronously to a connected Socket object.

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

送信されるファイルのパスと名前を格納する文字列。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 値のビットごとの組み合わせ。A bitwise combination of TransmitFileOptions values.

callback
AsyncCallback

このオプションの完了時に呼び出される AsyncCallback デリゲート。An AsyncCallback delegate to be invoked when this operation completes. このパラメーターは、null に設定できます。This parameter can be null.

state
Object

この要求の状態情報を格納するユーザー定義のオブジェクト。A user-defined object that contains state information for this request. このパラメーターは、null に設定できます。This parameter can be null.

戻り値

IAsyncResult

非同期操作を表す IAsyncResult オブジェクト。An IAsyncResult object that represents the asynchronous operation.

例外

Socket オブジェクトは閉じられています。The Socket object has been closed.

ソケットへのアクセスを試行しているときにエラーが発生しました。An error occurred when attempting to access the socket. 以下の解説を参照してください。See remarks section below.

オペレーティング システムは Windows NT 以降ではありません。The operating system is not Windows NT or later.

- または --or-

ソケットがリモート ホストに接続されていません。The socket is not connected to a remote host.

ファイル fileName が見つかりませんでした。The file fileName was not found.

次のコード例では、非同期通信用のソケットを作成して接続し、リモートホストへのファイル "text.txt" の非同期送信を開始します。The following code example creates and connects a socket for asynchronous communication and begins sending the file "text.txt" asynchronously to the remote host. この例では、 preBuffer ファイルと postBuffer 共に送信するデータのとが作成され、既定 TransmitFileOptions 値が使用されます。In this example, a preBuffer and a postBuffer of data is created to send with the file and the default TransmitFileOptions value is used. コールバックデリゲートは、 EndSendFile 転送を完了するためにを呼び出します。The callback delegate calls EndSendFile to complete the transmission.

public:
   static void AsynchronousFileSendWithBuffers()
   {
      // Send a file asynchronously to the remote device. Send a buffer before the file and a buffer afterwards.
      // Establish the remote endpoint for the socket.
      IPHostEntry^ ipHostInfo = Dns::GetHostEntry( Dns::GetHostName() );
      IPAddress^ ipAddress = ipHostInfo->AddressList[ 0 ];
      IPEndPoint^ remoteEP = gcnew IPEndPoint( ipAddress,11000 );

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

      // Connect to the remote endpoint.
      client->BeginConnect( remoteEP, gcnew AsyncCallback( ConnectCallback ), client );

      // Wait for connect.
      connectDone->WaitOne();

      // Send a file fileName to the remote device with preBuffer and postBuffer data.
      // 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 );

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

      //Send file fileName with buffers and default flags to the remote device.
      Console::WriteLine( fileName );
      client->BeginSendFile( fileName, preBuf, postBuf, static_cast<TransmitFileOptions>(0), gcnew AsyncCallback( AsynchronousFileSendCallback ), client );

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


private:
   static void AsynchronousFileSendCallback( IAsyncResult^ ar )
   {
      // Retrieve the socket from the state object.
      Socket^ client = dynamic_cast<Socket^>(ar->AsyncState);

      // Complete sending the data to the remote device.
      client->EndSendFile( ar );
      sendDone->Set();
   }
public static void AsynchronousFileSendWithBuffers()
{
    // Send a file asynchronously to the remote device. Send a buffer before the file and a buffer afterwards.

    // Establish the remote endpoint for the socket.
    IPHostEntry ipHostInfo = Dns.GetHostEntry(Dns.GetHostName());
    IPAddress ipAddress = ipHostInfo.AddressList[0];
    IPEndPoint remoteEP = new IPEndPoint(ipAddress, 11000);

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

    // Connect to the remote endpoint.
    client.BeginConnect(remoteEP,
        new AsyncCallback(ConnectCallback), client);

    // Wait for connect.
    connectDone.WaitOne();

    // Send a file fileName to the remote device with preBuffer and postBuffer data.
    // 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);

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

    //Send file fileName with buffers and default flags to the remote device.
    Console.WriteLine(fileName);
    client.BeginSendFile(fileName, preBuf, postBuf, 0, new AsyncCallback(AsynchronousFileSendCallback), client);

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

private static void AsynchronousFileSendCallback(IAsyncResult ar)
{
    // Retrieve the socket from the state object.
    Socket client = (Socket) ar.AsyncState;

    // Complete sending the data to the remote device.
    client.EndSendFile(ar);
    sendDone.Set();
}

注釈

このオーバーロードには、送信するファイルの名前と値のビットごとの組み合わせが必要です TransmitFileOptionsThis 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 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 共有名 (" \ \ \ \ 共有ディレクトリ \\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.

パラメーターは、 flags ファイル転送に関する追加情報を Window Sockets service プロバイダーに提供します。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.

このメソッドは、 TransmitFile Windows Sockets 2 API で検出された関数を使用します。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.

BeginSendFileメソッドは、、、、のいずれかのメソッドで確立されたリモートホストに対して、非同期の送信操作を開始し Connect BeginConnect Accept BeginAccept ます。The BeginSendFile method starts an asynchronous send operation to the remote host established in the Connect, BeginConnect, Accept, or BeginAccept methods. BeginSendFile 最初に、、、またはを呼び出さない場合、例外がスローされ Accept BeginAccept Connect BeginConnect ます。BeginSendFile throws an exception if you do not first call Accept, BeginAccept, Connect, or BeginConnect. メソッドを呼び出す BeginSendFile と、別の実行スレッド内でファイルを送信できるようになります。Calling the BeginSendFile method gives you the ability to send a file within a separate execution thread.

操作を完了するには、デリゲートパラメーターによって呼び出されるコールバックメソッドを作成し AsyncCallback ます。To complete the operation, you can create a callback method that is invoked by the AsyncCallback delegate parameter. これを行うには、少なくとも、 state パラメーターには通信に使用されるオブジェクトが含まれている必要があり Socket ます。To do this, at the very minimum, the state parameter must contain the Socket object being used for communication. コールバックでより多くの情報が必要な場合は、 Socket とその他の必要な情報を保持するクラスまたは構造体を作成できます。If your callback needs more information, you can create a class or structure to hold the Socket and the other required information. パラメーターを使用して、このカスタムオブジェクトのインスタンスをメソッドに渡し BeginSendFile state ます。Pass an instance of this custom object to the BeginSendFile method through the state parameter.

コールバックメソッドは、メソッドを呼び出す必要があり EndSendFile ます。Your callback method must invoke the EndSendFile method. アプリケーションがを呼び出すと BeginSendFile 、システムは別のスレッドを使用して指定されたコールバックメソッドを実行し、 EndSendFileSocket ファイル全体を送信するか、例外をスローするまでブロックします。When your application calls BeginSendFile, the system uses a separate thread to execute the specified callback method, and blocks on EndSendFile until the Socket sends the entire file or throws an exception. コールバックメソッドの記述の詳細については 、「コールバックメソッドとしてのデリゲートのマーシャリング」を参照してください。For additional information on writing callback methods see Marshaling a Delegate as a Callback Method.

接続指向プロトコルを想定してい BeginSendFile ますが、最初に Connect メソッドまたはメソッドを呼び出して既定のリモートホストを確立した場合、コネクションレスプロトコルでも機能し BeginConnect ます。Although intended for connection-oriented protocols, BeginSendFile also works for connectionless protocols, provided that you first call the Connect or BeginConnect method to establish a default remote host. コネクションレスプロトコルを使用する場合は、ファイルのサイズが基になるサービスプロバイダーの最大パケットサイズを超えていないことを確認する必要もあります。With connectionless protocols, you must also be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. この場合、データグラムは送信されず、 BeginSendFile 例外がスローされ SocketException ます。If it does, the datagram is not sent and BeginSendFile throws a SocketException exception.

注意

例外が発生した場合は、プロパティを使用して、 SocketException SocketException.ErrorCode 特定のエラーコードを取得します。If you receive a SocketException exception, use the SocketException.ErrorCode property to obtain the specific error code. このコードを取得したら、 Windows Sockets version 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.

注意

非同期メソッドに対して、実行コンテキスト (セキュリティコンテキスト、権限を借用したユーザー、および呼び出し元のコンテキスト) がキャッシュされ Socket ます。The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous Socket methods. 特定のコンテキスト (特定の非同期メソッド、特定のインスタンス、および特定のコールバック) を初めて使用した後 Socket Socket 、そのコンテキストを使用すると、パフォーマンスが向上します。After the first use of a particular context (a specific asynchronous Socket method, a specific Socket instance, and a specific callback), subsequent uses of that context will see a performance improvement.

適用対象

BeginSendFile(String, AsyncCallback, Object)

UseDefaultWorkerThread フラグを使用して、接続されている Socket オブジェクトにファイル fileName を送信します。Sends the file fileName to a connected Socket object using the UseDefaultWorkerThread flag.

public:
 IAsyncResult ^ BeginSendFile(System::String ^ fileName, AsyncCallback ^ callback, System::Object ^ state);
public IAsyncResult BeginSendFile (string fileName, AsyncCallback? callback, 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

送信するファイルのパスと名前を格納する文字列。A string that contains the path and name of the file to send. このパラメーターは、null に設定できます。This parameter can be null.

callback
AsyncCallback

AsyncCallback デリゲート。The AsyncCallback delegate.

state
Object

この要求の状態情報を格納するオブジェクト。An object that contains state information for this request.

戻り値

IAsyncResult

非同期送信を表す IAsyncResult オブジェクト。An IAsyncResult object that represents the asynchronous send.

例外

Socket オブジェクトは閉じられています。The Socket object has been closed.

ソケットがリモート ホストに接続されていません。The socket is not connected to a remote host.

ファイル fileName が見つかりませんでした。The file fileName was not found.

ソケットへのアクセスを試行しているときにエラーが発生しました。An error occurred when attempting to access the socket. 以下の解説を参照してください。See remarks section below.

次のコード例では、非同期通信用のソケットを作成して接続します。The following code example creates and connects a socket for asynchronous communication. まず、ファイル "text.txt" がリモートホストに非同期的に送信されます。First, the file "text.txt" is sent asynchronously to the remote host. コールバックデリゲートは、 EndSendFile 転送を完了するためにを呼び出します。The callback delegate calls EndSendFile to complete the transmission.

   static void AsynchronousFileSend()
   {
      // Send a file to a remote device.
      // Establish the remote endpoint for the socket.
      IPHostEntry^ ipHostInfo = Dns::GetHostEntry( Dns::GetHostName() );
      IPAddress^ ipAddress = ipHostInfo->AddressList[ 0 ];
      IPEndPoint^ remoteEP = gcnew IPEndPoint( ipAddress,11000 );

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

      // Connect to the remote endpoint.
      client->BeginConnect( remoteEP, gcnew AsyncCallback( ConnectCallback ), client );

      // Wait for connect.
      connectDone->WaitOne();

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

      // Send file fileName to the remote device.
      Console::WriteLine( fileName );
      client->BeginSendFile( fileName, gcnew AsyncCallback( FileSendCallback ), client );

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

private:
   static void FileSendCallback( IAsyncResult^ ar )
   {
      // Retrieve the socket from the state object.
      Socket^ client = dynamic_cast<Socket^>(ar->AsyncState);

      // Complete sending the data to the remote device.
      client->EndSendFile( ar );
      sendDone->Set();
   }

public static void AsynchronousFileSend()
{
    // Send a file to a remote device.

    // Establish the remote endpoint for the socket.
    IPHostEntry ipHostInfo = Dns.GetHostEntry(Dns.GetHostName());
    IPAddress ipAddress = ipHostInfo.AddressList[0];
    IPEndPoint remoteEP = new IPEndPoint(ipAddress, 11000);

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

    // Connect to the remote endpoint.
    client.BeginConnect(remoteEP,
        new AsyncCallback(ConnectCallback), client);

    // Wait for connect.
    connectDone.WaitOne();

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

    // Send file fileName to the remote device.
    Console.WriteLine(fileName);
    client.BeginSendFile(fileName, new AsyncCallback(FileSendCallback), client);

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

private static void FileSendCallback(IAsyncResult ar)
{
    // Retrieve the socket from the state object.
    Socket client = (Socket) ar.AsyncState;

    // Complete sending the data to the remote device.
    client.EndSendFile(ar);
    sendDone.Set();
}

注釈

このオーバーロード fileName は、接続されているソケットにファイルを送信します。This overload sends the file fileName to the connected socket. 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 共有名 (" \ \ \ \ 共有ディレクトリ \\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 Windows Sockets 2 API で検出された関数を使用します。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.

BeginSendFileメソッドは、、、、のいずれかのメソッドで確立されたリモートホストに対して、非同期の送信操作を開始し Connect BeginConnect Accept BeginAccept ます。The BeginSendFile method starts an asynchronous send operation to the remote host established in the Connect,BeginConnect, Accept, or BeginAccept methods. BeginSendFile 最初に、、、またはを呼び出さない場合、例外がスローされ Accept BeginAccept Connect BeginConnect ます。BeginSendFile throws an exception if you do not first call Accept, BeginAccept, Connect, or BeginConnect. メソッドを呼び出す BeginSendFile と、別の実行スレッド内でファイルを送信できます。Calling the BeginSendFile method enables you to send a file within a separate execution thread.

操作を完了するには、デリゲートパラメーターによって呼び出されるコールバックメソッドを作成し AsyncCallback ます。To complete the operation, you can create a callback method that is invoked by the AsyncCallback delegate parameter. これを行うには、少なくとも、 state パラメーターには通信に使用されるオブジェクトが含まれている必要があり Socket ます。To do this, at the very minimum, the state parameter must contain the Socket object being used for communication. コールバックでより多くの情報が必要な場合は、 Socket とその他の必要な情報を保持するクラスまたは構造体を作成できます。If your callback needs more information, you can create a class or structure to hold the Socket and the other required information. パラメーターを使用して、このカスタムオブジェクトのインスタンスをメソッドに渡し BeginSendFile state ます。Pass an instance of this custom object to the BeginSendFile method through the state parameter.

コールバックメソッドは、メソッドを呼び出す必要があり EndSendFile ます。Your callback method must invoke the EndSendFile method. アプリケーションがを呼び出すと BeginSendFile 、システムは別のスレッドを使用して指定されたコールバックメソッドを実行し、 EndSendFileSocket ファイル全体を送信するか、例外をスローするまでブロックします。When your application calls BeginSendFile, the system uses a separate thread to execute the specified callback method, and blocks on EndSendFile until the Socket sends the entire file or throws an exception. コールバックメソッドの記述の詳細については 、「コールバックメソッドとしてのデリゲートのマーシャリング」を参照してください。For additional information on writing callback methods see Marshaling a Delegate as a Callback Method.

接続指向プロトコルを想定してい BeginSendFile ますが、最初に Connect メソッドまたはメソッドを呼び出して既定のリモートホストを確立した場合、コネクションレスプロトコルでも機能し BeginConnect ます。Although intended for connection-oriented protocols, BeginSendFile also works for connectionless protocols, provided that you first call the Connect or BeginConnect method to establish a default remote host. コネクションレスプロトコルを使用する場合は、ファイルのサイズが基になるサービスプロバイダーの最大パケットサイズを超えていないことを確認する必要があります。With connectionless protocols, you must be sure that the size of your file does not exceed the maximum packet size of the underlying service provider. この場合、データグラムは送信されず、 BeginSendFile 例外がスローされ SocketException ます。If it does, the datagram is not sent and BeginSendFile throws a SocketException exception.

注意

例外が発生した場合は、プロパティを使用して、 SocketException SocketException.ErrorCode 特定のエラーコードを取得します。If you receive a SocketException exception, use the SocketException.ErrorCode property to obtain the specific error code. このコードを取得したら、 Windows Sockets version 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.

注意

非同期メソッドに対して、実行コンテキスト (セキュリティコンテキスト、権限を借用したユーザー、および呼び出し元のコンテキスト) がキャッシュされ Socket ます。The execution context (the security context, the impersonated user, and the calling context) is cached for the asynchronous Socket methods. 特定のコンテキスト (特定の非同期メソッド、特定のインスタンス、および特定のコールバック) を初めて使用した後 Socket Socket 、そのコンテキストを使用すると、パフォーマンスが向上します。After the first use of a particular context (a specific asynchronous Socket method, a specific Socket instance, and a specific callback), subsequent uses of that context will see a performance improvement.

適用対象