summaryrefslogtreecommitdiffstats
path: root/kdecore/kbufferedio.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commitce4a32fe52ef09d8f5ff1dd22c001110902b60a2 (patch)
tree5ac38a06f3dde268dc7927dc155896926aaf7012 /kdecore/kbufferedio.h
downloadtdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.tar.gz
tdelibs-ce4a32fe52ef09d8f5ff1dd22c001110902b60a2.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'kdecore/kbufferedio.h')
-rw-r--r--kdecore/kbufferedio.h289
1 files changed, 289 insertions, 0 deletions
diff --git a/kdecore/kbufferedio.h b/kdecore/kbufferedio.h
new file mode 100644
index 000000000..47579738d
--- /dev/null
+++ b/kdecore/kbufferedio.h
@@ -0,0 +1,289 @@
+/*
+ * This file is part of the KDE libraries
+ * Copyright (C) 2001 Thiago Macieira <thiago.macieira@kdemail.net>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public License
+ * along with this library; see the file COPYING.LIB. If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#ifndef KBUFFEREDIO_H
+#define KBUFFEREDIO_H
+
+#include <qcstring.h>
+#include <qptrlist.h>
+#include "kasyncio.h"
+
+class KBufferedIOPrivate;
+/**
+ * This abstract class implements basic functionality for buffered
+ * input/output.
+ *
+ * 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:
+ * @li closeNow()
+ * @li waitForMore()
+ *
+ * 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>
+ * @short Buffered I/O
+ */
+class KDECORE_EXPORT KBufferedIO: public KAsyncIO
+{
+ Q_OBJECT
+
+protected:
+ // no default public constructor
+ KBufferedIO();
+
+public:
+ /**
+ * The modes for closed() signal
+ */
+ enum closeModes
+ {
+ availRead = 0x01,
+ dirtyWrite = 0x02,
+ involuntary = 0x10,
+ delayed = 0x20,
+ closedNow = 0x40
+ };
+
+ /**
+ * Destroys this class. The flushing of the buffers is implementation dependant.
+ * The default implementation discards the contents
+ */
+ virtual ~KBufferedIO();
+
+ /**
+ * 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.
+ */
+ virtual void closeNow() = 0;
+
+ /**
+ * 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"
+ * @param rsize the size of the read buffer
+ * @param wsize the size of the write buffer
+ * @return true if setting both was ok. If false is returned, the
+ * buffers were left unchanged.
+ */
+ virtual bool setBufferSize(int rsize, int wsize = -2);
+
+ /**
+ * Returns the number of bytes available for reading in the read buffer
+ * @return the number of bytes available for reading
+ */
+ virtual int bytesAvailable() const;
+
+ /**
+ * Waits for more data to be available and returns the amount of available data then.
+ *
+ * @param msec number of milliseconds to wait, -1 to wait forever
+ * @return -1 if we cannot wait (e.g., that doesn't make sense in this stream)
+ */
+ virtual int waitForMore(int msec) = 0;
+
+ /**
+ * Returns the number of bytes yet to write, still in the write buffer
+ * @return the number of unwritten bytes in the write buffer
+ */
+ virtual int bytesToWrite() const;
+
+ /**
+ * 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.
+ * @return true when there is enough data in the buffer to read a line
+ */
+ virtual bool canReadLine() const;
+
+ // readBlock, peekBlock and writeBlock are not defined in this class (thus, left
+ // pure virtual) because this does not mean only reading and writing
+ // to the buffers. It may be necessary to do I/O to complete the
+ // transaction (e.g., user wants to read more than is in the buffer).
+ // Reading and writing to the buffer are available for access through
+ // protected member functions
+
+ /**
+ * 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.
+ *
+ * @param data the user buffer pointer, at least maxlen bytes long
+ * @param maxlen the maximum length to be peeked
+ * @return the number of bytes actually copied.
+ */
+ virtual int peekBlock(char *data, uint maxlen) = 0;
+
+ /**
+ * 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.
+ * @param data the data to be unread
+ * @param len the size of the data
+ * @return the number of bytes actually unread
+ */
+ virtual int unreadBlock(const char *data, uint len);
+
+signals:
+ /**
+ * This signal gets sent whenever bytes are written from the buffer.
+ * @param nbytes the number of bytes sent.
+ */
+ void bytesWritten(int nbytes);
+
+ // There is no read signal here. We use the readyRead signal inherited
+ // from KAsyncIO for that purpose
+
+ /**
+ * This signal gets sent when the stream is closed. The @p state parameter
+ * will give the current state, in OR-ed bits:
+ * @li availRead: read buffer contains data to be read
+ * @li dirtyWrite: write buffer wasn't empty when the stream closed
+ * @li involuntary: the stream wasn't closed due to user request
+ * (i.e., call to close). Probably remote end closed it
+ * @li delayed: the stream was closed voluntarily by the user, but it
+ * happened only after the write buffer was emptied
+ * @li closedNow: the stream was closed voluntarily by the user, by
+ * explicitly calling closeNow, which means the
+ * write buffer's contents may have been discarded
+ * @param state the state (see function description)
+ */
+ void closed(int state);
+
+protected:
+ /**
+ * For an explanation on how this buffer work, please refer to the comments
+ * at the top of kbufferedio.cpp, @ref impldetails .
+ */
+ QPtrList<QByteArray> inBuf;
+
+ /**
+ * For an explanation on how this buffer work, please refer to the comments
+ * at the top of kbufferedio.cpp, @ref impldetails .
+ */
+ QPtrList<QByteArray> outBuf;
+
+ unsigned inBufIndex /** Offset into first input buffer. */,
+ outBufIndex /** Offset into first output buffer. */ ;
+
+ /**
+ * Consumes data from the input buffer.
+ * That is, this will copy the data stored in the input (read) buffer
+ * into the given @p destbuffer, as much as @p nbytes.
+ * @param nbytes the maximum amount of bytes to copy into the buffer
+ * @param destbuffer the destination buffer into which to copy the data
+ * @param discard whether to discard the copied data after the operation
+ * @return the real amount of data copied. If it is less than
+ * nbytes, then all the buffer was copied.
+ */
+ virtual unsigned consumeReadBuffer(unsigned nbytes, char *destbuffer, bool discard = true);
+
+ /**
+ * 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.
+ * @param nbytes the amount of bytes to discard
+ */
+ virtual void consumeWriteBuffer(unsigned nbytes);
+
+ /**
+ * 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 @p atBeginning is set or not.
+ * @param nbytes the number of bytes in the buffer
+ * @param buffer the data that was read
+ * @param atBeginning whether to append or insert at the beginning
+ * @return the number of bytes that have been appended
+ */
+ virtual unsigned feedReadBuffer(unsigned nbytes, const char *buffer, bool atBeginning = false);
+
+ /**
+ * 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.
+ * @param nbytes the number of bytes in the buffer
+ * @param buffer the data that is to be written
+ * @return the number of bytes that have been appended
+ */
+ virtual unsigned feedWriteBuffer(unsigned nbytes, const char *buffer);
+
+ /**
+ * Returns the number of bytes in the read buffer
+ * @return the size of the read buffer in bytes
+ */
+ virtual unsigned readBufferSize() const;
+
+ /**
+ * Returns the number of bytes in the write buffer
+ * @return the size of the write buffer in bytes
+ */
+ virtual unsigned writeBufferSize() const;
+
+protected:
+ virtual void virtual_hook( int id, void* data );
+private:
+ KBufferedIOPrivate *d;
+};
+
+#endif // KBUFFEREDIO_H