kdecore Library API Documentation

KBufferedIO Class Reference

This abstract class implements basic functionality for buffered input/output. Buffered I/O. More...

#include <kbufferedio.h>

Inheritance diagram for KBufferedIO:

Inheritance graph
[legend]
Collaboration diagram for KBufferedIO:

Collaboration graph
[legend]
List of all members.

Public Types

enum  closeModes {
  availRead = 0x01, dirtyWrite = 0x02, involuntary = 0x10, delayed = 0x20,
  closedNow = 0x40
}
 The modes for closed() signal. More...


Signals

void bytesWritten (int nbytes)
 This signal gets sent whenever bytes are written from the buffer.

void closed (int state)
 This signal gets sent when the stream is closed.


Public Member Functions

virtual ~KBufferedIO ()
 Destroys this class.

virtual void closeNow ()=0
 Closes the stream now, discarding the contents of the write buffer.

virtual bool setBufferSize (int rsize, int wsize=-2)
 Sets the internal buffer size to value.

virtual int bytesAvailable () const
 Returns the number of bytes available for reading in the read buffer.

virtual int waitForMore (int msec)=0
 Waits for more data to be available and returns the amount of available data then.

virtual int bytesToWrite () const
 Returns the number of bytes yet to write, still in the write buffer.

virtual bool canReadLine () const
 Checks whether there is enough data in the buffer to read a line.

virtual int peekBlock (char *data, uint maxlen)=0
 Reads into the user buffer at most maxlen bytes, but does not consume that data from the read buffer.

virtual int unreadBlock (const char *data, uint len)
 Unreads some data.


Protected Member Functions

virtual unsigned consumeReadBuffer (unsigned nbytes, char *destbuffer, bool discard=true)
 Consumes data from the input buffer.

virtual void consumeWriteBuffer (unsigned nbytes)
 Consumes data from the output buffer.

virtual unsigned feedReadBuffer (unsigned nbytes, const char *buffer, bool atBeginning=false)
 Feeds data into the input buffer.

virtual unsigned feedWriteBuffer (unsigned nbytes, const char *buffer)
 Feeds data into the output buffer.

virtual unsigned readBufferSize () const
 Returns the number of bytes in the read buffer.

virtual unsigned writeBufferSize () const
 Returns the number of bytes in the write buffer.

virtual void virtual_hook (int id, void *data)

Protected Attributes

QPtrList< QByteArrayinBuf
 For an explanation on how this buffer work, please refer to the comments at the top of kbufferedio.cpp.

QPtrList< QByteArrayoutBuf
 For an explanation on how this buffer work, please refer to the comments at the top of kbufferedio.cpp.

unsigned inBufIndex
unsigned outBufIndex

Detailed Description

This abstract class implements basic functionality for buffered input/output. Buffered I/O.

Through the available methods, you can find out how many bytes are available for reading, how many are still unsent and you can peek at the buffered data.

This class was intentionally written to resemble QSocket, because KExtendedSocket is a subclass of this one. This is so that applications written using QSocket's buffering characteristics will be more easily ported to the more powerful KExtendedSocket class.

KBufferedIO already provides a powerful internal buffering algorithm. However, this does not include the I/O itself, which must be implemented in derived classes. Thus, to implement a class that does some I/O, you must override, in addition to the pure virtual QIODevice methods, these two:

If your derived class reimplements the buffering algorithm, you must then decide which buffering functions to override. For instance, you may want to change the protected functions like feedReadBuffer() and consumeReadBuffer().

Author:
Thiago Macieira <thiagom@mail.com>
Version:
Id
kbufferedio.h,v 1.10 2002/09/08 15:15:33 tjansen Exp

Definition at line 59 of file kbufferedio.h.


Member Enumeration Documentation

enum KBufferedIO::closeModes
 

The modes for closed() signal.

Definition at line 71 of file kbufferedio.h.


Constructor & Destructor Documentation

KBufferedIO::~KBufferedIO  )  [virtual]
 

Destroys this class.

The flushing of the buffers is implementation dependant. The default implementation discards the contents

Definition at line 97 of file kbufferedio.cpp.


Member Function Documentation

virtual void KBufferedIO::closeNow  )  [pure virtual]
 

Closes the stream now, discarding the contents of the write buffer.

That is, we won't try to flush that buffer before closing. If you want that buffer to be flushed, you can call QIODevice::flush(), which is blocking, and then closeNow, or you can call QIODevice::close() for a delayed close.

Implemented in KExtendedSocket.

bool KBufferedIO::setBufferSize int  rsize,
int  wsize = -2
[virtual]
 

Sets the internal buffer size to value.

Not all implementations support this.

The parameters may be 0 to make the class unbuffered or -1 to let the class choose the size (which may be unlimited) or -2 to leave the buffer size untouched.

Note that setting the write buffer size to any value smaller than the current size of the buffer will force it to flush first, which can make this call blocking.

The default implementation does not support setting the buffer sizes. You can only call this function with values -1 for "don't care" or -2 for "unchanged"

Parameters:
rsize the size of the read buffer
wsize the size of the write buffer
Returns:
true if setting both was ok. If false is returned, the buffers were left unchanged.

Reimplemented in KExtendedSocket.

Definition at line 104 of file kbufferedio.cpp.

int KBufferedIO::bytesAvailable  )  const [virtual]
 

Returns the number of bytes available for reading in the read buffer.

Returns:
the number of bytes available for reading

Reimplemented in KExtendedSocket.

Definition at line 114 of file kbufferedio.cpp.

References readBufferSize().

Referenced by KExtendedSocket::bytesAvailable(), and canReadLine().

virtual int KBufferedIO::waitForMore int  msec  )  [pure virtual]
 

Waits for more data to be available and returns the amount of available data then.

Parameters:
msec number of milliseconds to wait, -1 to wait forever
Returns:
-1 if we cannot wait (e.g., that doesn't make sense in this stream)

Implemented in KExtendedSocket.

int KBufferedIO::bytesToWrite  )  const [virtual]
 

Returns the number of bytes yet to write, still in the write buffer.

Returns:
the number of unwritten bytes in the write buffer

Definition at line 119 of file kbufferedio.cpp.

References writeBufferSize().

bool KBufferedIO::canReadLine  )  const [virtual]
 

Checks whether there is enough data in the buffer to read a line.

The default implementation reads directly from inBuf, so if your implementation changes the meaning of that member, then you must override this function.

Returns:
true when there is enough data in the buffer to read a line

Definition at line 125 of file kbufferedio.cpp.

References bytesAvailable(), QPtrList::first(), and QPtrList::next().

virtual int KBufferedIO::peekBlock char *  data,
uint  maxlen
[pure virtual]
 

Reads into the user buffer at most maxlen bytes, but does not consume that data from the read buffer.

This is useful to check whether we already have the needed data to process something.

This function may want to try and read more data from the system provided it won't block.

Parameters:
data the user buffer pointer, at least maxlen bytes long
maxlen the maximum length to be peeked
Returns:
the number of bytes actually copied.

Implemented in KExtendedSocket.

int KBufferedIO::unreadBlock const char *  data,
uint  len
[virtual]
 

Unreads some data.

That is, write the data to the beginning of the read buffer, so that next calls to readBlock or peekBlock will see this data instead.

Note not all devices implement this since this could mean a semantic problem. For instance, sockets are sequential devices, so they won't accept unreading.

Parameters:
data the data to be unread
size the size of the data
Returns:
the number of bytes actually unread

Reimplemented in KExtendedSocket.

Definition at line 155 of file kbufferedio.cpp.

References feedReadBuffer().

void KBufferedIO::bytesWritten int  nbytes  )  [signal]
 

This signal gets sent whenever bytes are written from the buffer.

Parameters:
nbytes the number of bytes sent.

Referenced by KExtendedSocket::flush(), and KExtendedSocket::writeBlock().

void KBufferedIO::closed int  state  )  [signal]
 

This signal gets sent when the stream is closed.

The state parameter will give the current state, in OR-ed bits:

  • availRead: read buffer contains data to be read
  • dirtyWrite: write buffer wasn't empty when the stream closed
  • involuntary: the stream wasn't closed due to user request (i.e., call to close). Probably remote end closed it
  • delayed: the stream was closed voluntarily by the user, but it happened only after the write buffer was emptied
  • closedNow: the stream was closed voluntarily by the user, by explicitly calling closeNow, which means the write buffer's contents may have been discarded
    Parameters:
    state the state (see function description)

Referenced by KExtendedSocket::close(), and KExtendedSocket::closeNow().

unsigned KBufferedIO::consumeReadBuffer unsigned  nbytes,
char *  destbuffer,
bool  discard = true
[protected, virtual]
 

Consumes data from the input buffer.

That is, this will copy the data stored in the input (read) buffer into the given destbuffer, as much as nbytes.

Parameters:
nbytes the maximum amount of bytes to copy into the buffer
destbuffer the destination buffer into which to copy the data
discard whether to discard the copied data after the operation
Returns:
the real amount of data copied. If it is less than nbytes, then all the buffer was copied.

Definition at line 164 of file kbufferedio.cpp.

References QPtrList< QByteArray >::first(), inBuf, QPtrList< QByteArray >::next(), readBufferSize(), and QPtrList< QByteArray >::remove().

Referenced by KExtendedSocket::peekBlock(), KExtendedSocket::readBlock(), KExtendedSocket::release(), and KExtendedSocket::setBufferSize().

void KBufferedIO::consumeWriteBuffer unsigned  nbytes  )  [protected, virtual]
 

Consumes data from the output buffer.

Since this is called whenever we managed to send data out the wire, we can only discard this amount from the buffer. There is no copying and no "peeking" for the output buffer.

Note this function should be called AFTER the data was sent. After it is called, the data is no longer available in the buffer. And don't pass wrong nbytes values.

Parameters:
nbytes the amount of bytes to discard

Definition at line 214 of file kbufferedio.cpp.

References QPtrList< QByteArray >::current(), QPtrList< QByteArray >::first(), outBuf, and QPtrList< QByteArray >::remove().

Referenced by KExtendedSocket::flush(), KExtendedSocket::release(), and KExtendedSocket::setBufferSize().

unsigned KBufferedIO::feedReadBuffer unsigned  nbytes,
const char *  buffer,
bool  atBeginning = false
[protected, virtual]
 

Feeds data into the input buffer.

This happens when we detected available data in the device and read it.

The data will be appended to the buffer or inserted at the beginning, depending on whether atBeginning is set or not.

Parameters:
nbytes the number of bytes in the buffer
buffer the data that was read
atBeginning whether to append or insert at the beginning
Returns:
the number of bytes that have been appended

Definition at line 243 of file kbufferedio.cpp.

References QPtrList< QByteArray >::append(), inBuf, and QPtrList< QByteArray >::prepend().

Referenced by unreadBlock().

unsigned KBufferedIO::feedWriteBuffer unsigned  nbytes,
const char *  buffer
[protected, virtual]
 

Feeds data into the output buffer.

This happens when the user told us to write some data. The data will be appended to the buffer.

Parameters:
nbytes the number of bytes in the buffer
buffer the data that is to be written
Returns:
the number of bytes that have been appended

Definition at line 259 of file kbufferedio.cpp.

References QPtrList< QByteArray >::append(), and outBuf.

Referenced by KExtendedSocket::writeBlock().

unsigned KBufferedIO::readBufferSize  )  const [protected, virtual]
 

Returns the number of bytes in the read buffer.

Returns:
the size of the read buffer in bytes

Definition at line 270 of file kbufferedio.cpp.

Referenced by bytesAvailable(), KExtendedSocket::close(), KExtendedSocket::closeNow(), consumeReadBuffer(), KExtendedSocket::release(), and KExtendedSocket::setBufferSize().

unsigned KBufferedIO::writeBufferSize  )  const [protected, virtual]
 

Returns the number of bytes in the write buffer.

Returns:
the size of the write buffer in bytes

Definition at line 283 of file kbufferedio.cpp.

Referenced by bytesToWrite(), KExtendedSocket::close(), KExtendedSocket::closeNow(), KExtendedSocket::flush(), KExtendedSocket::release(), KExtendedSocket::setBufferSize(), and KExtendedSocket::writeBlock().


Member Data Documentation

QPtrList<QByteArray> KBufferedIO::inBuf [protected]
 

For an explanation on how this buffer work, please refer to the comments at the top of kbufferedio.cpp.

Definition at line 215 of file kbufferedio.h.

Referenced by consumeReadBuffer(), and feedReadBuffer().

QPtrList<QByteArray> KBufferedIO::outBuf [protected]
 

For an explanation on how this buffer work, please refer to the comments at the top of kbufferedio.cpp.

Definition at line 221 of file kbufferedio.h.

Referenced by consumeWriteBuffer(), feedWriteBuffer(), and KExtendedSocket::flush().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 12:47:17 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001