2 * bytestream.cpp - base class for bytestreams
3 * Copyright (C) 2003 Justin Karneges <justin@affinix.com>
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
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 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
22 #include"bytestream.h"
27 //! \class ByteStream bytestream.h
28 //! \brief Base class for "bytestreams"
30 //! This class provides a basic framework for a "bytestream", here defined
31 //! as a bi-directional, asynchronous pipe of data. It can be used to create
32 //! several different kinds of bytestream-applications, such as a console or
33 //! TCP connection, or something more abstract like a security layer or tunnel,
34 //! all with the same interface. The provided functions make creating such
35 //! classes simpler. ByteStream is a pure-virtual class, so you do not use it
36 //! on its own, but instead through a subclass such as \a BSocket.
38 //! The signals connectionClosed(), delayedCloseFinished(), readyRead(),
39 //! bytesWritten(), and error() serve the exact same function as those from
40 //! <A HREF="http://doc.trolltech.com/3.1/qsocket.html">QSocket</A>.
42 //! The simplest way to create a ByteStream is to reimplement isOpen(), close(),
43 //! and tryWrite(). Call appendRead() whenever you want to make data available for
44 //! reading. ByteStream will take care of the buffers with regards to the caller,
45 //! and will call tryWrite() when the write buffer gains data. It will be your
46 //! job to call tryWrite() whenever it is acceptable to write more data to
47 //! the underlying system.
49 //! If you need more advanced control, reimplement read(), write(), bytesAvailable(),
50 //! and/or bytesToWrite() as necessary.
52 //! Use appendRead(), appendWrite(), takeRead(), and takeWrite() to modify the
53 //! buffers. If you have more advanced requirements, the buffers can be accessed
54 //! directly with readBuf() and writeBuf().
56 //! Also available are the static convenience functions ByteStream::appendArray()
57 //! and ByteStream::takeArray(), which make dealing with byte queues very easy.
59 class ByteStream::Private
64 QByteArray readBuf
, writeBuf
;
68 //! Constructs a ByteStream object with parent \a parent.
69 ByteStream::ByteStream(QObject
*parent
)
70 :QObject(parent
), d(new Private())
76 //! Destroys the object and frees allocated resources.
77 ByteStream::~ByteStream()
83 //! Returns TRUE if the stream is open, meaning that you can write to it.
84 bool ByteStream::isOpen() const
90 //! Closes the stream. If there is data in the write buffer then it will be
91 //! written before actually closing the stream. Once all data has been written,
92 //! the delayedCloseFinished() signal will be emitted.
93 //! \sa delayedCloseFinished()
94 void ByteStream::close()
99 //! Writes array \a a to the stream.
100 void ByteStream::write(const QByteArray
&a
)
102 // kDebug() << "[data size: " << a.size() << "]";
104 // kDebug() << "[Data: " << a << "]";
109 bool doWrite
= bytesToWrite() == 0 ? true: false;
116 //! Reads bytes \a bytes of data from the stream and returns them as an array. If \a bytes is 0, then
117 //! \a read will return all available data.
118 QByteArray
ByteStream::read(int bytes
)
120 // kDebug() << " " << bytes <<" [bytes]";
121 return takeRead(bytes
);
125 //! Returns the number of bytes available for reading.
126 int ByteStream::bytesAvailable() const
128 return d
->readBuf
.size();
132 //! Returns the number of bytes that are waiting to be written.
133 int ByteStream::bytesToWrite() const
135 // kDebug() << "[bytes left: " << d->writeBuf.size() << " ]";
136 return d
->writeBuf
.size();
140 //! Clears the read buffer.
141 void ByteStream::clearReadBuffer()
143 d
->readBuf
.resize(0);
147 //! Clears the write buffer.
148 void ByteStream::clearWriteBuffer()
150 d
->writeBuf
.resize(0);
154 //! Appends \a block to the end of the read buffer.
155 void ByteStream::appendRead(const QByteArray
&block
)
158 appendArray(&d
->readBuf
, block
);
162 //! Appends \a block to the end of the write buffer.
163 void ByteStream::appendWrite(const QByteArray
&block
)
165 // kDebug() << "[data size: " << block.size() << "]";
167 appendArray(&d
->writeBuf
, block
);
171 //! Returns \a size bytes from the start of the read buffer.
172 //! If \a size is 0, then all available data will be returned.
173 //! If \a del is TRUE, then the bytes are also removed.
174 QByteArray
ByteStream::takeRead(int size
, bool del
)
176 // kDebug() << "[data size: " << size << "][ delete :" << del << " ]";
177 return takeArray(&d
->readBuf
, size
, del
);
181 //! Returns \a size bytes from the start of the write buffer.
182 //! If \a size is 0, then all available data will be returned.
183 //! If \a del is TRUE, then the bytes are also removed.
184 QByteArray
ByteStream::takeWrite(int size
, bool del
)
186 // kDebug() << "[data size: " << size << "][ delete :" << del << " ]";
187 return takeArray(&d
->writeBuf
, size
, del
);
191 //! Returns a reference to the read buffer.
192 QByteArray
& ByteStream::readBuf()
198 //! Returns a reference to the write buffer.
199 QByteArray
& ByteStream::writeBuf()
206 //! Attempts to try and write some bytes from the write buffer, and returns the number
207 //! successfully written or -1 on error. The default implementation returns -1.
208 int ByteStream::tryWrite()
210 // kDebug() << "(THIS RETURNS -1)";
215 //! Append array \a b to the end of the array pointed to by \a a.
216 void ByteStream::appendArray(QByteArray
*a
, const QByteArray
&b
)
219 int oldsize
= a
->size();
220 a
->resize(oldsize
+ b
.size());
221 memcpy(a
->data() + oldsize
, b
.data(), b
.size());
225 //! Returns \a size bytes from the start of the array pointed to by \a from.
226 //! If \a size is 0, then all available data will be returned.
227 //! If \a del is TRUE, then the bytes are also removed.
228 QByteArray
ByteStream::takeArray(QByteArray
*from
, int size
, bool del
)
230 // kDebug() << "[int size] : " << size << " [bool del] " << del;
239 if(size
> (int)from
->size())
242 char *r
= from
->data();
243 memcpy(a
.data(), r
, size
);
245 int newsize
= from
->size()-size
;
246 memmove(r
, r
+size
, newsize
);
247 from
->resize(newsize
);
252 void connectionClosed();
253 void delayedCloseFinished();
255 void bytesWritten(int);
258 //! \fn void ByteStream::connectionClosed()
259 //! This signal is emitted when the remote end of the stream closes.
261 //! \fn void ByteStream::delayedCloseFinished()
262 //! This signal is emitted when all pending data has been written to the stream
263 //! after an attempt to close.
265 //! \fn void ByteStream::readyRead()
266 //! This signal is emitted when data is available to be read.
268 //! \fn void ByteStream::bytesWritten(int x);
269 //! This signal is emitted when data has been successfully written to the stream.
270 //! \a x is the number of bytes written.
272 //! \fn void ByteStream::error(int code)
273 //! This signal is emitted when an error occurs in the stream. The reason for
274 //! error is indicated by \a code.
278 #include "bytestream.moc"