1 // -*- c++ -*-
2 //------------------------------------------------------------------------------
3 // Socket.h
4 //------------------------------------------------------------------------------
5 // Copyright (C) 1997-2002,2005 Vladislav Grinchenko
6 //
7 // This library is free software; you can redistribute it and/or
8 // modify it under the terms of the GNU Library General Public
9 // License as published by the Free Software Foundation; either
10 // version 2 of the License, or (at your option) any later version.
11 //------------------------------------------------------------------------------
12 //
13 // This class is a direct derivative from my Unix Network Programming
14 // class work on generalizing object-oriented network interfaces.
15 //
16 //------------------------------------------------------------------------------
17 // Created: 03/22/1999
18 //------------------------------------------------------------------------------
19
20 #ifndef SOCKET_H
21 #define SOCKET_H
22
23 #include <sys/stat.h>
24 #include <sys/time.h>
25 #include <limits.h> // for INT_MAX
26 #include <stdio.h> // for EOF
27 #include <sys/types.h>
28 #include <unistd.h>
29 #include <fcntl.h> // for fcntl(2)
30
31 #ifdef linux
32 # include <sys/ioctl.h> // ioctl(2)
33 #endif
34
35 #ifdef sun // ioctl(2)
36 # include <unistd.h>
37 # include <stropts.h>
38 # include <sys/filio.h>
39 #endif
40
41 #include "assa/Address.h"
42
43 /** @def BYTES_LEFT_IN_SOCKBUF(s)
44
45 BYTES_LEFT_IN_SOCKBUF macro returns number of unprocessed
46 bytes left in ASSA's double-buffer from EventHandler::handle_read()
47 callback.
48
49 Unless for a valid reason, this macro should always be called.
50 @param s Reference to ASSA::Socket
51 */
52 #define BYTES_LEFT_IN_SOCKBUF(s) ((s).eof () ? -1 : (s).in_avail ())
53
54 /** @def BYTES_LEFT_IN_SIN
55
56 BYTES_LEFT_IN_SIN macro returns number of unprocessed bytes left
57 in cin internal buffer.
58 */
59 #define BYTES_LEFT_IN_SIN (cin.eof () ? -1 : cin.rdbuf ()->in_avail ())
60
61
62 namespace ASSA {
63
64 class Streambuf; // Forward declaration
65
66 /** @file Socket.h
67 *
68 * Abstraction of socket data type. This will be a subclass of instream
69 */
70
71 class Socket {
72 public:
73 /// Size of bytes of a kernel page
74 static const int PGSIZE;
75
76 /** @enum io_state_t
77 * State bits: goodbit, eofbit, failbit, badbit. Meaning to
78 * these is explained in class' documentation.
79 */
80 enum io_state_t {
81 goodbit = 0, /**< indicates that socket is ready for use */
82 eofbit = 1, /**< indicates that an input operation reached the
83 end of an input sequence */
84 failbit = 2, /**< indicates that an input operation failed to read
85 the expected characters, or that an output operation
86 failed to generate the desired characters. */
87 badbit = 4 /**< indicates a loss of integrity in an input or
88 output sequence (such as an irrecoverable read
89 error from a file) */
90 };
91
92 typedef int iostate;
93 typedef unsigned char IOState;
94
95 /** @enum opt_t
96 * Socket options.
97 */
98 enum opt_t
99 {
100 reuseaddr, /**< Allow local address reuse. */
101
102 rcvlowat, /**< The receiver low-water mark is the
103 amount of data that must be in the socket receive
104 buffer for select(3) to return "readable". It defaults
105 to 1 for a TCP and UDP socket (NOTE: Posix.1g does not
106 require support for this option). */
107
108 sndlowat, /**< The send low-water mark si the amount
109 of available space that must exist in the socket send
110 buffer for select to return "writable". This low-water
111 mark normally defaults to 2048 for TCP socket. UDP
112 socket is always writable (NOTE: Posix.1g does not
113 require support for this option) */
114
115 nonblocking /**< Set Socket to a non-blocking mode (O_RDWR|O_NONBLOCK).
116
117 The default setup for a socket is BLOCKING (O_RDWR),
118 Blocking implies being suspended while waiting
119 for data to arrive on read. On write, it means
120 that there is no room to send all data out and
121 the process is being suspended until more room
122 in the output buffer becomes available.
123
124 Use nonblocking option to set the socket to
125 non-blocking mode.
126
127 For input operations, if an operation cannot be
128 satisfied (at least 1 byte of data for a TCP socket
129 or a complete datagram for a UDP socket), return is
130 made immediately with an error of EWOULDBLOCK.
131
132 For output operations, if there is no room at
133 all in the socket send buffer, return is made
134 immediately with an error of EWOULDBLOCK. If,
135 however, there is some room in the socket send buffer,
136 the return value will be the number of bytes that the
137 kernel was able to copy into the buffer
138 (This is called a short count).
139
140 NOTE: To go back to blocking mode, clear nonblocking
141 with turnOptionOff().
142 */
143 };
144
145 /// Constructor
146 Socket();
147
148 /// Destructor
149 virtual ~Socket();
150
151 /// Open socket
152 virtual bool open(const int domain_) =0;
153
154 /// Close socket
155 virtual bool close() =0;
156
157 /** Make a connection.
158
159 @param address_ address of the server to connect to
160 */
161 virtual bool connect (const Address& address_);
162
163 /** Server binds listening socket to its local well-known port.
164
165 @param my_address_ address to bind to
166 @return true if success, false otherwise
167 */
168 virtual bool bind (const Address& my_address_) =0;
169
170 /** Write specified number of bytes to the socket
171
172 @param buf_ packet to send
173 @param size_ size of the packet
174 */
175 virtual int write (const char* buf_, const u_int size_);
176
177 /** Return number of bytes available in socket receive buffer.
178 */
179 int getBytesAvail (void) const;
180
181 /** Read expected number of bytes from the socket.
182 @param buf_ buffer to save received packet to
183 @param size_ size of the packet
184 */
185 virtual int read (char* buf_, const u_int size_);
186
187 /** Extracts bytes and discards them. With no arguments,
188 read and discard until eof is encountered.
189
190 Bytes are extracted in the following manner:
191 <p>
192 <table border width=75% cellpadding=3>
193 <tr><th><b> n_ </b></th>
194 <th><b> delim_ </b></th>
195 <th><b> Action </b></th>
196 </tr>
197 <tr><td aling=center> 1 </td>
198 <td> EOF </td>
199 <td> Read and discard 1 byte </td>
200 </tr>
201 <tr><td align=center> k </td>
202 <td> EOF </td>
203 <td> Read and discard at most k bytes </td>
204 </tr>
205 <tr><td align=center> INT_MAX </td>
206 <td> EOF </td>
207 <td> Read and discard till eof is reached</td>
208 </tr>
209 <tr><td align=center> INT_MAX </td>
210 <td> 'c' </td>
211 <td> Read and discard till either 'c' or eof is found</td>
212 </tr>
213 <tr><td align=center> k </td>
214 <td> 'c' </td>
215 <td> Read and discard at most k bytes, but stop if 'c' is found</td>
216 </tr>
217 </table>
218 </p>
219
220 @param n_ number of bytes to ignore (default=INT_MAX)
221 @param delim_ delimiter to search for (default=EOF)
222 @return number of bytes discarded
223 */
224 int ignore (int n_ = INT_MAX, int delim_ = EOF);
225
226 /// Get file descriptor
227 virtual handler_t getHandler() const = 0;
228
229 /// Get socket domain
230 virtual const int getDomain() const = 0;
231
232 /** Return a pointer to the <B> Streambuf </B> associated with the
233 stream. This is part of the construction of a stream, and the
234 buffer class object is not normally changed. This function may be
235 used to get at <B> Streambuf </B> functionality directly,
236 given a Socket object.
237 Default behavior is to return NULL.
238 @return NULL
239 */
rdbuf()240 virtual Streambuf* rdbuf () { return 0; }
241
242 /** Virtual function that sets new socket buffer
243 and returns the old one.
244 Default behavior is to return NULL.
245 @return Old Socketbuf object.
246 */
rdbuf(Streambuf *)247 virtual Streambuf* rdbuf (Streambuf* /*sb_*/) { return 0; }
248
249 /** This function returns the number of characters
250 immediately available in the get area of the underlying
251 Socketbuf buffer without making a system call if Socket
252 is doing buffering I/O. It is certain that returned number of
253 characters may be fetched without error, and without
254 accessing any external device.
255 */
256 virtual int in_avail () const = 0;
257
258 /** This function simply calls the public "synchronizing" function
259 <B>rdbuf()->pubsync()</B> (assuming the associated
260 <B>streambuf</B> object is present). Typically, such an
261 operation flushes an output stream to the associated external
262 pipe.
263 */
264 virtual Socket& flush ();
265
266 /** Enable socket option
267 @param opt_ option name
268 @return true on success; false if error
269 */
270 bool turnOptionOn (opt_t opt_);
271
272 /** Disable socket option
273 @param opt_ option name
274 @return true on success; false if error
275 */
276 bool turnOptionOff (opt_t opt_);
277
278 /** Set socket option to value required.
279
280 @param opt_ option name
281 @param arg_ value to set (for binary: 0 - disable, 1 - enable).
282 @return true on success_; false if error
283 */
284 bool setOption (opt_t opt_, int arg_);
285
286 /** Get current value of a socket option.
287 @param opt_ option name
288 @return option value on success (for binary: 0 - disable,
289 1 - enabled); -1 if error
290 */
291 int getOption (opt_t opt_) const;
292
293 /// Convertion to void* (for testing where bool is required)
294 operator void* () const;
295
296 /// Alias to fail()
297 bool operator! () const;
298
299 /** Retrieve state of the socket
300 @return control state of the socket
301 */
rdstate()302 iostate rdstate () const { return m_state; }
303
304 /// Clear the socket state. Closed socket remains in bad state.
305 void clear (iostate state_ = Socket::goodbit);
306
307 /** Set socket state to flag_ by adding flag_ to the existing state.
308 * @param flag_ new state
309 */
310 void setstate (iostate flag_);
311
312 /** Indicates no error on the socket.
313 @return true if goodbit is set, false otherwise
314 */
good()315 bool good () const { return m_state == 0; }
316
317 /** An earlier extraction operation has encountered the end
318 of file of the input stream (peer closed its socket).
319 @return true if peer closed the socket; false otherwise
320 */
eof()321 bool eof () const { return m_state & Socket::eofbit; }
322
323 /** Indicates that earlier extraction opeartion has failed to
324 match the required pattern of input. Socket should be
325 closed at this point by the owner.
326 @return true if failbit or badbit is set, false otherwise
327 */
fail()328 bool fail () const
329 {
330 return m_state & (Socket::failbit | Socket::badbit);
331 }
332
333 /** Socket fd == -1 or read/write error occured or some loss
334 of integrity on assosiated stream buffer.
335 @return true if badbit is set, false otherwise
336 */
bad()337 bool bad () const { return m_state & Socket::badbit; }
338
339 /// Write state bits of the socket to the log file.
340 void dumpState () const;
341
342 /// Give the true length of the XDR-encoded STL string.
xdr_length(const std::string & s_)343 static size_t xdr_length (const std::string& s_)
344 {
345 return (4 + s_.length () + s_.length () % 4);
346 }
347
348 /// Input of built-in char type. The value will be XDR-decoded.
349 Socket& operator>> (char& c);
350
351 /// Input of built-in u_char type. The value will be XDR-decoded.
352 Socket& operator>> (unsigned char& c_)
353 {
354 return operator>>((char&) c_);
355 }
356
357 /// Input of built-in signed char type. The value will be XDR-decoded.
358 Socket& operator>> (signed char& c_)
359 {
360 return operator>>((char&) c_);
361 }
362
363 /// Input of STL string type. The string content will be XDR-decoded.
364 Socket& operator>> (std::string& s_);
365
366 /// Input of built-in short type. The value will be XDR-decoded.
367 Socket& operator>> (short& n_);
368
369 /// Input of built-in u_short type. The value will be XDR-decoded.
370 Socket& operator>> (unsigned short& n_);
371
372 /// Input of built-in integer type. The value will be XDR-decoded.
373 Socket& operator>> (int& n_);
374
375 /// Input of built-in u_int type. The value will be XDR-decoded.
376 Socket& operator>> (unsigned int& n_);
377
378 /// Input of built-in long type. The value will be XDR-decoded.
379 Socket& operator>> (long& n_);
380
381 /// Input of built-in u_long type. The value will be XDR-decoded.
382 Socket& operator>> (unsigned long& n_);
383
384 /// Input of built-in float type. The value will be XDR-decoded.
385 Socket& operator>> (float& n_);
386
387 /// Input of built-in double type. The value will be XDR-decoded.
388 Socket& operator>> (double& n_);
389
390 /// Output of built-in char type. The value will be XDR-encoded.
391 Socket& operator<< (char c);
392
393 /// Output of built-in u_char type. The value will be XDR-encoded.
394 Socket& operator<< (unsigned char c_)
395 {
396 return (*this) << (char) c_;
397 }
398
399 /// Output of built-in signed char type. The value will be XDR-encoded.
400 Socket& operator<< (signed char c_)
401 {
402 return (*this) << (char) c_;
403 }
404
405 /// Output of STL string type. The value will be XDR-encoded.
406 Socket& operator<< (const std::string& s_);
407
408 /// Output of built-in short type. The value will be XDR-encoded.
409 Socket& operator<< (short n_);
410
411 /// Output of built-in u_short type. The value will be XDR-encoded.
412 Socket& operator<< (unsigned short n_);
413
414 /// Output of built-in integer type. The value will be XDR-encoded.
415 Socket& operator<< (int n_);
416
417 /// Output of built-in u_int type. The value will be XDR-encoded.
418 Socket& operator<< (unsigned int n_);
419
420 /// Output of built-in long type. The value will be XDR-encoded.
421 Socket& operator<< (long n_);
422
423 /// Output of built-in u_long type. The value will be XDR-encoded.
424 Socket& operator<< (unsigned long n_);
425
426 /// Output of built-in float type. The value will be XDR-encoded.
427 Socket& operator<< (float n_);
428
429 /// Output of built-in double type. The value will be XDR-encoded.
430 Socket& operator<< (double n_);
431
432 /// Manipulators plug-in operator
433 Socket& operator<< (Socket& (*f) (Socket&))
434 {
435 return (f (*this));
436 }
437
438 /** Determine the endianess of the platform we are on.
439 *
440 * @return true if it is a little-endian host;
441 * false if a big-endian host.
442 */
443 static bool is_little_endian ();
444
445 /** Close socket endpoint in a portable way.
446 * Socket is also set to an invalid value.
447 */
close_handler(handler_t & socket_)448 static void close_handler (handler_t& socket_)
449 {
450 #if defined (WIN32)
451 closesocket (socket_);
452 #else
453 ::close (socket_);
454 #endif
455 disable_handler (socket_);
456 }
457
458 /** Decipher flags packed into mask_ used in fcntl() call.
459 */
460 static string decode_fcntl_flags (long mask_);
461
462 /*------------------------------------------------------------------
463 * Protected Members
464 *------------------------------------------------------------------
465 */
466 protected:
467 /** Gateway method of setting socket options.
468 @return 0 on success, -1 on error (setsockopt(2) failed)
469 */
470 int set_option (int level_, int optname_, int val_);
471
472 /** Gateway method for setting file descriptor options.
473 @return 0 on success, -1 on error (fcntl(2) failed)
474 */
475 int set_fd_options (long flags_);
476
477 /** Gateway method for clearing file descriptor options.
478 @return 0 on success, -1 on error (fcntl(2) failed)
479 */
480 int clear_fd_options (long flags_);
481
482 protected:
483 /** File descriptor
484 */
485 handler_t m_fd; // u_int, INVALID_SOCKET=(SOCKET)(~0)
486
487 /// Socket domain type
488 int m_type;
489
490 #if defined (WIN32)
491 bool m_nonblocking; // We cannot retrieve the status of the
492 // socket. So, we remember what it was instead.
493 #endif
494
495 /// Control state of the socket
496 IOState m_state;
497
498 //------------------------------------------------------------------------------
499 // Inline functions
500 //------------------------------------------------------------------------------
501
502 private:
503 /** The copy constructor and assignment operator are private
504 to prevent copying of <B> Socket </B> objects, since the
505 effect of such copying is not well defined. Usually you
506 want to copy a pointer to the object, or pass a reference
507 to a function.
508 */
509 Socket (const Socket&);
510 Socket& operator= (const Socket&);
511 };
512
513 //------------------------------------------------------------------------------
514 // Inline functions
515 //------------------------------------------------------------------------------
516
517 inline
Socket()518 Socket::Socket()
519 :
520 m_fd (BAD_HANDLER),
521 m_type(0),
522 #if defined (WIN32)
523 m_nonblocking (false),
524 #endif
525 m_state(Socket::badbit)
526 {
527 trace_with_mask("Socket::Socket",SOCKTRACE);
528 }
529
530 inline
~Socket()531 Socket::~Socket ()
532 {
533 trace_with_mask("Socket::~Socket",SOCKTRACE);
534 }
535
536 inline bool
connect(const Address &)537 Socket::connect (const Address& /* address_ */)
538 {
539 trace_with_mask("Socket::connect",SOCKTRACE);
540 return false;
541 }
542
543 inline int
write(const char *,const u_int)544 Socket::write(const char* /*buf_*/, const u_int /*size_*/)
545 {
546 trace_with_mask("Socket::write",SOCKTRACE);
547 return -1;
548 }
549
550 inline int
read(char *,const u_int)551 Socket::read(char* /*buf_*/, const u_int /*size_*/)
552 {
553 trace_with_mask("Socket::read()",SOCKTRACE);
554 return -1;
555 }
556
557 inline
558 Socket::operator void*() const
559 {
560 return fail() ? (void *)0 : (void *)(-1);
561 }
562
563 inline bool
564 Socket::operator!() const
565 {
566 return fail();
567 }
568
569
570 inline void
clear(iostate state_)571 Socket::clear(iostate state_)
572 {
573 m_state = is_valid_handler (m_fd) ? state_ : state_ | Socket::badbit;
574 }
575
576 inline void
setstate(iostate flag_)577 Socket::setstate(iostate flag_)
578 {
579 m_state |= flag_;
580 }
581
582 /** flush manipulator.
583
584 Flush a stream buffer.
585 */
586 inline
flush(Socket & os_)587 Socket& flush (Socket& os_)
588 {
589 os_.flush ();
590 return (os_);
591 }
592
593 /** endl manipulator.
594
595 If you want to insert a newline character ('\n') to terminate a text line,
596 you should favor the manipulator <B>endl</B>. This manipulator inserts
597 a newline character and also flushes the stream buffer.
598
599 @author Vladislav Grinchenko
600 */
601 inline
endl(Socket & os_)602 Socket& endl (Socket& os_)
603 {
604 char c = '\n';
605 os_.write (&c, 1);
606 os_.flush ();
607 return (os_);
608 }
609
610 /** ends manipulator.
611
612 You can insert a null character (without flushing the output stream) with
613 the manipulator <B>ends</B>. A common use for a <B>Socket</B> object is
614 to mediate output to a stream buffer that constructs an in-memory character
615 sequence. Such a sequence wants a terminating null character.
616 The manipulator <B>ends</B> provides highly visible evidence that the null
617 character is indeed being supplied.
618
619 @author Vladislav Grinchenko
620 */
621 inline
ends(Socket & os_)622 Socket& ends (Socket& os_)
623 {
624 char c = '\0';
625 os_.write (&c, 1);
626 return (os_);
627 }
628
629 } // end namespace ASSA
630
631 #include "assa/Streambuf.h"
632
633 #endif // SOCKET_H
634
635
636
637