--- /dev/null
+#ifndef STLPLUS_IP_SOCKET\r
+#define STLPLUS_IP_SOCKET\r
+////////////////////////////////////////////////////////////////////////////////\r
+\r
+// Author: Andy Rushton\r
+// Copyright: (c) Southampton University 1999-2004\r
+// (c) Andy Rushton 2004-2009\r
+// License: BSD License, see ../docs/license.html\r
+\r
+// A platform-independent (Unix and Windows anyway) interface to Internet-Protocol sockets\r
+\r
+////////////////////////////////////////////////////////////////////////////////\r
+#include "portability_fixes.hpp"\r
+#include <string>\r
+\r
+namespace stlplus\r
+{\r
+\r
+ //////////////////////////////////////////////////////////////////////////////\r
+ // internals\r
+ // use a PIMPL interface to hide the platform-specifics in the implementation\r
+\r
+ class IP_socket_internals;\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+ // Types of socket supported\r
+\r
+ enum IP_socket_type {undefined_socket_type = -1, TCP = 0, UDP = 1};\r
+\r
+ //////////////////////////////////////////////////////////////////////////////\r
+ // Socket class\r
+\r
+ class IP_socket\r
+ {\r
+ public:\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+ // constructors/destructors\r
+\r
+ // create an uninitialised socket\r
+ IP_socket(void);\r
+\r
+ // create an initialised socket\r
+ // - type: create either a TCP or UDP socket\r
+ IP_socket(IP_socket_type type);\r
+\r
+ // destroy the socket, closing it if open\r
+ ~IP_socket(void);\r
+\r
+ // copying is implemented as aliasing\r
+ IP_socket(const IP_socket&);\r
+ IP_socket& operator=(const IP_socket&);\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+ // initialisation\r
+\r
+ // initialise the socket\r
+ // - type: create either a TCP or UDP socket\r
+ // - returns success status\r
+ bool initialise(IP_socket_type type);\r
+\r
+ // test whether this is an initialised socket\r
+ // - returns whether this is initialised\r
+ bool initialised(void) const;\r
+\r
+ // close, i.e. disconnect the socket\r
+ // - returns a success flag\r
+ bool close(void);\r
+\r
+ //////////////////////////////////////////////////////////////////////////////\r
+ // Socket configuration\r
+\r
+ // function for performing IP lookup (i.e. gethostbyname)\r
+ // could be standalone but making it a member means that it can use the socket's error handler\r
+ // i.e. if this fails, the sockets error code will be set - clear it to use the socket again\r
+ // - remote_address: IP name (stlplus.sourceforge.net) or dotted number (216.34.181.96)\r
+ // - returns the IP address as a long integer - zero if there's an error\r
+ unsigned long ip_lookup(const std::string& remote_address);\r
+\r
+ // test whether a socket is ready to communicate\r
+ // - readable: test whether socket is ready to read\r
+ // - writeable: test whether a socket is ready to write\r
+ // - timeout: if socket is not ready, time to wait before giving up - in micro-seconds - 0 means don't wait\r
+ // returns false if not ready or error - use error() method to tell - true if ready\r
+ bool select(bool readable, bool writeable, unsigned timeout = 0);\r
+\r
+ // bind the socket to a port so that it can receive from specific address - typically used by a client\r
+ // - remote_address: IP number of remote server to send/receive to/from\r
+ // - local_port: port on local machine to bind to the address\r
+ // - returns success flag\r
+ bool bind(unsigned long remote_address, unsigned short local_port);\r
+\r
+ // bind the socket to a port so that it can receive from any address - typically used by a server\r
+ // - local_port: port on local machine to bind to the address\r
+ // - returns success flag\r
+ bool bind_any(unsigned short local_port);\r
+\r
+ // set this socket up to be a listening port\r
+ // socket must be bound to a port already\r
+ // - queue: length of backlog queue to manage - may be zero meaning no queue\r
+ // - returns success status\r
+ bool listen(unsigned short queue = 0);\r
+\r
+ // test for a connection on the socket\r
+ // only applicable if it has been set up as a listening port\r
+ // - timeout: how long to wait in microseconds if not connected yet\r
+ // - returns true if a connection is ready to be accepted\r
+ bool accept_ready(unsigned timeout = 0) const;\r
+\r
+ // accept a connection on the socket\r
+ // only applicable if it has been set up as a listening port\r
+ // - returns the connection as a new socket\r
+ IP_socket accept(void);\r
+\r
+ // create a connection - usually used by a client\r
+ // TCP: client connect to a remote server\r
+ // UDP: setup remote address and port for sends\r
+ // - remote_address: IP number already looked up using ip_lookup\r
+ // - remote_port: port to connect to\r
+ // - returns a success flag\r
+ bool connect(unsigned long remote_address, unsigned short remote_port);\r
+\r
+ // test whether a socket is connected and ready to communicate, returns on successful connect or timeout\r
+ // - timeout: how long to wait in microseconds if not connected yet\r
+ // - returns true if connected and ready to communicate, false if not ready or error\r
+ bool connected(unsigned timeout = 0);\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+ // sending/receiving\r
+\r
+ // test whether a socket is connected and ready to send data, returns if ready or on timeout\r
+ // - timeout: how long to wait in microseconds if not connected yet (blocking)\r
+ // - returns status\r
+ bool send_ready(unsigned timeout = 0);\r
+\r
+ // send data through a connection-based (TCP) socket\r
+ // if the data is long only part of it may be sent. The sent part is\r
+ // removed from the data, so the same string can be sent again and again\r
+ // until it is empty.\r
+ // - data: string containing data to be sent - any data successfully sent is removed\r
+ // - returns success flag\r
+ bool send(std::string& data);\r
+\r
+ // send data through a connectionless (UDP) socket\r
+ // the data will be sent as a single packet\r
+ // - packet: string containing data to be sent - any data successfully sent is removed\r
+ // - remote_address: address of the remote host to send to - optional if the socket has been connected to remote\r
+ // - remote_port: port of the remote host to send to - optional if the socket has been connected to remote\r
+ // - returns success flag\r
+ bool send_packet(std::string& packet, unsigned long remote_address, unsigned short remote_port);\r
+\r
+ // send data through a connectionless (UDP) socket\r
+ // the data will be sent as a single packet\r
+ // only works if the socket has been connected to remote\r
+ // - packet: string containing data to be sent - any data successfully sent is removed\r
+ // - returns success flag\r
+ bool send_packet(std::string& packet);\r
+\r
+ // test whether a socket is connected and ready to receive data, returns if ready or on timeout\r
+ // - timeout: how long to wait in microseconds if not connected yet (blocking)\r
+ // - returns status\r
+ bool receive_ready(unsigned wait = 0);\r
+\r
+ // receive data through a connection-based (TCP) socket\r
+ // if the data is long only part of it may be received. The received data\r
+ // is appended to the string, building it up in stages, so the same string\r
+ // can be received again and again until all information has been\r
+ // received.\r
+ // - data: string receiving data from socket - any data successfully received is appended\r
+ // - returns success flag\r
+ bool receive(std::string& data);\r
+\r
+ // receive data through a connectionless (UDP) socket\r
+ // - packet: string receiving data from socket - any data successfully received is appended\r
+ // - remote_address: returns the address of the remote host received from\r
+ // - remote_port: returns the port of the remote host received from\r
+ // - returns success flag\r
+ bool receive_packet(std::string& packet, unsigned long& remote_address, unsigned short& remote_port);\r
+\r
+ // variant of above which does not give back the address and port of the sender\r
+ // receive data through a connectionless (UDP) socket\r
+ // - packet: string receiving data from socket - any data successfully received is appended\r
+ // - returns success flag\r
+ bool receive_packet(std::string& packet);\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+ // informational\r
+\r
+ // gets the type of socket\r
+ // - returns undefined_socket_type, TCP or UDP\r
+ IP_socket_type type(void) const;\r
+\r
+ // the local port number of the connection\r
+ // returns the port number, 0 if not bound to a port\r
+ unsigned short local_port(void) const;\r
+\r
+ // the remote address of the connection\r
+ // returns the address, 0 if not connected\r
+ unsigned long remote_address(void) const;\r
+\r
+ // the remote port number of the connection\r
+ // returns the port number, 0 if not connected to a port\r
+ unsigned short remote_port(void) const;\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+ // error handling\r
+ // errors are set internally\r
+ // an error code of 0 is the test for no error, don't rely on the message being an empty string\r
+ // an error code != 0 means an error, then there will be a message explaining the error\r
+\r
+ // indicate an error - mostly used internally, you can set your own errors - use a negative code\r
+ void set_error (int error, const std::string& message) const;\r
+\r
+ // if an error is set it stays set - so you must clear it before further operations\r
+ void clear_error (void) const;\r
+\r
+ // get the error code of the last error\r
+ int error(void) const;\r
+\r
+ // get the explanatory message of the last error\r
+ std::string message(void) const;\r
+\r
+ ////////////////////////////////////////////////////////////////////////////\r
+\r
+ private:\r
+ friend class IP_socket_internals;\r
+ IP_socket_internals* m_impl;\r
+ };\r
+\r
+\r
+} // end namespace stlplus\r
+\r
+#endif\r