Cross-Platform C++

ot::net
class DatagramSocket

#include "ot/net/DatagramSocket.h"

ot::ManagedObject ot::net::MulticastSocket 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.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

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()

Method Detail

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< DatagramSocketImplgetDatagramSocketImpl() const
Returns the DatagramSocketImp object used by this DatagramSocket.


GetDatagramSocketImplFactory

static RefPtr< DatagramSocketImplFactoryGetDatagramSocketImplFactory()
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< InetAddressgetInetAddress() 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< InetAddressgetLocalAddress() 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]



Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements