ot::net
class DatagramSocket
#include "ot/net/DatagramSocket.h"
Provides a Berkeley socket interface for UDP datagram sockets.
A DatagramSocket is an end-point for unreliable (UDP) communication between two or more networked machines.
The DatagramSocket class manages a datagram socket handle which is provided by the underlying operating system. This handle is represented by a SocketDescriptor, which enables OpenTop to close the socket handle when it is no longer required.
When a DatagramSocket is created, it can be bound to a specific local interface by using an appropriate constructor, or it can be bound after construction using the bind() method.
The ability to send and receive broadcast packets is enabled by default for DatagramSockets. This option may be controlled using the setBroadcast() method.
The actual work of the DatagramSocket is performed by an instance of the DatagramSocketImpl class. Instances of DatagramSocketImpl are created using a factory class: DatagramSocketImplFactory. An application can change the factory that creates the DatagramSocket implementation by calling SetDatagramSocketImplFactory() on this class. OpenTop provides a default factory that creates plain DatagramSocketImpl instances which are suitable for most purposes.
- Since:
-
1.3
Constructor/Destructor Summary |
DatagramSocket()
Creates an unbound datagram socket. |
DatagramSocket(int port)
Creates a DatagramSocket and binds it to the specified port on and wildcard address on the local machine. |
DatagramSocket(int port, InetAddress* pLocalAddr)
Creates a DatagramSocket and binds it to the specified interface and port on the local machine. |
Method Summary
|
virtual void |
bind(int port, InetAddress* pLocalAddr)
Binds this datagram socket to a particular local IP address and port. |
virtual void |
close()
Closes the DatagramSocket and releases any system resources associated with it. |
virtual void |
connect(InetAddress* pAddress, int port)
Connects a DatagramSocket to a specified remote address and port. |
protected void |
createDatagramSocketImpl()
|
virtual void |
disconnect()
Disconnects the DatagramSocket from its remote destination. |
virtual bool |
getBroadcast() const
Tests if the SO_BROADCAST option is enabled for this datagram socket. |
protected RefPtr< DatagramSocketImpl > |
getDatagramSocketImpl() const
Returns the DatagramSocketImp object used by this DatagramSocket. |
static RefPtr< DatagramSocketImplFactory > |
GetDatagramSocketImplFactory()
Returns the static object that is the DatagramSocketImplFactory for DatagramSockets. |
virtual RefPtr< InetAddress > |
getInetAddress() const
Returns an InetAddress representing the remote host to which this DatagramSocket is connected. |
virtual RefPtr< InetAddress > |
getLocalAddress() const
Returns an InetAddress representing the local interface to which this datagram socket is bound (if any). |
virtual int |
getLocalPort() const
Returns the local port number to which this DatagramSocket is bound. |
virtual int |
getPort() const
Returns the remote port to which this DatagramSocket is connected. |
virtual int |
getReceiveBufferSize() const
Returns the SO_RVCBUF option for this DatagramSocket, which is the size of the buffer used by the operating system to hold received data before it is read by the application. |
virtual bool |
getReuseAddress() const
Tests if the SO_REUSEADDR option is enabled for this datagram socket. |
virtual int |
getSendBufferSize() const
Returns the value of the SO_SNDBUF option for this datagram socket, which is the size of the buffer used by the operating system to store output data from the application before it is sent to (and acknowledged by) the remote host. |
virtual size_t |
getSoTimeout() const
Returns the value of the SO_TIMEOUT pseudo option. |
virtual bool |
isBound() const
Tests if the datagram socket has been bound. |
virtual bool |
isClosed() const
Tests if the datagram socket has been closed. |
virtual bool |
isConnected() const
Tests the connected status of this DatagramSocket. |
virtual void |
receive(DatagramPacket& p)
Receives a datagram packet from the network using this datagram socket. |
virtual void |
send(const DatagramPacket& p)
Sends a datagram packet using this datagram socket. |
virtual void |
setBroadcast(bool bBroadcast)
Sets the SO_BROADCAST option for this datagram socket. |
static void |
SetDatagramSocketImplFactory(DatagramSocketImplFactory* pFac)
Sets the client DatagramSocket implementation factory for the application. |
virtual void |
setReceiveBufferSize(size_t size)
Sets the SO_RCVBUF option for this datagram socket, which is the size of the buffer used by the operating system to hold received data before it is read by the application. |
virtual void |
setReuseAddress(bool bEnable)
Sets the SO_REUSEADDR option for this datagram socket. |
virtual void |
setSendBufferSize(size_t size)
Sets the SO_SNDBUF option for this datagram socket, which is the size of the buffer used by the operating system to store output data from the application before it is sent to a remote host. |
virtual void |
setSoTimeout(size_t timeoutMS)
Enables/disables the SO_TIMEOUT pseudo option. |
virtual String |
toString() const
Returns a string representation of this DatagramSocket. |
Constructor/Destructor Detail |
DatagramSocket
DatagramSocket()
-
Creates an unbound datagram socket.
The registered DatagramSocket factory is used to create an instance of DatagramSocketImpl to perform the actual work for the DatagramSocket.
- Exceptions:
SocketException
-
if an error occurs creating the DatagramSocket.
DatagramSocket
DatagramSocket(int port)
-
Creates a DatagramSocket and binds it to the specified port on and wildcard address on the local machine.
The registered DatagramSocket factory is used to create an instance of DatagramSocketImpl to perform the actual work for the DatagramSocket.
- Parameters:
port
-
the local port number to bind to
- Exceptions:
IllegalArgumentException
-
if port is not in the valid range
SocketException
-
if an error occurs creating or binding the DatagramSocket.
- See also:
-
connect()
DatagramSocket
DatagramSocket(int port,
InetAddress* pLocalAddr)
-
Creates a DatagramSocket and binds it to the specified interface and port on the local machine.
The registered DatagramSocket factory is used to create an instance of DatagramSocketImpl to perform the actual work for the DatagramSocket.
- Exceptions:
NullPointerException
-
if pAddress is null.
SocketException
-
if an error occurs creating or binding the DatagramSocket.
- See also:
-
connect()
bind
virtual void bind(int port,
InetAddress* pLocalAddr)
-
Binds this datagram socket to a particular local IP address and port.
- Parameters:
port
-
the local port number to bind to. If zero, the system will pick an ephemeral port (usually above 1024)
pLocalAddress
-
an InetAddress pointer representing the interface to bind to. When this is null a valid local address will be used.
- Exceptions:
SocketException
-
if an error occurs binding the DatagramSocket.
- See also:
-
connect()
close
virtual void close()
-
Closes the DatagramSocket and releases any system resources associated with it.
Generally, applications will not need to call this function because the DatagramSocket is automatically closed when the reference-count of the DatagramSocketDescriptor is decremented to zero.
Subsequent send or receive operations will fail with an IOException.
- Exceptions:
SocketException
-
if an error occurs closing the DatagramSocket.
connect
virtual void connect(InetAddress* pAddress,
int port)
-
Connects a DatagramSocket to a specified remote address and port.
When a datagram socket is connected to a remote address, packets may only be sent to or received from that address. When the remote address is a multicast address, only send operations are permitted.
When a datagram socket is connected, packets received from other addresses are silently ignored. By default a datagram socket is not connected.
- Parameters:
pAddress
-
an InetAddress representing the remote host
port
-
the port number on the remote host
- Exceptions:
NullPointerException
-
if pAddress is null.
SocketException
-
if an error occurs connecting to the remote host.
- See also:
-
isConnected() , disconnect()
createDatagramSocketImpl
protected void createDatagramSocketImpl()
-
disconnect
virtual void disconnect()
-
Disconnects the DatagramSocket from its remote destination.
When a datagram socket is disconnected, packets may be sent to any host.
- Exceptions:
SocketException
-
if an error occurs disconnecting the socket.
- See also:
-
connect()
getBroadcast
virtual bool getBroadcast() const
-
Tests if the SO_BROADCAST option is enabled for this datagram socket.
By default, the SO_BROADCAST option is enabled for datagram sockets.
- Returns:
-
true if the SO_BROADCAST option is enabled; false otherwise.
getDatagramSocketImpl
protected RefPtr< DatagramSocketImpl > getDatagramSocketImpl() const
-
Returns the DatagramSocketImp object used by this DatagramSocket.
GetDatagramSocketImplFactory
static RefPtr< DatagramSocketImplFactory > GetDatagramSocketImplFactory()
-
Returns the static object that is the DatagramSocketImplFactory for DatagramSockets.
An instance of the default DatagramSocketImplFactory is created if a factory has not already been registered by the application.
getInetAddress
virtual RefPtr< InetAddress > getInetAddress() const
-
Returns an InetAddress representing the remote host to which this DatagramSocket is connected.
If this DatagramSocket has never been connected or is not currently connected a null RefPtr is returned.
- Returns:
-
the remote InetAddress or null.
- See also:
-
getLocalAddress
getLocalAddress
virtual RefPtr< InetAddress > getLocalAddress() const
-
Returns an InetAddress representing the local interface to which this datagram socket is bound (if any).
If this DatagramSocket has never been bound a null RefPtr is returned.
- Returns:
-
the local InetAddress or null if the datagram socket has not been bound to a local interface.
- See also:
-
getInetAddress()
getLocalPort
virtual int getLocalPort() const
-
Returns the local port number to which this DatagramSocket is bound.
- Returns:
-
the local port number or -1 if this DatagramSocket is not yet bound.
getPort
virtual int getPort() const
-
Returns the remote port to which this DatagramSocket is connected.
- Returns:
-
the remote port number of -1 if this DatagramSocket is not connected.
getReceiveBufferSize
virtual int getReceiveBufferSize() const
-
Returns the SO_RVCBUF option for this DatagramSocket, which is the size of the buffer used by the operating system to hold received data before it is read by the application.
- Returns:
-
the value of the SO_RCVBUF option for this DatagramSocket
- Exceptions:
SocketException
-
if an error occurs while interrogating the DatagramSocket.
- See also:
-
setReceiveBufferSize()
getReuseAddress
virtual bool getReuseAddress() const
-
Tests if the SO_REUSEADDR option is enabled for this datagram socket.
By default, the SO_REUSEADDR option is not enabled for datagram sockets.
- Returns:
-
true if the SO_REUSEADDR option is enabled; false otherwise.
getSendBufferSize
virtual int getSendBufferSize() const
-
Returns the value of the SO_SNDBUF option for this datagram socket, which is the size of the buffer used by the operating system to store output data from the application before it is sent to (and acknowledged by) the remote host.
- Exceptions:
SocketException
-
if an error occurs while interrogating the datagram socket.
getSoTimeout
virtual size_t getSoTimeout() const
-
Returns the value of the SO_TIMEOUT pseudo option.
SO_TIMEOUT is not one of the options defined for Berkeley DatagramSockets, but was actually introduced as part of the Java API. For client DatagramSockets it has the same meaning as the SO_RCVTIMEO option, which specifies the maximum number of milliseconds that a blocking read() call will wait for data to arrive on the DatagramSocket.
isBound
virtual bool isBound() const
-
Tests if the datagram socket has been bound.
- Returns:
-
true if the DatagramSocket has been bound; false otherwise.
isClosed
virtual bool isClosed() const
-
Tests if the datagram socket has been closed.
- Returns:
-
true if the DatagramSocket is closed; false otherwise.
isConnected
virtual bool isConnected() const
-
Tests the connected status of this DatagramSocket.
- Returns:
-
true if the DatagramSocket is connected; false otherwise.
receive
virtual void receive(DatagramPacket& p)
-
Receives a datagram packet from the network using this datagram socket.
The datagram packet is received into a buffer provided by a DatagramPacket object. The DatagramPacket's length field is used to control the number of bytes that are copied into the data buffer, any remaining bytes in the message are silently discarded.
Following a successful receive operation, the length field of the DatagramPacket is updated to reflect the number of bytes copied. In addition, the IP address and port number of the sender are copied into the respective fields of the passed DatagramPacket.
If this datagram socket has been connected to a remote host, only packets originating from the connected host/port will be received. Other packets will be silently dropped.
This method will block until a datagram packet becomes available. The call will block indefinitely unless a specific timeout value has been set with setSoTimeout().
- Parameters:
p
-
the DatagramPacket into which the datagram will be received.
- Exceptions:
SocketException
-
if an error occurs during the receive operation.
SocketTimeoutException
-
if setSoTimeout was previously called and the specified timeout value has expired.
send
virtual void send(const DatagramPacket& p)
-
Sends a datagram packet using this datagram socket.
The datagram packet to send is represented by a reference to a DatagramPacket object, which contains the data buffer to send, its length (which may be zero) and the IP address/port number of the remote host to which the packet will be sent.
If this datagram socket has been connected to a remote host, the packet will be sent to the connected host.
- Parameters:
p
-
the datagram to send.
- Exceptions:
IllegalArgumentException
-
if this datagram socket is connected to a specific host/port and the datagram packet contains destination information which does not match.
SocketException
-
if an error occurs during the receive operation.
setBroadcast
virtual void setBroadcast(bool bBroadcast)
-
Sets the SO_BROADCAST option for this datagram socket.
This method must be called before bind(), so should be used in conjunction with the default DatagramSocket() constructor.
- Parameters:
bEnable
-
enables SO_BROADCAST when true, disables it otherwise
SetDatagramSocketImplFactory
static void SetDatagramSocketImplFactory(DatagramSocketImplFactory* pFac)
-
Sets the client DatagramSocket implementation factory for the application.
When an application creates a new DatagramSocket, the registered DatagramSocket implementation factory's createDatagramSocketImpl() method is called to create the actual DatagramSocketImpl instance which performs the work for the DatagramSocket.
An application should only call this function if it wishes to employ a customized DatagramSocketImpl class.
To ensure that the passed object exists for as long as the application needs it, the DatagramSocketImplFactory object is registered with the system's ObjectManager which holds a (counted) reference to it until system termination. This absolves the application from having to manage the lifetime of the passed object. For example, the following code is perfectly valid and does not cause a memory leak:-
int main(int argc, char* argv[])
{
SystemMonitor _monitor(); // ensures clean termination
// register a customized DatagramSocket implementation factory
DatagramSocket::SetDatagramSocketImplFactory(new MyDatagramSocketImplFactory);
...
}
- Parameters:
pFac
-
a pointer to a DatagramSocketImplFactory
- Exceptions:
NullPointerException
-
if pFac is null.
- Multi-threaded considerations:
-
Can safely be called from multiple concurrent threads.
setReceiveBufferSize
virtual void setReceiveBufferSize(size_t size)
-
Sets the SO_RCVBUF option for this datagram socket, which is the size of the buffer used by the operating system to hold received data before it is read by the application.
The underlying operating system need not use the precise buffer size specified in this call (it is treated more like a hint than a command). To find out the actual receive buffer size being used, applications should call the getReceiveBufferSize() method.
- Parameters:
size
-
the requested buffer size (in bytes)
- Exceptions:
SocketException
-
if an error occurs while setting the SO_RCVBUF option
- See also:
-
getReceiveBufferSize()
setReuseAddress
virtual void setReuseAddress(bool bEnable)
-
Sets the SO_REUSEADDR option for this datagram socket.
This method must be called before bind(), so should be used in conjunction with the default DatagramSocket() constructor.
- Parameters:
bEnable
-
enables SO_REUSEADDR when true, disables it otherwise
- Note:
-
It is not usually necessary to set this option for UDP datagram sockets, but it is required for multicast sockets where several applications on the same host can all bind to and receive multicast packets on a single port.
setSendBufferSize
virtual void setSendBufferSize(size_t size)
-
Sets the SO_SNDBUF option for this datagram socket, which is the size of the buffer used by the operating system to store output data from the application before it is sent to a remote host.
- Parameters:
size
-
the requested buffer size (in bytes)
- Exceptions:
SocketException
-
if an error occurs while setting the SO_SNDBUF option
- See also:
-
getReceiveBufferSize()
setSoTimeout
virtual void setSoTimeout(size_t timeoutMS)
-
Enables/disables the SO_TIMEOUT pseudo option.
SO_TIMEOUT is not one of the options defined for Berkeley sockets, but was actually introduced as part of the Java API. For datagram sockets it has the same meaning as the SO_RCVTIMEO option, which specifies the maximum number of milliseconds that a blocking receive() call will wait for data to arrive on the datagram socket.
- Parameters:
timeoutMS
-
the specified timeout value, in milliseconds. A value of zero indicates no timeout, i.e. an infinite wait.
toString
virtual String toString() const
-
Returns a string representation of this DatagramSocket.
The format of the returned string is dependent on the associated DatagramSocketImpl instance, but plain DatagramSockets return a string in the form:- DatagramSocket[localPort=n]
Found a bug or missing feature? Please email us at support@elcel.com