sockets::TCPClient Class Reference

TCP client class. More...

#include <tcpclient.h>

Inheritance diagram for sockets::TCPClient:

sockets::IPSocket sockets::Socket sockets::TCPSocket List of all members.

Public Types

enum  { poInBuf = 0x0001, poLine = 0x0002 }
 printf() options More...

Public Member Functions

 TCPClient (Buffer *rbuf=0, Buffer *wbuf=0)
 Constructor.
 TCPClient (TCPClient const &tcpc)
 Copy constructor.
virtual TCPClientoperator= (TCPClient const &right)
 Assignment operator.
virtual bool assign (int fd, uint32_t status)
 Assigns a socket file descriptor.
virtual bool close ()
 Overrides Socket::close().
virtual ssize_t read (char *buf, size_t len)
 Reads data from socket directly.
virtual ssize_t read_inbuf (size_t max=0)
 Reads data from socket in the read buffer.
virtual ssize_t read_line (char *buf, size_t len) const
 Reads a line from the read buffer.
virtual ssize_t write (char const *buf, size_t len, bool inbuf=false)
 Writes data to the socket, falling back on buffer if it blocks.
virtual ssize_t write_str (char const *str, bool inbuf=false)
 Same as write() but uses a NUL-terminated string as buffer.
virtual ssize_t write_string (std::string const &str, bool inbuf=false)
 Same as write_str() but uses a std::string as buffer.
virtual ssize_t write_line (char const *line, bool inbuf=false)
 Writes a line to the socket.
virtual ssize_t printf (uint32_t options, char const *format,...) FORMAT(printf
 Writes to the socket, printf()-like style.
virtual ssize_t virtual ssize_t vprintf (uint32_t options, char const *format, va_list args)
 Writes to the socket, vprintf()-like style.
virtual ssize_t write_outbuf (size_t max=0)
 Writes data from the write buffer to the socket.
virtual ssize_t write_unbuffered (char const *buf, size_t len)
 Writes data to the socket directly.
Bufferrbuf () const
 Returns the read buffer.
Bufferrbuf (Buffer *rbuf)
 Sets the read buffer.
Bufferwbuf () const
 Returns the write buffer.
Bufferwbuf (Buffer *wbuf)
 Sets the write buffer.
std::string const & linesep () const
 Returns the line separator of the socket.
std::string const & linesep (std::string const linesep)
 Sets the line separator of the socket.

Protected Member Functions

virtual ssize_t read_real (void *buf, size_t len)
 Actually calls the recv() function.
virtual ssize_t write_real (void const *buf, size_t len)
 Actually calls the send() function.
virtual bool read_event ()
 Read event handling.
virtual bool write_event ()
 Write event handling.
virtual bool on_connect (int error)
 Connect event.
virtual bool on_read ()
 Read event.
virtual bool on_write ()
 Write event.
virtual bool on_writing ()
 Writing event.

Detailed Description

This class is used to represent connected TCP clients, both those initiated through client sockets and server sockets. It has therefore no way of actually connecting to a socket.

This class provides functions for reading and writing from/to the socket, and event handlers.


Member Enumeration Documentation

anonymous enum
 

Enumerator:
poInBuf  Always write data to the write buffer.
poLine  Add line separator to the output.

Reimplemented from sockets::Socket.


Constructor & Destructor Documentation

sockets::TCPClient::TCPClient Buffer rbuf = 0,
Buffer wbuf = 0
[inline, explicit]
 

Constructor.

Parameters:
[in] rbuf If non-zero, points to the read buffer of the socket.
[in] wbuf If non-zero, points to the write buffer of the socket.
See also:
rbuf(), wbuf()

sockets::TCPClient::TCPClient TCPClient const &  tcpc  )  [inline]
 

This copy constructor copies the line separator but NOT the read and write buffer.


Member Function Documentation

virtual bool sockets::TCPClient::assign int  fd,
uint32_t  status
[virtual]
 

Assigns a socket file descriptor to the socket object, that is then used by the object for all operations on the socket.

This function overrides IPSocket::assign() to call the on_connect(), on_read() and on_write() functions as needed.

Parameters:
[in] fd The socket file descriptor to assign.
[in] status The status flags that are added to the socket. If the ssMonitored flag is among them, the watch() function is automatically called. on_connect(), on_write() and on_read() are called respectively when the ssConnected, ssWritable and ssReadable flags are among them.
Returns:
true if successful, false otherwise. errno is set accordingly in the latter case.

Reimplemented from sockets::IPSocket.

virtual bool sockets::TCPClient::close  )  [virtual]
 

This function overrides Socket::close to call the shutdown() function on the socket. It also clears the read and write buffers, if set.

Returns:
the same values as Socket::close().

Reimplemented from sockets::Socket.

std::string const& sockets::TCPClient::linesep  )  const [inline]
 

Returns the line separator of the socket, that is used by the write_line() function.

Returns:
The line separator of the socket.

virtual bool sockets::TCPClient::on_connect int  error  )  [inline, protected, virtual]
 

This function is called whenever a successful connection attempt finishes, or an asynchronous connection attempt fails.

The default implementation just returns true.

Parameters:
[in] error This is set to zero if the connection is established, or is the error number that occured otherwise.
Returns:
false if the socket has been closed or is no longer valid, true otherwise.

virtual bool sockets::TCPClient::on_read  )  [inline, protected, virtual]
 

This function is called whenever the socket becomes readable (there is new data to be read).

The default implementation just returns true.

Returns:
false if the socket has been closed or is no longer valid, true otherwise.

virtual bool sockets::TCPClient::on_write  )  [inline, protected, virtual]
 

This function is called whenever the socket becomes writable (new data can be sent through the socket).

The default implementation just returns true. It is highly recommended that you ouverride this function to call the write_outbuf() if you use buffered output functions of the socket.

Returns:
false if the socket has been closed or is no longer valid, true otherwise.

virtual bool sockets::TCPClient::on_writing  )  [inline, protected, virtual]
 

This event is called by the write() function whenever there is data in the buffer, which means the write() would normally write to the buffer without trying to actually write data to the socket.

You may therefore want to call the write_outbuf() function from here if you want your data to be sent faster than waiting for the on_write() event to be called.

The default implementation just returns true.

Returns:
true if no error other than EAGAIN or EWOULDBLOCK happened on the socket, false otherwise.

virtual ssize_t sockets::TCPClient::printf uint32_t  options,
char const *  format,
  ...
[virtual]
 

Writes to the socket, printf()-like style. The actual writing is done through the write() function by default.

Parameters:
[in] options An or'ed set of either
  • pfInBuf: always write to the write buffer even if sending it directly through the socket could be tried.
  • pfLine: writing is done through write_line().
[in] format The format string.
[in] ... Args for the format string.
Returns:
whatever is returned by the write() or write_line() function.

Buffer* sockets::TCPClient::rbuf Buffer rbuf  )  [inline]
 

Sets the read buffer. By default, there is no read buffer, and it is not required to set one unless you intend to use functions that manipulate it.

Please note that the socket does not try to free the buffer once it is deleted; you have to take care of that by yourself.

Parameters:
[in] rbuf The read buffer.
Returns:
The new read buffer.

Buffer* sockets::TCPClient::rbuf  )  const [inline]
 

Returns the read buffer. This buffer is mainly used by the read_inbuf() function, with other functions expecting to find data in it (of course, you are free to use the function provided by the Buffer class as well).

Returns:
The read buffer.

virtual ssize_t sockets::TCPClient::read char *  buf,
size_t  len
[virtual]
 

Reads data from socket directly, without touching to the eventual read buffer set to the socket. Reading is done regardless of whether the ssReadable status flag is set, but the ssConnected flag needs to be set.

Parameters:
[in] buf The buffer that will receive the data read from the socket.
[in] len The length of the buffer, in bytes.
Returns:
The number of bytes read from the socket, or -1 on error. A return value of 0 means that an orderly shutdown has been made on the other end of the socket, or that the ssConnected status flag wasn't set.

virtual bool sockets::TCPClient::read_event  )  [protected, virtual]
 

This function sets the ssReadable status flag, then calls the on_read() function and finishes by calling watch() to update the events being monitored, if ssReadable is still set on return.

Returns:
false if the socket has been closed or is no longer valid, true otherwise.

Reimplemented from sockets::Socket.

virtual ssize_t sockets::TCPClient::read_inbuf size_t  max = 0  )  [virtual]
 

Reads data from socket in the read buffer. Reading is done regardless of whether the ssReadable status flag is set, but the ssConnected flag needs to be set.

Parameters:
[in] max The maximum number of bytes to read from the socket. Set this to zero if you want to fill the buffer with all the data available (provided the socket is big enough, of course!)
Returns:
The number of bytes that were put in the buffer. On error, -1 is returned if errno is set to anything else than EAGAIN (or EWOULDBLOCK), else either the number of bytes that were put in the buffer (if non-zero) or -1 is returned. If the other end shut down the connection, 0 is returned, unless there were bytes put in the buffer. 0 is also returned if the ssConnected flag is not set or if the buffer is already full.

virtual ssize_t sockets::TCPClient::read_line char *  buf,
size_t  len
const [virtual]
 

Reads a line from the read buffer. The read buffer must have been filled by a call to the read_inbuf() function. Line separator is the LF character, any CR character found before or after is ignored.

Parameters:
[in] buf A buffer that will receive a copy of the line that has been found on success. The copy does not include the trailing CR or LF characters but will be NULL terminated.
[in] len The length of the buffer, in bytes. This also determines the maximum length allowed for lines before giving up.
Returns:
the length of the line if an entire line has been found in the buffer, 0 if no line was found, -1 on error (most likely, a line longer than len in the buffer).

virtual ssize_t sockets::TCPClient::read_real void *  buf,
size_t  len
[protected, virtual]
 

Actually calls the recv() function. The ssReadable flag is removed and watch() is called if the read would block (i.e. errno == EAGAIN).

Parameters:
[in] buf The buffer that will receive the data read from the socket.
[in] len The length of the buffer, in bytes.
Returns:
The number of bytes read from the socket, or -1 on error. A return value of 0 means that an orderly shutdown has been made on the other end of the socket.

virtual ssize_t virtual ssize_t sockets::TCPClient::vprintf uint32_t  options,
char const *  format,
va_list  args
[virtual]
 

Writes to the socket, vprintf()-like style. The actual writing is done through the write() function by default.

Parameters:
[in] options An or'ed set of either
  • pfInBuf: always write to the write buffer even if sending it directly through the socket could be tried.
  • pfLine: writing is done through write_line().
[in] format The format string.
[in] args Args for the format string.
Returns:
whatever is returned by the write() or write_line() function.

Buffer* sockets::TCPClient::wbuf Buffer wbuf  )  [inline]
 

Sets the write buffer. By default, there is no write buffer, but it is highly recommended to set one.

Please note that the socket does not try to free the buffer once it is deleted; you have to take care of that by yourself.

Parameters:
[in] wbuf The write buffer.
Returns:
The new write buffer.

Buffer* sockets::TCPClient::wbuf  )  const [inline]
 

Returns the write buffer. This buffer is mainly used to store data that needs to be written to the socket, in case it is not possible to do it immediately.

Returns:
The write buffer.

virtual ssize_t sockets::TCPClient::write char const *  buf,
size_t  len,
bool  inbuf = false
[virtual]
 

Writes data to the socket, falling back on the buffer if it blocks. Writing is done regardless of whether the ssWritable status flag is set, but the ssConnecting or ssConnected flags need to be set.

The on_writing() function is called before doing anything if the ssConnected flag is set.

This function will write to the write buffer instead of the socket when one of the following conditions is true:

  • writing to the socket would block;
  • there is already data in the write buffer;
  • the ssConnecting status flag is set;
  • the inbuf parameter is set to true. Attempts to send the data from the write buffer to the socket can then be made through the write_outbuf() function, that is generally called from the on_write() and on_writing() functions.

Parameters:
[in] buf A buffer containing the data to write to the socket.
[in] len The length of the buffer, in bytes.
[in] inbuf If true, the data is always written to the write buffer even if sending it directly through the socket could be tried.
Returns:
The len parameter if everything has either been sent through the socket or written in the buffer, 0 if the socket is not connecting or connected, between 0 and len-1 if the buffer is full, and -1 if there was an error on the socket other than EAGAIN or EWOULDBLOCK.

virtual bool sockets::TCPClient::write_event  )  [protected, virtual]
 

This function sets the ssConnected and ssWritable status flags then calls the on_connect() function if the ssConnecting status flag is set (this flag is removed prior to calling the function). Note that the ssConnected flag is NOT set if the connection failed.

Then, it'll call the on_write() function if the ssWritable flag is still set. If this flag is then still set, the watch() function is called to update the events being monitored.

Returns:
false if the socket has been closed or is no longer valid, true otherwise.

Reimplemented from sockets::Socket.

virtual ssize_t sockets::TCPClient::write_line char const *  line,
bool  inbuf = false
[virtual]
 

Writes a line to the socket. This is done by writing the given line and the socket line separator to the write buffer, and then call write_outbuf().

Parameters:
[in] line The line to write, without the line separators.
[in] inbuf If true, write_outbuf() is NOT called after the line has been written to the socket.
Returns:
The total number of characters written to the buffer on success, 0 if the socket is not connecting or connected or if the buffer could not contain the whole data, -1 if the write_outbuf() function failed.

virtual ssize_t sockets::TCPClient::write_outbuf size_t  max = 0  )  [virtual]
 

Writes as much data as possible from the write buffer to the socket. Writing is done regardless of whether the ssWritable status flag is set, but the ssConnected flag needs to be set.

Parameters:
[in] max The maximum number of bytes from the buffer to write. Set this to zero if you don't want to set a limit.
Returns:
The number of bytes that were written to the socket, 0 if the socket is not connected or if the write buffer is empty, or -1 if there was an error and errno was not set to EAGAIN or EWOULDBLOCK.

virtual ssize_t sockets::TCPClient::write_real void const *  buf,
size_t  len
[protected, virtual]
 

Actually calls the send() function. The ssWritable flag is removed and watch() is called if the write would block (i.e. errno == EAGAIN).

Parameters:
[in] buf A buffer containing the data to write to the socket.
[in] len The length of the buffer, in bytes.
Returns:
The number of bytes that were sent, or -1 on on error.

virtual ssize_t sockets::TCPClient::write_unbuffered char const *  buf,
size_t  len
[virtual]
 

Writes data to the socket directly, without touching to the eventual write buffer set to the socket. Writing is done regardless of whether the ssWritable status flag is set, but the ssConnected flag needs to be set.

Parameters:
[in] buf A buffer containing the data to write to the socket.
[in] len The length of the buffer, in bytes.
Returns:
The number of bytes that were sent, 0 if the socket is not connected, or -1 on error.


The documentation for this class was generated from the following file:
Generated on Sun May 20 21:32:23 2007 for Epona API by  doxygen 1.4.6