home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kbufferedio.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-11-08  |  10.4 KB  |  290 lines
  1. /*
  2.  *  This file is part of the KDE libraries
  3.  *  Copyright (C) 2001 Thiago Macieira <thiago.macieira@kdemail.net>
  4.  *
  5.  *  This library is free software; you can redistribute it and/or
  6.  *  modify it under the terms of the GNU Library General Public
  7.  *  License as published by the Free Software Foundation; either
  8.  *  version 2 of the License, or (at your option) any later version.
  9.  *
  10.  *  This library 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 GNU
  13.  *  Library General Public License for more details.
  14.  *
  15.  *  You should have received a copy of the GNU Library General Public License
  16.  *  along with this library; see the file COPYING.LIB.  If not, write to
  17.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  *  Boston, MA 02110-1301, USA.
  19.  */
  20.  
  21. #ifndef KBUFFEREDIO_H
  22. #define KBUFFEREDIO_H
  23.  
  24. #include <qcstring.h>
  25. #include <qptrlist.h>
  26. #include "kasyncio.h"
  27.  
  28. class KBufferedIOPrivate;
  29. /**
  30.  * This abstract class implements basic functionality for buffered
  31.  * input/output.
  32.  *
  33.  * Through the available methods, you can find out how many bytes are
  34.  * available for reading, how many are still unsent and you can peek at
  35.  * the buffered data.
  36.  *
  37.  * This class was intentionally written to resemble QSocket, because
  38.  * KExtendedSocket is a subclass of this one. This is so that applications
  39.  * written using QSocket's buffering characteristics will be more easily
  40.  * ported to the more powerful KExtendedSocket class.
  41.  *
  42.  * KBufferedIO already provides a powerful internal buffering algorithm. However,
  43.  * this does not include the I/O itself, which must be implemented in
  44.  * derived classes. Thus, to implement a class that does some I/O, you must
  45.  * override, in addition to the pure virtual QIODevice methods, these two:
  46.  * @li closeNow()
  47.  * @li waitForMore()
  48.  *
  49.  * If your derived class reimplements the buffering algorithm, you must then
  50.  * decide which buffering functions to override. For instance, you may want to
  51.  * change the protected functions like feedReadBuffer() and consumeReadBuffer().
  52.  *
  53.  * @author Thiago Macieira <thiagom@mail.com>
  54.  * @short Buffered I/O
  55.  */
  56. class KDECORE_EXPORT KBufferedIO: public KAsyncIO
  57. {
  58.   Q_OBJECT
  59.  
  60. protected:
  61.   // no default public constructor
  62.   KBufferedIO();
  63.  
  64. public:
  65.   /**
  66.    * The modes for closed() signal
  67.    */
  68.   enum closeModes
  69.   {
  70.     availRead = 0x01,
  71.     dirtyWrite = 0x02,
  72.     involuntary = 0x10,
  73.     delayed = 0x20,
  74.     closedNow = 0x40
  75.   };
  76.  
  77.   /**
  78.    * Destroys this class. The flushing of the buffers is implementation dependant.
  79.    * The default implementation discards the contents
  80.    */
  81.   virtual ~KBufferedIO();
  82.  
  83.   /**
  84.    * Closes the stream now, discarding the contents of the
  85.    * write buffer. That is, we won't try to flush that
  86.    * buffer before closing. If you want that buffer to be
  87.    * flushed, you can call QIODevice::flush(), which is blocking, and
  88.    * then closeNow, or you can call QIODevice::close() for a delayed
  89.    * close.
  90.    */
  91.   virtual void closeNow() = 0;
  92.  
  93.   /**
  94.    * Sets the internal buffer size to value.
  95.    *
  96.    * Not all implementations support this.
  97.    *
  98.    * The parameters may be 0 to make the class unbuffered or -1
  99.    * to let the class choose the size (which may be unlimited) or
  100.    * -2 to leave the buffer size untouched.
  101.    *
  102.    * Note that setting the write buffer size to any value smaller than
  103.    * the current size of the buffer will force it to flush first,
  104.    * which can make this call blocking.
  105.    *
  106.    * The default implementation does not support setting the buffer
  107.    * sizes. You can only call this function with values -1 for "don't care"
  108.    * or -2 for "unchanged"
  109.    * @param rsize    the size of the read buffer
  110.    * @param wsize    the size of the write buffer
  111.    * @return true if setting both was ok. If false is returned, the
  112.    * buffers were left unchanged.
  113.    */
  114.   virtual bool setBufferSize(int rsize, int wsize = -2);
  115.  
  116.   /**
  117.    * Returns the number of bytes available for reading in the read buffer
  118.    * @return the number of bytes available for reading
  119.    */
  120.   virtual int bytesAvailable() const;
  121.  
  122.   /**
  123.    * Waits for more data to be available and returns the amount of available data then.
  124.    * 
  125.    * @param msec    number of milliseconds to wait, -1 to wait forever
  126.    * @return -1 if we cannot wait (e.g., that doesn't make sense in this stream)
  127.    */
  128.   virtual int waitForMore(int msec) = 0;
  129.  
  130.   /**
  131.    * Returns the number of bytes yet to write, still in the write buffer
  132.    * @return the number of unwritten bytes in the write buffer
  133.    */
  134.   virtual int bytesToWrite() const;
  135.  
  136.   /**
  137.    * Checks whether there is enough data in the buffer to read a line
  138.    *
  139.    * The default implementation reads directly from inBuf, so if your
  140.    * implementation changes the meaning of that member, then you must override
  141.    * this function.
  142.    * @return true when there is enough data in the buffer to read a line
  143.    */
  144.   virtual bool canReadLine() const;
  145.  
  146.   // readBlock, peekBlock and writeBlock are not defined in this class (thus, left
  147.   // pure virtual) because this does not mean only reading and writing
  148.   // to the buffers. It may be necessary to do I/O to complete the
  149.   // transaction (e.g., user wants to read more than is in the buffer).
  150.   // Reading and writing to the buffer are available for access through
  151.   // protected member functions
  152.  
  153.   /**
  154.    * Reads into the user buffer at most maxlen bytes, but does not
  155.    * consume that data from the read buffer. This is useful to check
  156.    * whether we already have the needed data to process something.
  157.    *
  158.    * This function may want to try and read more data from the system
  159.    * provided it won't block.
  160.    *
  161.    * @param data    the user buffer pointer, at least maxlen bytes long
  162.    * @param maxlen    the maximum length to be peeked
  163.    * @return the number of bytes actually copied.
  164.    */
  165.   virtual int peekBlock(char *data, uint maxlen) = 0;
  166.  
  167.   /**
  168.    * Unreads some data. That is, write the data to the beginning of the
  169.    * read buffer, so that next calls to readBlock or peekBlock will see
  170.    * this data instead.
  171.    *
  172.    * Note not all devices implement this since this could mean a semantic
  173.    * problem. For instance, sockets are sequential devices, so they won't
  174.    * accept unreading.
  175.    * @param data    the data to be unread
  176.    * @param len    the size of the data
  177.    * @return the number of bytes actually unread
  178.    */
  179.   virtual int unreadBlock(const char *data, uint len);
  180.  
  181. signals:
  182.   /**
  183.    * This signal gets sent whenever bytes are written from the buffer.
  184.    * @param nbytes the number of bytes sent.
  185.    */
  186.   void bytesWritten(int nbytes);
  187.  
  188.   // There is no read signal here. We use the readyRead signal inherited
  189.   // from KAsyncIO for that purpose
  190.  
  191.   /**
  192.    * This signal gets sent when the stream is closed. The @p state parameter
  193.    * will give the current state, in OR-ed bits:
  194.    * @li availRead:    read buffer contains data to be read
  195.    * @li dirtyWrite:    write buffer wasn't empty when the stream closed
  196.    * @li involuntary:    the stream wasn't closed due to user request
  197.    *            (i.e., call to close). Probably remote end closed it
  198.    * @li delayed:    the stream was closed voluntarily by the user, but it
  199.    *            happened only after the write buffer was emptied
  200.    * @li closedNow:    the stream was closed voluntarily by the user, by
  201.    *            explicitly calling closeNow, which means the
  202.    *            write buffer's contents may have been discarded
  203.    * @param state the state (see function description)
  204.    */
  205.   void closed(int state);
  206.  
  207. protected:
  208.   /**
  209.    * For an explanation on how this buffer work, please refer to the comments
  210.    * at the top of kbufferedio.cpp, @ref impldetails .
  211.    */
  212.   QPtrList<QByteArray> inBuf;
  213.  
  214.   /**
  215.    * For an explanation on how this buffer work, please refer to the comments
  216.    * at the top of kbufferedio.cpp, @ref impldetails .
  217.    */
  218.   QPtrList<QByteArray> outBuf;
  219.  
  220.   unsigned inBufIndex /** Offset into first input buffer. */, 
  221.     outBufIndex /** Offset into first output buffer. */ ;
  222.  
  223.   /**
  224.    * Consumes data from the input buffer.
  225.    * That is, this will copy the data stored in the input (read) buffer
  226.    * into the given @p destbuffer, as much as @p nbytes.
  227.    * @param nbytes    the maximum amount of bytes to copy into the buffer
  228.    * @param destbuffer    the destination buffer into which to copy the data
  229.    * @param discard    whether to discard the copied data after the operation
  230.    * @return the real amount of data copied. If it is less than
  231.    * nbytes, then all the buffer was copied.
  232.    */
  233.   virtual unsigned consumeReadBuffer(unsigned nbytes, char *destbuffer, bool discard = true);
  234.  
  235.   /**
  236.    * Consumes data from the output buffer.
  237.    * Since this is called whenever we managed to send data out the wire, we
  238.    * can only discard this amount from the buffer. There is no copying and no
  239.    * "peeking" for the output buffer.
  240.    *
  241.    * Note this function should be called AFTER the data was sent. After it
  242.    * is called, the data is no longer available in the buffer. And don't pass
  243.    * wrong nbytes values.
  244.    * @param nbytes    the amount of bytes to discard
  245.    */
  246.   virtual void consumeWriteBuffer(unsigned nbytes);
  247.  
  248.   /**
  249.    * Feeds data into the input buffer.
  250.    * This happens when we detected available data in the device and read it.
  251.  
  252.    * The data will be appended to the buffer or inserted at the beginning,
  253.    * depending on whether @p atBeginning is set or not.
  254.    * @param nbytes    the number of bytes in the buffer
  255.    * @param buffer    the data that was read
  256.    * @param atBeginning    whether to append or insert at the beginning
  257.    * @return the number of bytes that have been appended
  258.    */
  259.   virtual unsigned feedReadBuffer(unsigned nbytes, const char *buffer, bool atBeginning = false);
  260.  
  261.   /**
  262.    * Feeds data into the output buffer.
  263.    * This happens when the user told us to write some data.
  264.    * The data will be appended to the buffer.
  265.    * @param nbytes    the number of bytes in the buffer
  266.    * @param buffer    the data that is to be written
  267.    * @return the number of bytes that have been appended
  268.    */
  269.   virtual unsigned feedWriteBuffer(unsigned nbytes, const char *buffer);
  270.  
  271.   /**
  272.    * Returns the number of bytes in the read buffer
  273.    * @return the size of the read buffer in bytes
  274.    */
  275.   virtual unsigned readBufferSize() const;
  276.  
  277.   /**
  278.    * Returns the number of bytes in the write buffer
  279.    * @return the size of the write buffer in bytes
  280.    */
  281.   virtual unsigned writeBufferSize() const;
  282.  
  283. protected:
  284.   virtual void virtual_hook( int id, void* data );
  285. private:
  286.   KBufferedIOPrivate *d;
  287. };
  288.  
  289. #endif // KBUFFEREDIO_H
  290.