ot::net
class ServerSocket
#include "ot/net/ServerSocket.h"
Handles incoming TCP/IP connections.
The ServerSocket class contains the methods needed to write a portable TCP/IP server.
In general, a TCP/IP server listens for incoming network requests on a well-known IP address and port number. When a connection request is received, the ServerSocket makes this connection available to the server program as a new Socket. The new Socket represents a two-way (full-duplex) connection with the client, with an InputStream for the data flowing from the client to the server and an OutputStream going the other way.
In common with normal socket programming, the life-cycle of a ServerSocket follows this basic course:-
-
bind() to an IP-address/port number and listen for incoming connections
-
accept() a connection request
-
deal with the request, or pass the created Socket to another Thread or process to be dealt with
-
return to step 2 for the next client connection request
The actual work of the ServerSocket is performed by an instance of the SocketImpl class. Instances of SocketImpl are created using a factory class: SocketImplFactory. An application can change the socket factory that creates the socket implementation by calling SetSocketImplFactory() on this class.
Constructor/Destructor Summary |
ServerSocket()
Constructs a ServerSocket that is not bound to an IP-address or port number. |
ServerSocket(int port)
Constructs a ServerSocket that is bound to the port number port. |
ServerSocket(int port, int backlog)
Constructs a ServerSocket that is bound to the port number port. |
ServerSocket(int port, int backlog, InetAddress* pBindAddr)
Constructs a ServerSocket that is bound to the port number port and the local IP-address pBindAddr. |
Method Summary
|
virtual RefPtr< Socket > |
accept()
Returns a new Socket object representing a client connection to the server. |
virtual void |
bind(int port)
Binds this socket to the port number port. |
virtual void |
bind(int port, int backlog)
Binds this socket to the port number port. |
virtual void |
bind(int port, int backlog, InetAddress* pBindAddr)
Binds this socket to the port number port and the local IP-address pBindAddr. |
virtual void |
close()
Closes the SocketImpl socket wrapped by this ServerSocket. |
virtual RefPtr< InetAddress > |
getInetAddress() const
Returns an InetAddress object representing the local IP-address to which this ServerSocket is bound. |
virtual int |
getLocalPort() const
Returns the number of the local port on which this ServerSocket is listening. |
virtual size_t |
getReceiveBufferSize() const
Returns the value of the SO_RCVBUF option for this ServerSocket. |
virtual bool |
getReuseAddress() const
Tests if the SO_REUSEADDR option is enabled. |
static RefPtr< SocketImplFactory > |
GetSocketImplFactory()
Returns the single instance of SocketImplFactory that has been registered with ServerSocket for the application. |
virtual size_t |
getSoTimeout() const
Returns the timeout value for this ServerSocket. |
protected void |
implAccept(Socket* pSocket)
Implements accept(). |
virtual bool |
isBound() const
Returns the binding state of the ServerSocket. |
virtual void |
setReceiveBufferSize(size_t size)
Sets the value of the SO_RCVBUF option for this ServerSocket. |
virtual void |
setReuseAddress(bool bEnable)
Sets the SO_REUSEADDR option for this ServerSocket. |
static void |
SetSocketImplFactory(SocketImplFactory* pFac)
Registers a single instance of a ServerSocketImplFactory to act as the factory for creating new SocketImpl instances for use by ServerSockets. |
virtual void |
setSoTimeout(size_t timeoutMS)
Sets the timeout value for this ServerSocket. |
virtual String |
toString() const
Returns a string representation of this ServerSocket. |
Constructor/Destructor Detail |
ServerSocket
ServerSocket()
-
Constructs a ServerSocket that is not bound to an IP-address or port number.
Before this ServerSocket can be used to accept() incoming connection requests, bind() must be called.
Use this constructor when you need to set options that must be set before calling bind() such as setReuseAddress() and setReceiveBufferSize().
- Exceptions:
SocketException
-
if an error occurs whilst creating the socket.
- See also:
-
bind() , isBound()
ServerSocket
ServerSocket(int port)
-
Constructs a ServerSocket that is bound to the port number port.
The maximum queue length for incoming connection requests is set to a default value. If a connection request arrives when the queue is full, the request is refused.
- Parameters:
port
-
the port number to bind to. If the port number is zero the system will assign an unused port number.
- Exceptions:
SocketException
-
if an error occurs whilst creating the socket.
BindException
-
if an error occurs whilst binding to the requested port.
ServerSocket
ServerSocket(int port,
int backlog)
-
Constructs a ServerSocket that is bound to the port number port.
The maximum queue length for incoming connection requests is set to backlog. If a connection request arrives when the queue is full, the request is refused.
- Parameters:
port
-
the port number to bind to. If the port number is zero the system will assign an unused port number.
backlog
-
the maximum queue length for pending connection requests.
- Exceptions:
SocketException
-
if an error occurs whilst creating the socket.
BindException
-
if an error occurs whilst binding to the requested port.
ServerSocket
ServerSocket(int port,
int backlog,
InetAddress* pBindAddr)
-
Constructs a ServerSocket that is bound to the port number port and the local IP-address pBindAddr.
The maximum queue length for incoming connection requests is set to backlog. If a connection request arrives when the queue is full, the request is refused.
- Parameters:
port
-
the port number to bind to. If the port number is zero the system will assign an unused port number.
backlog
-
the maximum queue length for pending connection requests.
pBindAddr
-
a pointer to an InetAddress representing the IP-address of a local network interface on which to listen for incoming requests.
- Exceptions:
SocketException
-
if an error occurs whilst creating the socket.
BindException
-
if an error occurs whilst binding to the requested port and IP-address.
NullPointerException
-
if pBindAddr is null.
accept
virtual RefPtr< Socket > accept()
-
Returns a new Socket object representing a client connection to the server.
accept() blocks until a connection request is received or the timeout value specified with setSoTimeout() is exceeded.
Cancelling an active accept call
The only portable way to stop a thread that's in an accept() loop is to poll for completion by setting a reasonably short timeout value with setSoTimeout().
On some platforms, calling close() on the ServerSocket from another thread will force the accept() to abort immediately and throw a SocketException. Unfortunately this behaviour is not guaranteed on all platforms, so does not present a portable solution. On some platforms, if the socket is a blocking socket, a close() call will block until the next connection request is received. This is rarely the desired outcome.
- Returns:
-
A new Socket representing a two-way connection with the client.
- Exceptions:
InterruptedIOException
-
if a network connection request is not received within the time limit set by an earlier call to setSoTimeout().
SocketException
-
if an error occurs on the underlying socket.
- See also:
-
setSoTimeout()
bind
virtual void bind(int port)
-
Binds this socket to the port number port.
The maximum queue length for incoming connection requests is set to a default value. If a connection request arrives when the queue is full, the request is refused.
- Parameters:
port
-
the port number to bind to. If the port number is zero the system will assign an unused port number.
- Exceptions:
SocketException
-
if an error occurs whilst obtaining the local port number if a port number of zero was provided.
BindException
-
if an error occurs whilst binding to the requested port.
bind
virtual void bind(int port,
int backlog)
-
Binds this socket to the port number port.
The maximum queue length for incoming connection requests is set to backlog. If a connection request arrives when the queue is full, the request is refused.
- Parameters:
port
-
the port number to bind to. If the port number is zero the system will assign an unused port number.
backlog
-
the maximum queue length for pending connection requests.
- Exceptions:
SocketException
-
if an error occurs whilst obtaining the local port number if a port number of zero was provided.
BindException
-
if an error occurs whilst binding to the requested port.
bind
virtual void bind(int port,
int backlog,
InetAddress* pBindAddr)
-
Binds this socket to the port number port and the local IP-address pBindAddr.
The maximum queue length for incoming connection requests is set to backlog. If a connection request arrives when the queue is full, the request is refused.
- Parameters:
port
-
the port number to bind to. If the port number is zero the system will assign an unused port number.
backlog
-
the maximum queue length for pending connection requests.
pBindAddr
-
a pointer to an InetAddress representing the IP-address of a local network interface on which to listen for incoming requests.
- Exceptions:
SocketException
-
if an error occurs whilst obtaining the local port number if a port number of zero was provided.
BindException
-
if an error occurs whilst binding to the requested port and IP-address.
NullPointerException
-
if pBindAddr is null
close
virtual void close()
-
Closes the SocketImpl socket wrapped by this ServerSocket.
Note that on some platforms close() is implemented as a blocking call that may not return until the socket has been successfully closed. If close() is called by a separate thread while a blocking accept() call is active, the close() may not succeed until the next client connection request is received.
- Note:
-
The ServerSocket will be made non-blocking if a timeout value is specified using setSoTimeout().
getInetAddress
virtual RefPtr< InetAddress > getInetAddress() const
-
Returns an InetAddress object representing the local IP-address to which this ServerSocket is bound.
- Returns:
-
the bound InetAddress.
getLocalPort
virtual int getLocalPort() const
-
Returns the number of the local port on which this ServerSocket is listening.
- Returns:
-
the bound port number.
getReceiveBufferSize
virtual size_t getReceiveBufferSize() const
-
Returns the value of the SO_RCVBUF option for this ServerSocket.
The value of the SO_RCVBUF is used by the underlying sockets implementation to negotiate the receive buffer size that will be used for Sockets accepted from this ServerSocket.
- Returns:
-
the value of the SO_RCVBUF option for this ServerSocket.
getReuseAddress
virtual bool getReuseAddress() const
-
Tests if the SO_REUSEADDR option is enabled.
- Returns:
-
true if the SO_REUSEADDR option is enabled; false otherwise.
GetSocketImplFactory
static RefPtr< SocketImplFactory > GetSocketImplFactory()
-
Returns the single instance of SocketImplFactory that has been registered with ServerSocket for the application.
An instance of SocketImplFactory is automatically created if the application has not already registered one.
The application should not use the returned factory to create instances of SocketImpl. The only reason this method is present is to allow an application or third-party OpenTop extension to chain SocketImplFactories together.
- Returns:
-
The SocketImplFactory used for creating instances of SocketImpl for ServerSockets.
getSoTimeout
virtual size_t getSoTimeout() const
-
Returns the timeout value for this ServerSocket.
This represents the maximum duration that a call to accept() will wait for an incoming connection request before timing-out.
A value of zero indicates infinity (i.e. no timeout).
- Returns:
-
the timeout value (in milliseconds).
implAccept
protected void implAccept(Socket* pSocket)
-
Implements accept().
Derived classes that have overridden accept() may call this function to implement the accept logic.
- Parameters:
pSocket
-
a pointer to a new Socket created by accept().
isBound
virtual bool isBound() const
-
Returns the binding state of the ServerSocket.
- Returns:
-
true if this ServerSocket has been bound; false otherwise.
- See also:
-
bind()
setReceiveBufferSize
virtual void setReceiveBufferSize(size_t size)
-
Sets the value of the SO_RCVBUF option for this ServerSocket.
The SO_RCVBUF option is used by the underlying sockets implementation as the proposed buffer size that will be used for Sockets accepted from this ServerSocket.
Even though the receive buffer belongs to sockets accepted from this ServerSocket, the child sockets inherit the value of SO_RCVBUF from the listening ServerSocket because TCP will negotiate the buffer size during the 3-way handshake which occurs before the accept() function returns.
This method must be called before bind(), so should be used in conjunction with the default ServerSocket() constructor.
setReuseAddress
virtual void setReuseAddress(bool bEnable)
-
Sets the SO_REUSEADDR option for this ServerSocket.
This method must be called before bind(), so should be used in conjunction with the default ServerSocket() constructor.
- Parameters:
bEnable
-
enables SO_REUSEADDR when true, disables it otherwise
SetSocketImplFactory
static void SetSocketImplFactory(SocketImplFactory* pFac)
-
Registers a single instance of a ServerSocketImplFactory to act as the factory for creating new SocketImpl instances for use by ServerSockets.
The ServerSocket shares ownership of the passed factory by incrementing the reference count. This ensures the factory is not destroyed while it is still needed. The reference count is decremented at system termination or when another SocketImplFactory is registered.
- Parameters:
pFac
-
pointer to the SocketImplFactory to be registered.
- Multi-threaded considerations:
-
Can safely be called from multiple concurrent threads.
setSoTimeout
virtual void setSoTimeout(size_t timeoutMS)
-
Sets the timeout value for this ServerSocket.
For ServerSocket, the timeout value controls the length of time that calls to accept() will block while waiting for a client connection request.
- Parameters:
timeoutMS
-
the timeout value in milliseconds. A value of zero indicates infinity (i.e. no timeout).
- See also:
-
accept()
toString
virtual String toString() const
-
Returns a string representation of this ServerSocket.
- Returns:
-
a string representation of this ServerSocket.
Found a bug or missing feature? Please email us at support@elcel.com