Dogcows Code - chaz/yoink/blob - src/stlplus/portability/udp_sockets.hpp

   1 #ifndef STLPLUS_UDP_SOCKET
   2 #define STLPLUS_UDP_SOCKET
   3 ////////////////////////////////////////////////////////////////////////////////
   4
   5 // Author:    Andy Rushton
   6 // Copyright: (c) Southampton University 1999-2004
   7 //            (c) Andy Rushton           2004-2009
   8 // License:   BSD License, see ../docs/license.html
   9
  10 // A platform-independent (Unix and Windows anyway) interface to UDP sockets
  11
  12 ////////////////////////////////////////////////////////////////////////////////
  13
  14 #include "portability_fixes.hpp"
  15 #include "ip_sockets.hpp"
  16 #include <string>
  17
  18 namespace stlplus
  19 {
  20
  21   //////////////////////////////////////////////////////////////////////////////
  22   // UDP client - creates a connectioned socket
  23
  24   class UDP_client : protected IP_socket
  25   {
  26   public:
  27
  28     // create an uninitialised socket
  29     UDP_client(void);
  30
  31     // Send/Receive datagram packets to/from the given address/remote port on the local port.
  32     // - remote_address: IP name or number of remote host
  33     // - remote_port: port number of remote host
  34     // - local_port: port number to receive on - 0 to get an ephemeral port.
  35     UDP_client(const std::string& remote_address, unsigned short remote_port, unsigned short local_port=0);
  36
  37     // Send/Receive datagram packets to/from the given address/remote port on the given local port
  38     // Enables default send to remote address/port
  39     // - remote_address: IP address of remote host - pre-looked-up using ip_lookup
  40     // - remote_port: port number of remote host
  41     // - local_port: port number to receive on - 0 to get an ephemeral port.
  42     UDP_client(unsigned long remote_address, unsigned short remote_port, unsigned short local_port=0);
  43
  44     ////////////////////////////////////////////////////////////////////////////
  45     // initialisation, connection
  46
  47     // function for performing IP lookup (i.e. gethostbyname)
  48     // could be standalone but making it a member means that it can use the socket's error handler
  49     // i.e. if this fails, the sockets error code will be set - clear it to use the socket again
  50     // - remote_address: IP name (stlplus.sourceforge.net) or dotted number (216.34.181.96)
  51     // - returns the IP address as a long integer - zero if there's an error
  52     // unsigned long ip_lookup(const std::string& remote_address);
  53     using IP_socket::ip_lookup;
  54
  55     // Send/Receive datagram packets to/from the given address/remote port on the local port.
  56     // Enables default send to remote address/port
  57     // - remote_address: IP name or number of remote host
  58     // - remote_port: port number of remote host
  59     // - local_port: port number to receive on - 0 to get an ephemeral port.
  60     // - returns a success flag
  61     bool initialise(const std::string& remote_address, unsigned short remote_port, unsigned short local_port=0);
  62
  63     // Send/Receive datagram packets to/from the given address/remote port on the given local port
  64     // Enables default send to remote address/port
  65     // - remote_address: IP address of remote host - pre-looked-up using ip_lookup
  66     // - remote_port: port number of remote host
  67     // - local_port: port number to receive on - 0 to get an ephemeral port.
  68     // - returns a success flag
  69     bool initialise(unsigned long remote_address, unsigned short remote_port, unsigned short local_port=0);
  70
  71     // test whether this is an initialised socket
  72     // - returns whether this is initialised
  73     // bool initialised(void) const;
  74     using IP_socket::initialised;
  75
  76     // close, i.e. disconnect the socket
  77     // - returns a success flag
  78     // bool close(void);
  79     using IP_socket::close;
  80
  81     ////////////////////////////////////////////////////////////////////////////
  82     // sending/receiving
  83
  84     // test whether a socket is connected and ready to send data, returns if ready or on timeout
  85     // - timeout: how long to wait in microseconds if not connected yet (blocking)
  86     // - returns status
  87     // bool send_ready(unsigned timeout = 0);
  88     using IP_socket::send_ready;
  89
  90     // send to the remote address/port setup in initialise, from the local port also setup in initialise.
  91     // send data through the socket as a single datagram
  92     // - packet: string containing data to be sent - if data is successfully sent it is removed
  93     // - returns success flag
  94     bool send(std::string& packet);
  95
  96     // test whether a socket is connected and ready to receive data, returns if ready or on timeout
  97     // - timeout: how long to wait in microseconds if not connected yet (blocking)
  98     // - returns status
  99     // bool receive_ready(unsigned timeout = 0);
 100     using IP_socket::receive_ready;
 101
 102     // datagram receive
 103     // - packet: string to receive data from datagram - if data is successfully sent it is appended
 104     // - returns success flag - i.e. packet successfully received
 105     bool receive(std::string& packet);
 106
 107     ////////////////////////////////////////////////////////////////////////////
 108     // informational
 109
 110     // the local port number of the connection
 111     // returns the port number, 0 if not bound to a port
 112     // unsigned short local_port(void) const;
 113     using IP_socket::local_port;
 114
 115     // the remote address of the connection
 116     // returns the address, 0 if ANY address
 117     // unsigned long remote_address(void) const;
 118     using IP_socket::remote_address;
 119
 120     // the remote port number of the connection
 121     // returns the port number, 0 if not bound to a port
 122     // unsigned short remote_port(void) const;
 123     using IP_socket::remote_port;
 124
 125     ////////////////////////////////////////////////////////////////////////////
 126     // error handling
 127     // errors are set internally
 128     // an error code of 0 is the test for no error, don't rely on the message being an empty string
 129     // an error code != 0 means an error, then there will be a message explaining the error
 130
 131     // if an error is set it stays set - so you must clear it before further operations
 132     // void clear_error (void);
 133     using IP_socket::clear_error ;
 134
 135     // get the error code of the last error
 136     // int error(void) const;
 137     using IP_socket::error;
 138
 139     // get the explanatory message of the last error
 140     // std::string message(void) const;
 141     using IP_socket::message;
 142
 143     ////////////////////////////////////////////////////////////////////////////
 144
 145   private:
 146     IP_socket m_socket;
 147   };
 148
 149   ////////////////////////////////////////////////////////////////////////////////
 150   // UDP server - creates a connectionless (multicast) listener socket
 151
 152   class UDP_server : protected IP_socket
 153   {
 154   public:
 155
 156     // create an uninitialised socket
 157     UDP_server(void);
 158
 159     // Initialise socket.
 160     // Receive datagram packets from any address on provided local receiving port.
 161     // - local_port: port number to receive on - 0 to get an ephemeral port.
 162     UDP_server(unsigned short local_port);
 163
 164     ////////////////////////////////////////////////////////////////////////////
 165     // initialisation, connection
 166
 167     // function for performing IP lookup (i.e. gethostbyname)
 168     // could be standalone but making it a member means that it can use the socket's error handler
 169     // i.e. if this fails, the sockets error code will be set - clear it to use the socket again
 170     // - remote_address: IP name (stlplus.sourceforge.net) or dotted number (216.34.181.96)
 171     // - returns the IP address as a long integer - zero if there's an error
 172     // unsigned long ip_lookup(const std::string& remote_address);
 173     using IP_socket::ip_lookup;
 174
 175     // Initialise socket.
 176     // Receive datagram packets from any address on provided local receiving port.
 177     // - local_port: port number to receive on - 0 to get an ephemeral port.
 178     // - returns a success flag
 179     bool initialise(unsigned short local_port);
 180
 181     // test whether this is an initialised socket
 182     // - returns whether this is initialised
 183     // bool initialised(void) const;
 184     using IP_socket::initialised;
 185
 186     // close, i.e. disconnect the socket
 187     // - returns a success flag
 188     // bool close(void);
 189     using IP_socket::close;
 190
 191     ////////////////////////////////////////////////////////////////////////////
 192     // sending/receiving
 193
 194     // test whether a socket is connected and ready to send data, returns if ready or on timeout
 195     // - timeout: how long to wait in microseconds if not connected yet (blocking)
 196     // - returns status
 197     // bool send_ready(unsigned timeout = 0);
 198     using IP_socket::send_ready;
 199
 200     // send to the address/port given here, from the local port setup in initialise.
 201     // send data through the socket as a single datagram
 202     // - packet: string containing data to be sent - if data is successfully sent it is removed
 203     // - remote_address: IP name (stlplus.sourceforge.net) or dotted number (216.34.181.96)
 204     // - remote_port: port number of remote host
 205     // - returns success flag
 206     bool send(std::string& packet, const std::string& remote_address, unsigned short remote_port);
 207
 208     // send to the address/port given here, from the local port setup in initialise.
 209     // send data through the socket as a single datagram
 210     // - packet: string containing data to be sent - if data is successfully sent it is removed
 211     // - remote_address: pre-looked-up IP address of remote host
 212     // - remote_port: port number of remote host
 213     // - returns success flag
 214     bool send(std::string& packet, unsigned long remote_address, unsigned short remote_port);
 215
 216     // test whether a socket is connected and ready to receive data, returns if ready or on timeout
 217     // - timeout: how long to wait in microseconds if not connected yet (blocking)
 218     // - returns status
 219     // bool receive_ready(unsigned timeout = 0);
 220     using IP_socket::receive_ready;
 221
 222     // datagram receive
 223     // - packet: string to receive data from datagram - if data is successfully sent it is appended
 224     // - remote_address: the address of the client that sent the packet, can then be used to reply
 225     // - remote_port: the port of the client that sent the packet, can then be used to reply
 226     // - returns success flag - i.e. packet successfully received
 227     bool receive(std::string& packet, unsigned long& remote_address, unsigned short& remote_port);
 228
 229     ////////////////////////////////////////////////////////////////////////////
 230     // informational
 231
 232     // the local port number of the connection
 233     // returns the port number, 0 if not bound to a port
 234     // unsigned short local_port(void) const;
 235     using IP_socket::local_port;
 236
 237     ////////////////////////////////////////////////////////////////////////////
 238     // error handling
 239     // errors are set internally
 240     // an error code of 0 is the test for no error, don't rely on the message being an empty string
 241     // an error code != 0 means an error, then there will be a message explaining the error
 242
 243     // if an error is set it stays set - so you must clear it before further operations
 244     // void clear_error(void);
 245     using IP_socket::clear_error;
 246
 247     // get the error code of the last error
 248     // int error(void) const;
 249     using IP_socket::error;
 250
 251     // get the explanatory message of the last error
 252     // std::string message(void) const;
 253     using IP_socket::message;
 254
 255     ////////////////////////////////////////////////////////////////////////////
 256   };
 257
 258   /////////////////////////////////////////////////////////////////////////////
 259   // fire and forget UDP client packet send function
 260
 261   bool UDP_send(const std::string& packet,
 262                 const std::string& remote_address, unsigned short remote_port, unsigned short local_port = 0);
 263
 264   ////////////////////////////////////////////////////////////////////////////////
 265
 266 } // end namespace stlplus
 267
 268 #endif