CSL 5.2

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

PracticalSocket.h
Go to the documentation of this file.
1 /*
2 * C++ sockets on Unix and Windows
3 * Copyright (C) 2002
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18 */
19
20 #ifndef __PRACTICALSOCKET_INCLUDED__
21 #define __PRACTICALSOCKET_INCLUDED__
22
23 #include <string> // For string
24 #include <exception> // For exception class
25
26 using namespace std;
27
28 class SocketException : public exception {
29 public:
30 /**
31 * Construct a SocketException with a explanatory message.
32 * @param message explanatory message
33 * @param incSysMsg true if system message (from strerror(errno))
34 * should be postfixed to the user provided message
35 */
36 SocketException(const string &message, bool inclSysMsg = false) throw();
37
38 /**
39 * Provided just to guarantee that no exceptions are thrown.
40 */
41 ~SocketException() throw();
42
43 /**
44 * Get the exception message
45 * @return exception message
46 */
47 const char *what() const throw();
48
49 private:
50 string userMessage; // Exception message
51 };
52
53 /**
54 * Socket super class
55 */
56 class Socket {
57 public:
58 /**
59 * Close and deallocate this socket
60 */
61 ~Socket();
62
63 /**
64 * Get the local address
65 * @return local address of socket
66 * @exception SocketException thrown if fetch fails
67 */
68 string getLocalAddress() throw(SocketException);
69
70 /**
71 * Get the local port
72 * @return local port of socket
73 * @exception SocketException thrown if fetch fails
74 */
75 unsigned short getLocalPort() throw(SocketException);
76
77 /**
78 * Set the local port to the specified port and the local address
79 * to any interface
80 * @param localPort local port
81 * @exception SocketException thrown if setting local port fails
82 */
83 void setLocalPort(unsigned short localPort) throw(SocketException);
84
85 /**
86 * Set the local port to the specified port and the local address
87 * to the specified address. If you omit the port, a random port
88 * will be selected.
89 * @param localAddress local address
90 * @param localPort local port
91 * @exception SocketException thrown if setting local port or address fails
92 */
93 void setLocalAddressAndPort(const string &localAddress,
94 unsigned short localPort = 0) throw(SocketException);
95
96 /**
97 * If WinSock, unload the WinSock DLLs; otherwise do nothing. We ignore
98 * this in our sample client code but include it in the library for
99 * completeness. If you are running on Windows and you are concerned
100 * about DLL resource consumption, call this after you are done with all
101 * Socket instances. If you execute this on Windows while some instance of
102 * Socket exists, you are toast. For portability of client code, this is
103 * an empty function on non-Windows platforms so you can always include it.
104 * @param buffer buffer to receive the data
105 * @param bufferLen maximum number of bytes to read into buffer
106 * @return number of bytes read, 0 for EOF, and -1 for error
107 * @exception SocketException thrown WinSock clean up fails
108 */
109 static void cleanUp() throw(SocketException);
110
111 /**
112 * Resolve the specified service for the specified protocol to the
113 * corresponding port number in host byte order
114 * @param service service to resolve (e.g., "http")
115 * @param protocol protocol of service to resolve. Default is "tcp".
116 */
117 static unsigned short resolveService(const string &service,
118 const string &protocol = "tcp");
119
120 private:
121 // Prevent the user from trying to use value semantics on this object
122 Socket(const Socket &sock);
123 void operator=(const Socket &sock);
124
125 protected:
126 int sockDesc; // Socket descriptor
127 Socket(int type, int protocol) throw(SocketException);
128 Socket(int sockDesc);
129 };
130
131 /**
132 * Socket which is able to connect, send, and receive
133 */
134 class CommunicatingSocket : public Socket {
135 public:
136 /**
137 * Attempt to establish a socket connection with the given foreign
138 * address and port
139 * @param foreignAddress foreign address (IP address or name)
140 * @param foreignPort foreign port
141 * @return true if connection successfully established
142 * @exception SocketException thrown if unable to establish connection
143 */
144 void connect(const string &foreignAddress, unsigned short foreignPort)
145 throw(SocketException);
146
147 /**
148 * Write the given buffer to this socket. Call connect() before
149 * calling send()
150 * @param buffer buffer to be written
151 * @param bufferLen number of bytes from buffer to be written
152 * @return true if the send is successful
153 * @exception SocketException thrown if unable to send data
154 */
155 void send(const void *buffer, int bufferLen) throw(SocketException);
156
157 /**
158 * Read into the given buffer up to bufferLen bytes data from this
159 * socket. Call connect() before calling recv()
160 * @param buffer buffer to receive the data
161 * @param bufferLen maximum number of bytes to read into buffer
162 * @return number of bytes read, 0 for EOF, and -1 for error
163 * @exception SocketException thrown if unable to receive data
164 */
165 int recv(void *buffer, int bufferLen) throw(SocketException);
166
167 /**
168 * Get the foreign address. Call connect() before calling recv()
169 * @return foreign address
170 * @exception SocketException thrown if unable to fetch foreign address
171 */
172 string getForeignAddress() throw(SocketException);
173
174 /**
175 * Get the foreign port. Call connect() before calling recv()
176 * @return foreign port
177 * @exception SocketException thrown if unable to fetch foreign port
178 */
179 unsigned short getForeignPort() throw(SocketException);
180
181 protected:
182 CommunicatingSocket(int type, int protocol) throw(SocketException);
183 CommunicatingSocket(int newConnSD);
184 };
185
186 /**
187 * TCP socket for communication with other TCP sockets
188 */
189 class TCPSocket : public CommunicatingSocket {
190 public:
191 /**
192 * Construct a TCP socket with no connection
193 * @exception SocketException thrown if unable to create TCP socket
194 */
195 TCPSocket() throw(SocketException);
196
197 /**
198 * Construct a TCP socket with a connection to the given foreign address
199 * and port
200 * @param foreignAddress foreign address (IP address or name)
201 * @param foreignPort foreign port
202 * @exception SocketException thrown if unable to create TCP socket
203 */
204 TCPSocket(const string &foreignAddress, unsigned short foreignPort)
205 throw(SocketException);
206
207 private:
208 // Access for TCPServerSocket::accept() connection creation
209 friend class TCPServerSocket;
210 TCPSocket(int newConnSD);
211 };
212
213 /**
214 * TCP socket class for servers
215 */
216 class TCPServerSocket : public Socket {
217 public:
218 /**
219 * Construct a TCP socket for use with a server, accepting connections
220 * on the specified port on any interface
221 * @param localPort local port of server socket, a value of zero will
222 * give a system-assigned unused port
223 * @param queueLen maximum queue length for outstanding
224 * connection requests (default 5)
225 * @exception SocketException thrown if unable to create TCP server socket
226 */
227 TCPServerSocket(unsigned short localPort, int queueLen = 5)
228 throw(SocketException);
229
230 /**
231 * Construct a TCP socket for use with a server, accepting connections
232 * on the specified port on the interface specified by the given address
233 * @param localAddress local interface (address) of server socket
234 * @param localPort local port of server socket
235 * @param queueLen maximum queue length for outstanding
236 * connection requests (default 5)
237 * @exception SocketException thrown if unable to create TCP server socket
238 */
239 TCPServerSocket(const string &localAddress, unsigned short localPort,
240 int queueLen = 5) throw(SocketException);
241
242 /**
243 * Blocks until a new connection is established on this socket or error
244 * @return new connection socket
245 * @exception SocketException thrown if attempt to accept a new connection fails
246 */
247 TCPSocket *accept() throw(SocketException);
248
249 private:
250 void setListen(int queueLen) throw(SocketException);
251 };
252
253 /**
254 * UDP socket class
255 */
256 class UDPSocket : public CommunicatingSocket {
257 public:
258 /**
259 * Construct a UDP socket
260 * @exception SocketException thrown if unable to create UDP socket
261 */
262 UDPSocket() throw(SocketException);
263
264 /**
265 * Construct a UDP socket with the given local port
266 * @param localPort local port
267 * @exception SocketException thrown if unable to create UDP socket
268 */
269 UDPSocket(unsigned short localPort) throw(SocketException);
270
271 /**
272 * Construct a UDP socket with the given local port and address
273 * @param localAddress local address
274 * @param localPort local port
275 * @exception SocketException thrown if unable to create UDP socket
276 */
277 UDPSocket(const string &localAddress, unsigned short localPort)
278 throw(SocketException);
279
280 /**
281 * Unset foreign address and port
282 * @return true if disassociation is successful
283 * @exception SocketException thrown if unable to disconnect UDP socket
284 */
285 void disconnect() throw(SocketException);
286
287 /**
288 * Send the given buffer as a UDP datagram to the
289 * specified address/port
290 * @param buffer buffer to be written
291 * @param bufferLen number of bytes to write
292 * @param foreignAddress address (IP address or name) to send to
293 * @param foreignPort port number to send to
294 * @return true if send is successful
295 * @exception SocketException thrown if unable to send datagram
296 */
297 void sendTo(const void *buffer, int bufferLen, const string &foreignAddress,
298 unsigned short foreignPort) throw(SocketException);
299
300 /**
301 * Read read up to bufferLen bytes data from this socket. The given buffer
302 * is where the data will be placed
303 * @param buffer buffer to receive data
304 * @param bufferLen maximum number of bytes to receive
305 * @param sourceAddress address of datagram source
306 * @param sourcePort port of data source
307 * @return number of bytes received and -1 for error
308 * @exception SocketException thrown if unable to receive datagram
309 */
310 int recvFrom(void *buffer, int bufferLen, string &sourceAddress,
311 unsigned short &sourcePort) throw(SocketException);
312
313 /**
314 * Set the multicast TTL
315 * @param multicastTTL multicast TTL
316 * @exception SocketException thrown if unable to set TTL
317 */
318 void setMulticastTTL(unsigned char multicastTTL) throw(SocketException);
319
320 /**
321 * Join the specified multicast group
322 * @param multicastGroup multicast group address to join
323 * @exception SocketException thrown if unable to join group
324 */
325 void joinGroup(const string &multicastGroup) throw(SocketException);
326
327 /**
328 * Leave the specified multicast group
329 * @param multicastGroup multicast group address to leave
330 * @exception SocketException thrown if unable to leave group
331 */
332 void leaveGroup(const string &multicastGroup) throw(SocketException);
333
334 private:
335 void setBroadcast();
336 };
337
338 #endif