System.Net.Sockets.TcpClient Class

Summary

Provides client connections for TCP network services.

C# Syntax:

public class TcpClient : IDisposable

The TcpClient class builds upon the Socket class to provide TCP services at a higher level of abstraction. TcpClient provides simple methods for connecting, sending, and receiving data over a network. You can connect with a remote host using one of the following two ways:

• Create an instance of the TcpClient class using either no parameters, or using a local IPEndPoint, and then call one of the three available TcpClient TcpClient.Connect methods.
• Create an instance of the TcpClient class using the host name and port number of the device to which you intend to connect. This constructor will automatically establish your connection.

To send and receive data, use the TcpClient.GetStream method to obtain a NetworkStream that can send and receive data on the underlying connected Socket. After utilizing the write and read methods available through the NetworkStream, use the TcpClient.Close method to release all resources associated with the TcpClient.

TcpClient provides a set of convenient properties that you can use to adjust common Socket settings. If you need to set Socket options not addressed with these properties, use the TcpClient.Client property to retrieve the underlying Socket.

Notes to inheritors: You can use the Socket accessed through the TcpClient.Client to facilitate any functionality not available using the simplified interface of TcpClient property. Specifically, you can call Socket.SetSocketOption to set your desired option.

The following example establishes a TcpClient connection using the host name www.contoso.com on port 11000. You use the underlying NetworkStream instance to send and receive simple string statements.

TcpClient tcpClient = new TcpClient();
    try{
        tcpClient.Connect("www.contoso.com", 11000);
        NetworkStream networkStream = tcpClient.GetStream();

        if(networkStream.CanWrite && networkStream.CanRead){

            // Does a simple write.
            Byte[] sendBytes = Encoding.ASCII.GetBytes("Is anybody there");
            networkStream.Write(sendBytes, 0, sendBytes.Length);
      
            // Reads the NetworkStream into a byte buffer.
            byte[] bytes = new byte[tcpClient.ReceiveBufferSize];
            networkStream.Read(bytes, 0, (int) tcpClient.ReceiveBufferSize);
  
           // Returns the data received from the host to the console.
           string returndata = Encoding.ASCII.GetString(bytes);
           Console.WriteLine("This is what the host returned to you: " + returndata);

          }
          else if (!networkStream.CanRead){
              Console.WriteLine("You can not write data to this stream");
              tcpClient.Close();
          }
          else if (!networkStream.CanWrite){             
              Console.WriteLine("You can not read data from this stream");
              tcpClient.Close();
          }
       }
       catch (Exception e ) {
                  Console.WriteLine(e.ToString());
       }

    

System.Net.Sockets Namespace | TcpListener | NetworkStream | MSDN: tcpudp

System.Net.Sockets.TcpClient Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the TcpClient class.
ctor #2	Overloaded: .ctor(IPEndPoint localEP) Initializes a new instance of TcpClient bound to the specified local endpoint.
ctor #3	Overloaded: .ctor(string hostname, int port) Initializes a new instance of the TcpClient class and connects to the specified port on the specified host.

Public Properties

LingerState	Read-write Gets or sets information about the sockets linger time.
NoDelay	Read-write Gets or sets a value that enables a delay when send or receive buffers are not full.
ReceiveBufferSize	Read-write Gets or sets the size of the receive buffer.
ReceiveTimeout	Read-write Gets or sets the amount of time a TcpClient will wait to receive data once initiated.
SendBufferSize	Read-write Gets or sets the size of the send buffer.
SendTimeout	Read-write Gets or sets the amount of time a TcpClient will wait to receive confirmation after you initiate a send.

Public Methods

Close	Closes the TCP connection.
Connect	Overloaded: Connect(IPEndPoint remoteEP) Connects the client to a remote TCP host using the specified remote network endpoint.
Connect	Overloaded: Connect(IPAddress address, int port) Connects the client to a remote TCP host using the specified IP address and port number.
Connect	Overloaded: Connect(string hostname, int port) Connects the client to the specified port on the specified host.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetStream	Returns the stream used to send and receive data.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Properties

Active	Read-write Gets or set a value that indicates whether a connection has been made.
Client	Read-write Gets or sets the underlying Socket.

Protected Methods

Dispose	Releases the unmanaged resources used by the TcpClient and optionally releases the managed resources.
Finalize	Overridden: Frees resources used by the TcpClient class.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Net.Sockets.TcpClient

System.Net.Sockets.TcpClient Member Details

Summary

Initializes a new instance of the TcpClient class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public TcpClient();

The default constructor initializes a new TcpClient. You must call the TcpClient.Connect method to establish a remote host connection.

The following example demonstrates how to use the default constructor to create a new TcpClient.

           //Creates a TCPClient using the default constructor.
           TcpClient tcpClientC = new TcpClient();

    

Return to top

Summary

Initializes a new instance of TcpClient bound to the specified local endpoint.

C# Syntax:

public TcpClient(    IPEndPoint localEP );

localEP

The IPEndPoint to which you bind the TCP Socket.

Exceptions

Exception Type	Condition
ArgumentNullException	The localEP parameter is null.

The localEP parameter specifies the local IPEndPoint. This constructor creates an underlying socket and binds that socket to localEp. You must call the TcpClient.Connect method to establish a remote host connection.

Note Use this constructor if you want to specify which local network interface (IP address), and port number to use when establishing a remote host connection.

The following example demonstrates how to create an instance of the TcpClient class using a local endpoint.

           //Creates a TCPClient using a localend point.
           IPAddress ipAddress = Dns.Resolve(Dns.GetHostName()).AddressList[0];
           IPEndPoint ipLocalEndPoint = new IPEndPoint(ipAddress, 11000);
           try{
                    TcpClient tcpClientA = new TcpClient(ipLocalEndPoint);
           }  
           catch (Exception e ) {
                     Console.WriteLine(e.ToString());
             }

    

Return to top

Summary

Initializes a new instance of the TcpClient class and connects to the specified port on the specified host.

C# Syntax:

public TcpClient(    string hostname,    int port );

hostname

DNS name of the remote host to which you intend to connect.

port

Port number of the remote host to which you intend to connect.

Exceptions

Exception Type	Condition
ArgumentNullException	The hostname parameter is null.
ArgumentOutOfRangeException	The port parameter is not between IPEndPoint.MinPort and IPEndPoint.MaxPort.
SocketException	An error occurred while connecting to the remote host.

This constructor initializes a new TcpClient and establishes a remote host connection by calling TcpClient.Connect using the provided hostname and port parameters. This constructor allows you to initialize, resolve the DNS host name, and connect in one convenient step.

The following example demonstrates how to create an instance of TcpClient class using a host name and port number.

           //Creates a TCPClient using hostname and port.
           try{
                TcpClient tcpClientB = new TcpClient("www.contoso.com", 11000);
           }
           catch (Exception e ) {
                      Console.WriteLine(e.ToString());
           }

    

Return to top

Summary

Gets or set a value that indicates whether a connection has been made.

C# Syntax:

protected bool Active {get; set;}

Classes deriving from TcpClient can use this property to keep track of the underlying Socket connection state.

Note TcpClient.Active can be used to avoid redundant connection attempts, or to validate operations that require a particular connection state as a pre condition.

The following example demonstrates a derived class using the protected property TcpClient.Active. In this example, MyTcpClientDerivedClass verifies that the connection is active before obtaining the underlying Socket.

// This derived class demonstrates the use of three protected methods belonging to the TcpClient class
public class MyTcpClientDerivedClass : TcpClient{

// Constructor for the derived class.
public MyTcpClientDerivedClass() : base(){
}
public void UsingProtectedMethods(){

  // Uses the protected 'Active' property belonging to the TcpClient base class 
  // to determine if a connection is established. 
  if (this.Active){
      // Calls the protected 'Client' property belonging to the TcpClient base class.
      Socket s = this.Client;
      // Uses the Socket returned by Client to set an option that is not available using TcpClient.
      s.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.Broadcast, 1);
  }
  // To free all resources, calls the protected virtual method Dispose belonging to the TcpClient base class.
 this.Dispose(true);
 GC.SuppressFinalize(this);

}

}

    

Return to top

Summary

Gets or sets the underlying Socket.

C# Syntax:

protected Socket Client {get; set;}

TcpClient creates a Socket to send and receive data over a network. Classes deriving from TcpClient can use this property to get or set this Socket. Use the underlying Socket returned from TcpClient.Client, if you require access beyond that which TcpClient provides. You can also use TcpClient.Client to set the underlying Socket to an existing Socket. This might be useful if you want to take advantage of the simplicity of TcpClient using a pre-existing Socket.

The following example demonstrates a derived class using the protected property TcpClient.Client. In this example, MyTcpClientDerivedClass obtains the underlying socket to enable broadcasting.

// This derived class demonstrates the use of three protected methods belonging to the TcpClient class
public class MyTcpClientDerivedClass : TcpClient{

// Constructor for the derived class.
public MyTcpClientDerivedClass() : base(){
}
public void UsingProtectedMethods(){

  // Uses the protected 'Active' property belonging to the TcpClient base class 
  // to determine if a connection is established. 
  if (this.Active){
      // Calls the protected 'Client' property belonging to the TcpClient base class.
      Socket s = this.Client;
      // Uses the Socket returned by Client to set an option that is not available using TcpClient.
      s.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.Broadcast, 1);
  }
  // To free all resources, calls the protected virtual method Dispose belonging to the TcpClient base class.
 this.Dispose(true);
 GC.SuppressFinalize(this);

}

}

    

Return to top

Summary

Gets or sets information about the sockets linger time.

C# Syntax:

public LingerOption LingerState {get; set;}

This property controls the length of time that the underlying Socket will remain open after a call to TcpClient.Close, when data remains to be sent. If the LingerOption.Enabled property of the LingerOption is true, then data will continue to be sent to the network with a time out of LingerOption.LingerTime seconds. Once the data is sent, or if the time-out expires, the connection is closed and any unsent data is lost. If the LingerOption.Enabled property of the LingerOption is false, then the connection will close, even if data remains to be sent.

The following example sets and gets the sockets linger time.

      // sets the amount of time to linger after closing, using the LingerOption public property.
      LingerOption lingerOption = new LingerOption(true, 10);
      tcpClient.LingerState = lingerOption;

      // gets the amount of linger time set, using the LingerOption public property.
      if (tcpClient.LingerState.LingerTime == 10)
   	    Console.WriteLine("The linger state setting was successfully set to " +
   	    tcpClient.LingerState.LingerTime.ToString());

    

Return to top

Summary

Gets or sets a value that enables a delay when send or receive buffers are not full.

C# Syntax:

public bool NoDelay {get; set;}

When TcpClient.NoDelay is false, TCP does not send a packet over the network until it has collected a significant amount of outgoing data. Because of the amount of overhead in a TCP segment, sending small amounts of data would be very inefficient. However, situations do exist where you might want to send very small amounts of data or expect immediate responses from each packet you send. Your decision should weigh the relative importance of network efficiency versus application requirements.

The following example enables the delay. It then checks the value of TcpClient.NoDelay to verify that it was successfully set.

      // Sends data immediately upon calling NetworkStream.Write.
      tcpClient.NoDelay = true;

      // Determines if the delay is enabled by using the NoDelay property.
      if (tcpClient.NoDelay == true)
   	    Console.WriteLine("The delay was set successfully to " +
   	    tcpClient.NoDelay.ToString());

    

Return to top

Summary

Gets or sets the size of the receive buffer.

C# Syntax:

public int ReceiveBufferSize {get; set;}

The TcpClient.ReceiveBufferSize property gets or sets the number of bytes that you are expecting to store in the receive buffer for each read operation.

Note Setting this property does not limit the amount of data you can store from a single read operation. The receive buffer dynamically grows in size as space is needed to accommodate varying packet sizes. This property simply allows you to save the overhead associated with dynamic reallocation by specifying a buffer size up front.

The following example sets and gets the receive buffer size.

      // sets the receive buffer size using the ReceiveBufferSize public property.
      tcpClient.ReceiveBufferSize = 1024;
   
      // gets the receive buffer size using the ReceiveBufferSize public property.
      if (tcpClient.ReceiveBufferSize == 1024)
   	   Console.WriteLine("The receive buffer was successfully set to " + 
   	   tcpClient.ReceiveBufferSize.ToString());

    

Return to top

Summary

Gets or sets the amount of time a TcpClient will wait to receive data once initiated.

C# Syntax:

public int ReceiveTimeout {get; set;}

The TcpClient.ReceiveTimeout property determines the amount of time a TcpClient will wait to receive data after a read is initiated. This time is measured in milliseconds. The underlying Socket will throw a SocketException if a read is initiated, and the TcpClient.ReceiveTimeout expires.

The following example sets and gets the receive time out.

      // Sets the receive time out using the ReceiveTimeout public property.
      tcpClient.ReceiveTimeout = 5;

      // Gets the receive time out using the ReceiveTimeout public property.
      if (tcpClient.ReceiveTimeout == 5)
   	    Console.WriteLine("The receive time out limit was successfully set " +
   	    tcpClient.ReceiveTimeout.ToString());

    

Return to top

Summary

Gets or sets the size of the send buffer.

C# Syntax:

public int SendBufferSize {get; set;}

The TcpClient.SendBufferSize property gets or sets the number of bytes to store in the send buffer for each send operation.

Note Setting this property does not limit the amount of data you can store for a single send operation. You specify the number of outgoing data bytes when using one of the underlying NetworkStream send operations. TcpClient.SendBufferSize simply allows you to save the overhead associated with dynamic reallocation by specifying a buffer size up front.

The following example sets and gets the send buffer size.

      //sets the send buffer size using the SendBufferSize public property.
      tcpClient.SendBufferSize = 1024;  

      // gets the send buffer size using the SendBufferSize public property.
      if (tcpClient.SendBufferSize == 1024)
          Console.WriteLine("The send buffer was successfully set to " +
           tcpClient.SendBufferSize.ToString());

    

Return to top

Summary

Gets or sets the amount of time a TcpClient will wait to receive confirmation after you initiate a send.

C# Syntax:

public int SendTimeout {get; set;}

After you initiate a send, the underlying Socket returns the number of bytes actually sent to the host. The TcpClient.SendTimeout property determines the amount of time a TcpClient will wait before receiving the number of bytes returned by the Socket class. The underlying Socket will throw a SocketException if a send is initiated and the TcpClient.SendTimeout expires.

The following example sets and gets the TcpClient.SendTimeout value.

      // sets the send time out using the SendTimeout public property.
      tcpClient.SendTimeout = 5;

      // gets the send time out using the SendTimeout public property.
      if (tcpClient.SendTimeout == 5)
           Console.WriteLine("The send time out limit was successfully set " +
   	    tcpClient.SendTimeout.ToString());

    

Return to top

Summary

Closes the TCP connection.

C# Syntax:

public void Close();

Exceptions

Exception Type	Condition
SocketException	An error occurs while closing the socket.

The following example demonstrates closing TcpClient by calling TcpClient.Close.

   // Uses the Close public method to close the network stream and socket.
   tcpClient.Close();

    

Return to top

Summary

Connects the client to a remote TCP host using the specified remote network endpoint.

C# Syntax:

public void Connect(    IPEndPoint remoteEP );

remoteEP

The IP endpoint to which you intend to connect.

Exceptions

Exception Type	Condition
ArgumentNullException	The remoteEp parameter is null.
SocketException	An error occurred while connecting to the remote host.

TcpClient.Connect establishes a TCP connection using the specified network endpoint. Before you call TcpClient.Connect, you must first create an instance of the IPEndPoint class using an IP address and a port number. This is your network endpoint. You can then call TcpClient.Connect and pass the IPEndPoint as its parameter. TcpClient.Connect then establishes a connection with the remote host by calling the Socket.Connect method of the underlying Socket. After establishing a connection, you can use TcpClient.GetStream to obtain the underlying NetworkStream. Use the underlying NetworkStream to send and receive data.

The following example uses an IPEndPoint to connect with a remote host.

   //Uses a remote end point to establish a socket connection.
   TcpClient tcpClient = new TcpClient();
   IPAddress ipAddress = Dns.Resolve("www.contoso.com").AddressList[0];
   IPEndPoint ipEndPoint = new IPEndPoint(ipAddress, 11004);
   try{
   	tcpClient.Connect(ipEndPoint);
   }
   catch (Exception e ) {
              Console.WriteLine(e.ToString());
          }

    

Return to top

Summary

Connects the client to a remote TCP host using the specified IP address and port number.

C# Syntax:

public void Connect(    IPAddress address,    int port );

address

The IP address of the host to which you intend to connect.

port

The port number to which you intend to connect.

Exceptions

Exception Type	Condition
ArgumentNullException	The address parameter is null.
ArgumentOutOfRangeException	The port parameter is not between IPEndPoint.MinPort and IPEndPoint.MaxPort.
SocketException	An error occurred while connecting to the remote host.

TcpClient.Connect establishes a TCP connection using the specified port and IP address by calling the Socket.Connect method of the underlying Socket. After establishing a connection, you can use TcpClient.GetStream to obtain the underlying NetworkStream. Use the underlying NetworkStream to send and receive data.

The following example uses an IP Address and port number to connect with a remote host.

      //Uses the IP address and port number to establish a socket connection.
      TcpClient tcpClient = new TcpClient();
      IPAddress ipAddress = Dns.Resolve("www.contoso.com").AddressList[0];
      try{
          tcpClient.Connect(ipAddress, 11003);
      }
      catch (Exception e ) {
                 Console.WriteLine(e.ToString());
      }

    

Return to top

Summary

Connects the client to the specified port on the specified host.

C# Syntax:

public void Connect(    string hostname,    int port );

hostname

The DNS name of the remote host to which you intend to connect.

port

The port number of the remote host to which you intend to connect.

Exceptions

Exception Type	Condition
ArgumentNullException	The hostname parameter is null.
ArgumentOutOfRangeException	The port parameter is not between IPEndPoint.MinPort and IPEndPoint.MaxPort.
SocketException	An operating system error occurred while accessing the socket.

TcpClient.Connect establishes a TCP connection to the host device by calling the Socket.Connect method of the underlying Socket using the specified hostname and port number. After establishing the connection, you can use TcpClient.GetStream to obtain the underlying NetworkStream. Use the underlying NetworkStream to send and receive data.

The following example uses the host name and port number to connect with a remote host.

     //Uses a host name and port number to establish a socket connection.
    TcpClient tcpClient = new TcpClient();
    try{
        tcpClient.Connect("www.contoso.com", 11002);
    }
    catch (Exception e ) {
               Console.WriteLine(e.ToString());
           }

    

Return to top

Summary

Releases the unmanaged resources used by the TcpClient and optionally releases the managed resources.

C# Syntax:

protected virtual void Dispose(    bool disposing );

disposing

true, to release both managed and unmanaged resources; false, to release only unmanaged resources.

This method is called by the Dispose() method and the Object.Finalize method.Dispose() invokes this method with the disposing parameter set to true. Object.Finalize invokes this method with disposing set to false.

When the disposing parameter is true, this method releases all resources held by any managed objects that this TcpClient references. It does this by invoking the Dispose() method of each referenced object.

Notes to inheritors: Dispose can be called multiple times by other objects. When overriding Dispose(Boolean), be careful not to reference objects that have been previously disposed of in an earlier call to Dispose. For more information about how to implement Dispose(Boolean), see the conceptual topic at MSDN: implementingdisposemethod.

For more information about Dispose and Object.Finalize, see the conceptual topic at MSDN: cleaningupunmanagedresources and the conceptual topic at MSDN: overridingfinalizemethod.

The following example uses a derived class to demonstrate the TcpClient.Dispose method. Specifying true causes both managed and unmanaged resources to be released.

// This derived class demonstrates the use of three protected methods belonging to the TcpClient class
public class MyTcpClientDerivedClass : TcpClient{

// Constructor for the derived class.
public MyTcpClientDerivedClass() : base(){
}
public void UsingProtectedMethods(){

  // Uses the protected 'Active' property belonging to the TcpClient base class 
  // to determine if a connection is established. 
  if (this.Active){
      // Calls the protected 'Client' property belonging to the TcpClient base class.
      Socket s = this.Client;
      // Uses the Socket returned by Client to set an option that is not available using TcpClient.
      s.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.Broadcast, 1);
  }
  // To free all resources, calls the protected virtual method Dispose belonging to the TcpClient base class.
 this.Dispose(true);
 GC.SuppressFinalize(this);

}

}

    

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Frees resources used by the TcpClient class.

C# Syntax:

~TcpClient();

The TcpClient class finalizer calls the TcpClient.Close method to close the TCP connection, the NetworkStream, and the Socket.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns the stream used to send and receive data.

C# Syntax:

public NetworkStream GetStream();

Return Value:

The underlying NetworkStream.

Exceptions

Exception Type	Condition
InvalidOperationException	The TcpClient is not connected to a remote host.
ObjectDisposedException	The TcpClient has been closed.

TcpClient.GetStream returns the underlying NetworkStream used to send and receive data. TcpClient.GetStream creates an instance of the NetworkStream class using the underlying Socket as its constructor parameter. NetworkStream inherits from the Stream, which provides a rich collection of methods and properties used to facilitate network communications.

The following example uses TcpClient.GetStream to obtain the underlying NetworkStream. After obtaining the NetworkStream, it sends and receives using its NetworkStream.Write and NetworkStream.Read methods.

   TcpClient tcpClient = new TcpClient();
   // Uses the GetStream public method to return the NetworkStream.
   try{
       NetworkStream networkStream = tcpClient.GetStream();
       if(networkStream.CanWrite){
           Byte[] sendBytes = Encoding.ASCII.GetBytes("Is anybody there?");
           networkStream.Write(sendBytes, 0, sendBytes.Length);
       }
       else{
           Console.WriteLine("You cannot write data to this stream.");
           tcpClient.Close();
           return;
       }
       if(networkStream.CanRead){
        
         // Reads NetworkStream into a byte buffer.
         byte[] bytes = new byte[tcpClient.ReceiveBufferSize];
         // Read can return anything from 0 to numBytesToRead. 
         // This method blocks until at least one byte is read.
         networkStream.Read(bytes, 0, (int) tcpClient.ReceiveBufferSize);
                
        // Returns the data received from the host to the console.
        string returndata = Encoding.ASCII.GetString(bytes);
        Console.WriteLine("This is what the host returned to you: " + returndata);
       }
       else{
            Console.WriteLine("You cannot read data from this stream.");
            tcpClient.Close();
            return;
       }
  }
   catch (Exception e ) {
                 Console.WriteLine(e.ToString());
          }

    

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page