System.Net.Sockets.TcpListener Class

Summary

Listens for connections from TCP network clients.

C# Syntax:

public class TcpListener

The TcpListener class builds upon the Socket class to provide TCP services at a higher level of abstraction. You can use a TcpListener to listen for connections from TCP clients. Application level protocols such as FTP and HTTP are built on the TcpListener class.

You can create an instance of the TcpListener class by providing one of the following constructor argument lists:

• An IPEndPoint containing your local IP address and port number.
• Your IP address and port number.
• Just your port number. In this case, the default network interface will be used.

Use the TcpListener.Start property to begin listening for incoming connection requests. Employ the TcpListener.Pending method to determine if connections are pending. Use TcpListener.AcceptSocket to retrieve a Socket, or TcpListener.AcceptTcpClient to retrieve a TcpClient used for facilitating communication with the remote machine. Finally, use TcpListener.Stop to close the underlying listening Socket.

Note Calling TcpListener.Stop only closes the Socket used to listen for incoming connections. You must close any instances returned from TcpListener.AcceptSocket or TcpListener.AcceptTcpClient as well.

The following example creates a TcpListener on port 13 that responds to an incoming connection with the current date and time, and then exits.

              const int portNumber = 13;
		TcpListener tcpListener = new TcpListener(portNumber);

		tcpListener.Start();

              Console.WriteLine("Waiting for a connection....");
                
              try{
              
                   //Accept the pending client connection and return a TcpClient initialized for communication.
                   TcpClient tcpClient = tcpListener.AcceptTcpClient();
		     Console.WriteLine("Connection accepted.");

		     NetworkStream networkStream = tcpClient.GetStream();

                   string responseString = "You have successfully connected to me";

                   Byte[] sendBytes = Encoding.ASCII.GetBytes(responseString);
                   networkStream.Write(sendBytes, 0, sendBytes.Length);

                   Console.WriteLine("Message Sent /> : " + responseString);
                   
               //Any communication with the remote client using the TcpClient can go here.
               //
               ////////

               //Close TcpListener and TcpClient.
               tcpClient.Close();
	        tcpListener.Stop();

               }
               catch (Exception e) {
			        Console.WriteLine(e.ToString());
	    	 }

    

System.Net.Sockets Namespace | TcpClient

System.Net.Sockets.TcpListener Member List:

Public Constructors

ctor #1	Overloaded: .ctor(int port) Initializes a new instance of the TcpListener class that listens on the specified port.
ctor #2	Overloaded: .ctor(IPEndPoint localEP) Initializes a new instance of the TcpListener class with the specified local endpoint.
ctor #3	Overloaded: .ctor(IPAddress localaddr, int port) Initializes a new instance of the TcpListener class that listens to the specified IP address and port.

Public Properties

LocalEndpoint

Read-only Gets the underlying EndPoint of the current TcpListener.

Public Methods

AcceptSocket	Accepts a pending connection request.
AcceptTcpClient	Accepts a pending connection request
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.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Pending	Determines if there are pending connection requests.
Start	Starts listening to network requests.
Stop	Closes the listener.
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-only Gets a value that indicates whether TcpListener is actively listening for client connections.
Server	Read-only Gets the underlying network Socket.

Protected Methods

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.TcpListener

System.Net.Sockets.TcpListener Member Details

Summary

Initializes a new instance of the TcpListener class that listens on the specified port.

C# Syntax:

public TcpListener(    int port );

port

The port on which to listen. If this number is 0, the system will assign an open port.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The port parameter is not between IPEndPoint.MinPort and IPEndPoint.MaxPort.

The port parameter specifies the local port number on which you intend to listen. When you call TcpListener.Start, TcpListener uses the default network interface to listen for connections on the specified port.

The following example creates an instance of the TcpListener class using a local port number.

        //Creates an instance of the TcpListener class by providing a local port number.  

        try{
            TcpListener tcpListener = new TcpListener(13);
        }
        catch ( Exception e ){
            Console.WriteLine( e.ToString());
        }


    

Return to top

Summary

Initializes a new instance of the TcpListener class with the specified local endpoint.

C# Syntax:

public TcpListener(    IPEndPoint localEP );

localEP

The local endpoint to which to bind the listener 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. If you call the TcpListener.Start method, TcpListener will listen for connections on localEp.

The following example creates an instance of the TcpListener class. using the local endpoint.

        //Creates an instance of the TcpListener class by providing a local endpoint.

        IPAddress ipAddress = Dns.Resolve(Dns.GetHostName()).AddressList[0];
        IPEndPoint ipLocalEndPoint = new IPEndPoint(ipAddress, 11000); 

        try{
            TcpListener tcpListener = new TcpListener(ipLocalEndPoint);
        }
        catch ( Exception e ){
            Console.WriteLine( e.ToString());
        }

    

Return to top

Summary

Initializes a new instance of the TcpListener class that listens to the specified IP address and port.

C# Syntax:

public TcpListener(    IPAddress localaddr,    int port );

localaddr

The local IP address.

port

The port on which to listen.

Exceptions

Exception Type	Condition
ArgumentNullException	The localaddr parameter is null.
ArgumentOutOfRangeException	The port parameter is not between IPEndPoint.MinPort and IPEndPoint.MaxPort.

TcpListener initializes its underlying IPEndPoint using the specified IP address and port number. If you call the TcpListener.Start method, TcpListener listens for connections using the underlying IPEndPoint.

The following example creates an instance of the TcpListener class using a local IP address and port number.

        //Creates an instance of the TcpListener class by providing a local IP address and port number.

        IPAddress ipAddress = Dns.Resolve("localhost").AddressList[0];

        try{
            TcpListener tcpListener =  new TcpListener(ipAddress, 13);    
        }
        catch ( Exception e){
            Console.WriteLine( e.ToString());
        }
    

    

Return to top

Summary

Gets a value that indicates whether TcpListener is actively listening for client connections.

C# Syntax:

protected bool Active {get;}

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

Note TcpClient.Active can be used to avoid redundant TcpListener.Start attempts.

Return to top

Summary

Gets the underlying EndPoint of the current TcpListener.

C# Syntax:

public EndPoint LocalEndpoint {get;}

You can use TcpListener.LocalEndpoint if you want to identify the local network interface and port number being used to listen for incoming client connection requests.

Note To obtain address and port information, you must explicitly cast TcpListener.LocalEndpoint to return an IPEndPoint. You can then use the various methods within IPEndPoint to retrieve the desired information.

Return to top

Summary

Gets the underlying network Socket.

C# Syntax:

protected Socket Server {get;}

TcpListener creates a Socket to listen for incoming client connection requests. Classes deriving from TcpListener can use this property to get this Socket. Use the underlying Socket returned by the TcpListener.Server property if you require access beyond that which TcpListener provides.

Note TcpListener.Server only returns the Socket used to listen for incoming client connection requests. Use the TcpListener.AcceptSocket method to accept a pending connection request and obtain a Socket for sending and receiving data. You can also use the TcpListener.AcceptTcpClient method to accept a pending connection request and obtain a TcpClient for sending and receiving data.

Return to top

Summary

Accepts a pending connection request.

C# Syntax:

public Socket AcceptSocket();

Return Value:

A Socket used to send and receive data.

Exceptions

Exception Type	Condition
InvalidOperationException	The listener has not been started with a call to TcpListener.Start.

TcpListener.AcceptSocket returns a Socket that you can use to send and receive data. This Socket is initialized with the IP address and port number of the remote machine. You can use any of the Socket.Send and Socket.Receive methods available in the Socket class to communicate with the remote machine.

Note When you finish using the Socket, be sure to call its Socket.Close method.

Note If your application is relatively simple, consider using the TcpListener.AcceptTcpClient method rather than TcpListener.AcceptSocket. TcpClient provides you with simple methods for sending and receiving data over a network.

In the following example, TcpListener.AcceptSocket is used to return a Socket. This Socket is used to communicate with the newly connected client.

	       
              // Accepts the pending client connection and returns a socket for communciation.
               Socket socket = tcpListener.AcceptSocket();
		 Console.WriteLine("Connection accepted.");

               string responseString = "You have successfully connected to me";

               //Forms and sends a response string to the connected client.
               Byte[] sendBytes = Encoding.ASCII.GetBytes(responseString);
               int i = socket.Send(sendBytes);
               Console.WriteLine("Message Sent /> : " + responseString);

    

Return to top

Summary

Accepts a pending connection request

C# Syntax:

public TcpClient AcceptTcpClient();

Return Value:

A TcpClient used to send and receive data.

Exceptions

Exception Type	Condition
InvalidOperationException	The listener has not been started with a call to TcpListener.Start.

TcpListener.AcceptTcpClient returns a TcpClient that you can use to send and receive data. Use TcpClient.GetStream to obtain the underlying NetworkStream of the TcpClient. NetworkStream inherits from Stream, which provides a rich collection of methods and properties for network communications.

Note When you are through with the returned TcpClient, be sure to call it's TcpClient.Close method.

Note If you want greater flexibility than a TcpClient offers, consider using TcpListener.AcceptSocket.

In the following example, TcpListener.AcceptTcpClient is used to return a TcpClient. This TcpClient is used to communicate with the newly connected client.

	       
              // Accepts the pending client connection and returns a socket for communciation.
               Socket socket = tcpListener.AcceptSocket();
		 Console.WriteLine("Connection accepted.");

               string responseString = "You have successfully connected to me";

               //Forms and sends a response string to the connected client.
               Byte[] sendBytes = Encoding.ASCII.GetBytes(responseString);
               int i = socket.Send(sendBytes);
               Console.WriteLine("Message Sent /> : " + responseString);

    

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:

~TcpListener();

The finalizer for the TcpListener class calls the TcpListener.Stop method to free the underlying 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

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

Summary

Determines if there are pending connection requests.

C# Syntax:

public bool Pending();

Return Value:

true if connections are pending; otherwise, false.

Exceptions

Exception Type	Condition
InvalidOperationException	The listener has not been started with a call to TcpListener.Start.

TcpListener.Pending polls for the underlying Socket to determine if there are pending connections.

Return to top

Summary

Starts listening to network requests.

C# Syntax:

public void Start();

Exceptions

Exception Type	Condition
SocketException	An error occurs while opening the network socket.

TcpListener.Start initializes the underlying Socket. After this initialization, TcpListener.Start does the following:

• Binds the underlying Socket using the underlying IPEndPoint.
• Begins listening for client connections by calling the Socket.Listen method of the underlying Socket.

This method only listens for connection requests. To detect these requests, you can use one of the following:

• The TcpListener.Pending method to detect incoming connection requests
• The TcpListener.AcceptSocket method or the TcpListener.AcceptTcpClient method to block until a connection request arrives.

The following example demonstrates how TcpListener.Start is used to listen for incoming client connection attempts.

              const int portNumber = 13;
		TcpListener tcpListener = new TcpListener(portNumber);

		tcpListener.Start();

              Console.WriteLine("Waiting for a connection....");
                
              try{
              
                   //Accept the pending client connection and return a TcpClient initialized for communication.
                   TcpClient tcpClient = tcpListener.AcceptTcpClient();
		     Console.WriteLine("Connection accepted.");

		     NetworkStream networkStream = tcpClient.GetStream();

                   string responseString = "You have successfully connected to me";

                   Byte[] sendBytes = Encoding.ASCII.GetBytes(responseString);
                   networkStream.Write(sendBytes, 0, sendBytes.Length);

                   Console.WriteLine("Message Sent /> : " + responseString);
                   
               //Any communication with the remote client using the TcpClient can go here.
               //
               ////////

               //Close TcpListener and TcpClient.
               tcpClient.Close();
	        tcpListener.Stop();

               }
               catch (Exception e) {
			        Console.WriteLine(e.ToString());
	    	 }

    

Return to top

Summary

Closes the listener.

C# Syntax:

public void Stop();

Exceptions

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

TcpListener.Stop closes the listener.

The following example demonstrates using TcpListener.Stop to close the underlying Socket.

              const int portNumber = 13;
		TcpListener tcpListener = new TcpListener(portNumber);

		tcpListener.Start();

              Console.WriteLine("Waiting for a connection....");
                
              try{
              
                   //Accept the pending client connection and return a TcpClient initialized for communication.
                   TcpClient tcpClient = tcpListener.AcceptTcpClient();
		     Console.WriteLine("Connection accepted.");

		     NetworkStream networkStream = tcpClient.GetStream();

                   string responseString = "You have successfully connected to me";

                   Byte[] sendBytes = Encoding.ASCII.GetBytes(responseString);
                   networkStream.Write(sendBytes, 0, sendBytes.Length);

                   Console.WriteLine("Message Sent /> : " + responseString);
                   
               //Any communication with the remote client using the TcpClient can go here.
               //
               ////////

               //Close TcpListener and TcpClient.
               tcpClient.Close();
	        tcpListener.Stop();

               }
               catch (Exception e) {
			        Console.WriteLine(e.ToString());
	    	 }

    

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