]>
Dogcows Code - chaz/yoink/blob - src/stlplus/portability/ip_sockets.hpp
f0bd314546041dd1ae50e78315a455762e603858
1 #ifndef STLPLUS_IP_SOCKET
2 #define STLPLUS_IP_SOCKET
3 ////////////////////////////////////////////////////////////////////////////////
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
10 // A platform-independent (Unix and Windows anyway) interface to Internet-Protocol sockets
12 ////////////////////////////////////////////////////////////////////////////////
13 #include "portability_fixes.hpp"
19 //////////////////////////////////////////////////////////////////////////////
21 // use a PIMPL interface to hide the platform-specifics in the implementation
23 class IP_socket_internals
;
25 ////////////////////////////////////////////////////////////////////////////
26 // Types of socket supported
28 enum IP_socket_type
{undefined_socket_type
= -1, TCP
= 0, UDP
= 1};
30 //////////////////////////////////////////////////////////////////////////////
37 ////////////////////////////////////////////////////////////////////////////
38 // constructors/destructors
40 // create an uninitialised socket
43 // create an initialised socket
44 // - type: create either a TCP or UDP socket
45 IP_socket(IP_socket_type type
);
47 // destroy the socket, closing it if open
50 // copying is implemented as aliasing
51 IP_socket(const IP_socket
&);
52 IP_socket
& operator=(const IP_socket
&);
54 ////////////////////////////////////////////////////////////////////////////
57 // initialise the socket
58 // - type: create either a TCP or UDP socket
59 // - returns success status
60 bool initialise(IP_socket_type type
);
62 // test whether this is an initialised socket
63 // - returns whether this is initialised
64 bool initialised(void) const;
66 // close, i.e. disconnect the socket
67 // - returns a success flag
70 //////////////////////////////////////////////////////////////////////////////
71 // Socket configuration
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
);
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);
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
);
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
);
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);
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;
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);
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
);
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);
128 ////////////////////////////////////////////////////////////////////////////
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)
134 bool send_ready(unsigned timeout
= 0);
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
);
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
);
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
);
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)
162 bool receive_ready(unsigned wait
= 0);
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
169 // - data: string receiving data from socket - any data successfully received is appended
170 // - returns success flag
171 bool receive(std::string
& data
);
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
);
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
);
186 ////////////////////////////////////////////////////////////////////////////
189 // gets the type of socket
190 // - returns undefined_socket_type, TCP or UDP
191 IP_socket_type
type(void) const;
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;
197 // the remote address of the connection
198 // returns the address, 0 if not connected
199 unsigned long remote_address(void) const;
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;
205 ////////////////////////////////////////////////////////////////////////////
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
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;
214 // if an error is set it stays set - so you must clear it before further operations
215 void clear_error (void) const;
217 // get the error code of the last error
218 int error(void) const;
220 // get the explanatory message of the last error
221 std::string
message(void) const;
223 ////////////////////////////////////////////////////////////////////////////
226 friend class IP_socket_internals
;
227 IP_socket_internals
* m_impl
;
231 } // end namespace stlplus
This page took 0.044143 seconds and 4 git commands to generate.