-#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
+#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 onwards\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