Socket.BeginSendFile メソッド

定義

接続された Socket オブジェクトに、ファイルを非同期的に送信します。Sends a file 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.

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);
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 オブジェクト。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. まず、ファイル ".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.

このメソッドは、Windows Sockets 2 API の TransmitFile 関数を使用します。This method uses the TransmitFile function found in the Windows Sockets 2 API. TransmitFile 関数とそのフラグの詳細については、 Windows Socketsのドキュメントを参照してください。For more information about the TransmitFile function and its flags, see the Windows Sockets documentation.

BeginSendFile メソッドは、ConnectBeginConnectAccept、または BeginAccept の各メソッドで確立されたリモートホストへの非同期の送信操作を開始します。The BeginSendFile method starts an asynchronous send operation to the remote host established in the Connect,BeginConnect, Accept, or BeginAccept methods. 最初に AcceptBeginAcceptConnect、または BeginConnectを呼び出さない場合、BeginSendFile は例外をスローします。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 delegate パラメーターによって呼び出されるコールバックメソッドを作成します。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. このカスタムオブジェクトのインスタンスを、state パラメーターを使用して BeginSendFile メソッドに渡します。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を呼び出すと、システムは別のスレッドを使用して指定されたコールバックメソッドを実行し、Socket がファイル全体を送信するか例外をスローするまで、EndSendFile にブロックします。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.

接続指向プロトコルを対象としていますが、最初に Connect または BeginConnect メソッドを呼び出して既定のリモートホストを確立した場合、コネクションレスプロトコルでも BeginSendFile 機能します。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. この場合、データグラムは送信されず、BeginSendFileSocketException 例外をスローします。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, 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);
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 オブジェクト。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.

次のコード例では、非同期通信用のソケットを作成して接続し、リモートホストへのファイル "test.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();
    }

注釈

このオーバーロードには、送信するファイルの名前と 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 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. このパラメーターの使用方法の詳細については、「TransmitFileOptions」を参照してください。For more information about how to use this parameter, see TransmitFileOptions.

このメソッドは、Windows Sockets 2 API の TransmitFile 関数を使用します。This method uses the TransmitFile function found in the Windows Sockets 2 API. TransmitFile 関数とそのフラグの詳細については、 Windows Socketsのドキュメントを参照してください。For more information about the TransmitFile function and its flags, see the Windows Sockets documentation.

BeginSendFile メソッドは、ConnectBeginConnectAccept、または BeginAccept の各メソッドで確立されたリモートホストへの非同期の送信操作を開始します。The BeginSendFile method starts an asynchronous send operation to the remote host established in the Connect, BeginConnect, Accept, or BeginAccept methods. 最初に AcceptBeginAcceptConnect、または BeginConnectを呼び出さない場合、BeginSendFile は例外をスローします。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 delegate パラメーターによって呼び出されるコールバックメソッドを作成します。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. このカスタムオブジェクトのインスタンスを、state パラメーターを使用して BeginSendFile メソッドに渡します。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を呼び出すと、システムは別のスレッドを使用して指定されたコールバックメソッドを実行し、Socket がファイル全体を送信するか例外をスローするまで、EndSendFile にブロックします。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.

接続指向プロトコルを対象としていますが、最初に Connect または BeginConnect メソッドを呼び出して既定のリモートホストを確立した場合、コネクションレスプロトコルでも BeginSendFile 機能します。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. この場合、データグラムは送信されず、BeginSendFileSocketException 例外をスローします。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.

適用対象