ucommon

BufferProtocol Class Reference

Common buffer protocol class. More...

#include <protocols.h>

Inheritance diagram for BufferProtocol:
Collaboration diagram for BufferProtocol:

Public Types

enum  type_t { BUF_RD, BUF_WR, BUF_RDWR }

Public Member Functions

int _getch (void)
 Get a character from the buffer.
int _putch (int ch)
 Put a character into the buffer.
bool eof (void)
 Check if at end of input.
int err (void)
size_t bool flush (void)
 Flush buffered memory to physical I/O.
size_t get (char *address, size_t count)
 Get memory from the buffer.
size_t getline (char *string, size_t size)
 Get text as a line of input from the buffer.
size_t getline (string &buffer)
 Get a string as a line of input from the buffer.
bool is_input (void)
 See if input active.
bool is_open (void)
 See if buffer open.
bool is_output (void)
 See if output active.
bool is_pending (void)
 See if pending input.
 operator bool ()
 See if buffer open.
bool operator! ()
 See if buffer closed.
size_t printf (const char *format,...) __PRINTF(2
 Print formatted string to the buffer.
void purge (void)
 Purge any pending input or output buffer data.
size_t put (const char *address, size_t count=0)
 Put memory into the buffer.
size_t putline (const char *string)
 Put a string as a line of output to the buffer.
void reset (void)
 Reset input buffer state.
void seteof (void)
 Set eof flag.

Protected Member Functions

virtual bool _blocking (void)
 Return true if blocking.
virtual void _clear (void)=0
 Method to clear low level i/o error.
virtual int _err (void) const =0
 Method to get low level i/o error.
virtual bool _flush (void)
 Flush buffer to physical i/o.
virtual bool _pending (void)
 Check if data is pending.
virtual size_t _pull (char *address, size_t size)=0
 Method to pull buffer from physical i/o (read).
virtual size_t _push (const char *address, size_t size)=0
 Method to push buffer into physical i/o (write).
void allocate (size_t size, type_t access=BUF_RDWR)
 Allocate I/O buffer(s) of specified size.
 BufferProtocol ()
 Construct an empty (unallocated) buffer.
 BufferProtocol (size_t size, type_t access=BUF_RDWR)
 Construct a buffer of pre-allocated size and access type.
char * gather (size_t size)
 Gather returns a pointer to contiguous input of specified size.
void release (void)
 Release (free) buffer memory.
char * request (size_t size)
 Request workspace in output buffer.
void seteol (const char *string)
 Set end of line marker.
size_t unread (void)
 Get current input position.
size_t unsaved (void)
 Get current output position.
 ~BufferProtocol ()
 Destroy object by releasing buffer memory.

Protected Attributes

const char * format

Detailed Description

Common buffer protocol class.

This is used to create objects which will stream character data as needed. This class can support bidirectional streaming as may be needed for serial devices, sockets, and pipes. The buffering mechanisms are hidden from derived classes, and two virtuals are used to communicate with the physical transport.

Author:
David Sugar <dyfet@gnutelephony.org>

Definition at line 165 of file protocols.h.


Constructor & Destructor Documentation

BufferProtocol::BufferProtocol ( size_t  size,
type_t  access = BUF_RDWR 
) [protected]

Construct a buffer of pre-allocated size and access type.

Parameters:
sizeof buffer to allocate.
accessmode of buffer.

Member Function Documentation

virtual int BufferProtocol::_err ( void  ) const [protected, pure virtual]

Method to get low level i/o error.

Returns:
error from low level i/o methods.

Implemented in fbuf, TCPBuffer, and shell::iobuf.

int BufferProtocol::_getch ( void  ) [virtual]

Get a character from the buffer.

If no data is available, return EOF.

Returns:
character from buffer or eof.

Implements CharacterProtocol.

virtual size_t BufferProtocol::_pull ( char *  address,
size_t  size 
) [protected, pure virtual]

Method to pull buffer from physical i/o (read).

The address is passed to this virtual since it is hidden as private.

Parameters:
addressof buffer to pull data into.
sizeof buffer area being pulled..
Returns:
number of read written, 0 on error or end of data.

Implemented in fbuf, TCPBuffer, SSLBuffer, and shell::iobuf.

virtual size_t BufferProtocol::_push ( const char *  address,
size_t  size 
) [protected, pure virtual]

Method to push buffer into physical i/o (write).

The address is passed to this virtual since it is hidden as private.

Parameters:
addressof data to push.
sizeof data to push.
Returns:
number of bytes written, 0 on error.

Implemented in fbuf, TCPBuffer, SSLBuffer, and shell::iobuf.

int BufferProtocol::_putch ( int  ch) [virtual]

Put a character into the buffer.

Returns:
character put into buffer or eof.

Implements CharacterProtocol.

void BufferProtocol::allocate ( size_t  size,
type_t  access = BUF_RDWR 
) [protected]

Allocate I/O buffer(s) of specified size.

If a buffer is currently allocated, it is released.

Parameters:
sizeof buffer to allocate.
accessmode of buffer.
bool BufferProtocol::eof ( void  )

Check if at end of input.

Returns:
true if end of data, false if input still buffered.
size_t bool BufferProtocol::flush ( void  ) [inline]

Flush buffered memory to physical I/O.

Returns:
true on success, false if not active or fails.

Definition at line 340 of file protocols.h.

char* BufferProtocol::gather ( size_t  size) [protected]

Gather returns a pointer to contiguous input of specified size.

This may require moving the input data in memory.

Parameters:
sizeof gather space.
Returns:
data pointer to gathered data or NULL if not available.
size_t BufferProtocol::get ( char *  address,
size_t  count 
)

Get memory from the buffer.

This method will become "get()" in abi 4 and may become a protected method.

Parameters:
addressof characters save from buffer.
countof characters to get from buffer.
Returns:
number of characters actually copied.
size_t BufferProtocol::getline ( char *  string,
size_t  size 
)

Get text as a line of input from the buffer.

The eol character(s) are used to mark the end of a line. Because the end of line character is stripped, the length of the string may be less than the actual count read. If at the end of the file buffer and unable to read more data an error occured then 0 is returned.

Parameters:
stringto save input into.
sizelimit of string to save.
Returns:
count of characters actually read or 0 if at end of data.
size_t BufferProtocol::getline ( string buffer)

Get a string as a line of input from the buffer.

The eol character(s) are used to mark the end of a line. Because the end of line character is stripped, the length of the string may be less than the actual count read. If at the end of the file buffer and unable to read more data an error occured then 0 is returned.

Parameters:
bufferto save input into.
Returns:
count of characters actually read or 0 if at end of data.
bool BufferProtocol::is_input ( void  ) [inline]

See if input active.

Returns:
true if input active.

Definition at line 415 of file protocols.h.

bool BufferProtocol::is_open ( void  ) [inline]

See if buffer open.

Returns:
true if buffer active.

Definition at line 408 of file protocols.h.

bool BufferProtocol::is_output ( void  ) [inline]

See if output active.

Returns:
true if output active.

Definition at line 422 of file protocols.h.

bool BufferProtocol::is_pending ( void  ) [inline]

See if pending input.

Returns:
true if input pending.

Definition at line 429 of file protocols.h.

BufferProtocol::operator bool ( ) [inline]

See if buffer open.

Returns:
true if buffer active.

Definition at line 394 of file protocols.h.

bool BufferProtocol::operator! ( ) [inline]

See if buffer closed.

Returns:
true if buffer inactive.

Definition at line 401 of file protocols.h.

size_t BufferProtocol::printf ( const char *  format,
  ... 
)

Print formatted string to the buffer.

The maximum output size is the buffer size, and the operation flushes the buffer.

Parameters:
formatstring.
Returns:
number of bytes written.
size_t BufferProtocol::put ( const char *  address,
size_t  count = 0 
)

Put memory into the buffer.

If count is 0 then put as NULL terminated string. This method will become "put()" in abi 4 and may become a protected method.

Parameters:
addressof characters to put into buffer.
countof characters to put into buffer.
Returns:
number of characters actually written.
size_t BufferProtocol::putline ( const char *  string)

Put a string as a line of output to the buffer.

The eol character is appended to the end.

Parameters:
stringto write.
Returns:
total characters successfully written, including eol chars.
char* BufferProtocol::request ( size_t  size) [protected]

Request workspace in output buffer.

This returns a pointer to memory from the output buffer and advances the output position. This is sometimes used for a form of zero copy write.

Parameters:
sizeof request area.
Returns:
data pointer or NULL if not available.
void BufferProtocol::reset ( void  )

Reset input buffer state.

Drops any pending input.

void BufferProtocol::seteol ( const char *  string) [inline, protected]

Set end of line marker.

Normally this is set to cr & lf, which actually supports both lf alone and cr/lf termination of lines. However, putline() will always add the full cr/lf if this mode is used. This option only effects getline() and putline().

Parameters:
stringfor eol for getline and putline.

Definition at line 204 of file protocols.h.

size_t BufferProtocol::unread ( void  ) [inline, protected]

Get current input position.

Sometimes used to help compute and report a "tell" offset.

Returns:
offset of input buffer.

Definition at line 286 of file protocols.h.

size_t BufferProtocol::unsaved ( void  ) [inline, protected]

Get current output position.

Sometimes used to help compute a "trunc" operation.

Definition at line 293 of file protocols.h.


The documentation for this class was generated from the following file: