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