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

   1 #ifndef STLPLUS_IP_SOCKET
   2 #define STLPLUS_IP_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 Internet-Protocol sockets
  11
  12 ////////////////////////////////////////////////////////////////////////////////
  13 #include "portability_fixes.hpp"
  14 #include <string>
  15
  16 namespace stlplus
  17 {
  18
  19   //////////////////////////////////////////////////////////////////////////////
  20   // internals
  21   // use a PIMPL interface to hide the platform-specifics in the implementation
  22
  23   class IP_socket_internals;
  24
  25   ////////////////////////////////////////////////////////////////////////////
  26   // Types of socket supported
  27
  28   enum IP_socket_type {undefined_socket_type = -1, TCP = 0, UDP = 1};
  29
  30   //////////////////////////////////////////////////////////////////////////////
  31   // Socket class
  32
  33   class IP_socket
  34   {
  35   public:
  36
  37     ////////////////////////////////////////////////////////////////////////////
  38     // constructors/destructors
  39
  40     // create an uninitialised socket
  41     IP_socket(void);
  42
  43     // create an initialised socket
  44     // - type: create either a TCP or UDP socket
  45     IP_socket(IP_socket_type type);
  46
  47     // destroy the socket, closing it if open
  48     ~IP_socket(void);
  49
  50     // copying is implemented as aliasing
  51     IP_socket(const IP_socket&);
  52     IP_socket& operator=(const IP_socket&);
  53
  54     ////////////////////////////////////////////////////////////////////////////
  55     // initialisation
  56
  57     // initialise the socket
  58     // - type: create either a TCP or UDP socket
  59     // - returns success status
  60     bool initialise(IP_socket_type type);
  61
  62     // test whether this is an initialised socket
  63     // - returns whether this is initialised
  64     bool initialised(void) const;
  65
  66     // close, i.e. disconnect the socket
  67     // - returns a success flag
  68     bool close(void);
  69
  70     //////////////////////////////////////////////////////////////////////////////
  71     // Socket configuration
  72
  73     // function for performing IP lookup (i.e. gethostbyname)
  74     // could be standalone but making it a member means that it can use the socket's error handler
  75     // i.e. if this fails, the sockets error code will be set - clear it to use the socket again
  76     // - remote_address: IP name (stlplus.sourceforge.net) or dotted number (216.34.181.96)
  77     // - returns the IP address as a long integer - zero if there's an error
  78     unsigned long ip_lookup(const std::string& remote_address);
  79
  80     // test whether a socket is ready to communicate
  81     // - readable: test whether socket is ready to read
  82     // - writeable: test whether a socket is ready to write
  83     // - timeout: if socket is not ready, time to wait before giving up - in micro-seconds - 0 means don't wait
  84     // returns false if not ready or error - use error() method to tell - true if ready
  85     bool select(bool readable, bool writeable, unsigned timeout = 0);
  86
  87     // bind the socket to a port so that it can receive from specific address - typically used by a client
  88     // - remote_address: IP number of remote server to send/receive to/from
  89     // - local_port: port on local machine to bind to the address
  90     // - returns success flag
  91     bool bind(unsigned long remote_address, unsigned short local_port);
  92
  93     // bind the socket to a port so that it can receive from any address - typically used by a server
  94     // - local_port: port on local machine to bind to the address
  95     // - returns success flag
  96     bool bind_any(unsigned short local_port);
  97
  98     // set this socket up to be a listening port
  99     // socket must be bound to a port already
 100     // - queue: length of backlog queue to manage - may be zero meaning no queue
 101     // - returns success status
 102     bool listen(unsigned short queue = 0);
 103
 104     // test for a connection on the socket
 105     // only applicable if it has been set up as a listening port
 106     // - timeout: how long to wait in microseconds if not connected yet
 107     // - returns true if a connection is ready to be accepted
 108     bool accept_ready(unsigned timeout = 0) const;
 109
 110     // accept a connection on the socket
 111     // only applicable if it has been set up as a listening port
 112     // - returns the connection as a new socket
 113     IP_socket accept(void);
 114
 115     // create a connection - usually used by a client
 116     // TCP: client connect to a remote server
 117     // UDP: setup remote address and port for sends
 118     // - remote_address: IP number already looked up using ip_lookup
 119     // - remote_port: port to connect to
 120     // - returns a success flag
 121     bool connect(unsigned long remote_address, unsigned short remote_port);
 122
 123     // test whether a socket is connected and ready to communicate, returns on successful connect or timeout
 124     // - timeout: how long to wait in microseconds if not connected yet
 125     // - returns true if connected and ready to communicate, false if not ready or error
 126     bool connected(unsigned timeout = 0);
 127
 128     ////////////////////////////////////////////////////////////////////////////
 129     // sending/receiving
 130
 131     // test whether a socket is connected and ready to send data, returns if ready or on timeout
 132     // - timeout: how long to wait in microseconds if not connected yet (blocking)
 133     // - returns status
 134     bool send_ready(unsigned timeout = 0);
 135
 136     // send data through a connection-based (TCP) socket
 137     // if the data is long only part of it may be sent. The sent part is
 138     // removed from the data, so the same string can be sent again and again
 139     // until it is empty.
 140     // - data: string containing data to be sent - any data successfully sent is removed
 141     // - returns success flag
 142     bool send(std::string& data);
 143
 144     // send data through a connectionless (UDP) socket
 145     // the data will be sent as a single packet
 146     // - packet: string containing data to be sent - any data successfully sent is removed
 147     // - remote_address: address of the remote host to send to - optional if the socket has been connected to remote
 148     // - remote_port: port of the remote host to send to - optional if the socket has been connected to remote
 149     // - returns success flag
 150     bool send_packet(std::string& packet, unsigned long remote_address, unsigned short remote_port);
 151
 152     // send data through a connectionless (UDP) socket
 153     // the data will be sent as a single packet
 154     // only works if the socket has been connected to remote
 155     // - packet: string containing data to be sent - any data successfully sent is removed
 156     // - returns success flag
 157     bool send_packet(std::string& packet);
 158
 159     // test whether a socket is connected and ready to receive data, returns if ready or on timeout
 160     // - timeout: how long to wait in microseconds if not connected yet (blocking)
 161     // - returns status
 162     bool receive_ready(unsigned wait = 0);
 163
 164     // receive data through a connection-based (TCP) socket
 165     // if the data is long only part of it may be received. The received data
 166     // is appended to the string, building it up in stages, so the same string
 167     // can be received again and again until all information has been
 168     // received.
 169     // - data: string receiving data from socket - any data successfully received is appended
 170     // - returns success flag
 171     bool receive(std::string& data);
 172
 173     // receive data through a connectionless (UDP) socket
 174     // - packet: string receiving data from socket - any data successfully received is appended
 175     // - remote_address: returns the address of the remote host received from
 176     // - remote_port: returns the port of the remote host received from
 177     // - returns success flag
 178     bool receive_packet(std::string& packet, unsigned long& remote_address, unsigned short& remote_port);
 179
 180     // variant of above which does not give back the address and port of the sender
 181     // receive data through a connectionless (UDP) socket
 182     // - packet: string receiving data from socket - any data successfully received is appended
 183     // - returns success flag
 184     bool receive_packet(std::string& packet);
 185
 186     ////////////////////////////////////////////////////////////////////////////
 187     // informational
 188
 189     // gets the type of socket
 190     // - returns undefined_socket_type, TCP or UDP
 191     IP_socket_type type(void) const;
 192
 193     // the local port number of the connection
 194     // returns the port number, 0 if not bound to a port
 195     unsigned short local_port(void) const;
 196
 197     // the remote address of the connection
 198     // returns the address, 0 if not connected
 199     unsigned long remote_address(void) const;
 200
 201     // the remote port number of the connection
 202     // returns the port number, 0 if not connected to a port
 203     unsigned short remote_port(void) const;
 204
 205     ////////////////////////////////////////////////////////////////////////////
 206     // error handling
 207     // errors are set internally
 208     // an error code of 0 is the test for no error, don't rely on the message being an empty string
 209     // an error code != 0 means an error, then there will be a message explaining the error
 210
 211     // indicate an error - mostly used internally, you can set your own errors - use a negative code
 212     void set_error (int error, const std::string& message) const;
 213
 214     // if an error is set it stays set - so you must clear it before further operations
 215     void clear_error (void) const;
 216
 217     // get the error code of the last error
 218     int error(void) const;
 219
 220     // get the explanatory message of the last error
 221     std::string message(void) const;
 222
 223     ////////////////////////////////////////////////////////////////////////////
 224
 225   private:
 226     friend class IP_socket_internals;
 227     IP_socket_internals* m_impl;
 228   };
 229
 230
 231 } // end namespace stlplus
 232
 233 #endif