2
* bytestream.cpp - base class for bytestreams
3
* Copyright (C) 2003 Justin Karneges
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
21
#include "bytestream.h"
26
//! \class ByteStream bytestream.h
27
//! \brief Base class for "bytestreams"
29
//! This class provides a basic framework for a "bytestream", here defined
30
//! as a bi-directional, asynchronous pipe of data. It can be used to create
31
//! several different kinds of bytestream-applications, such as a console or
32
//! TCP connection, or something more abstract like a security layer or tunnel,
33
//! all with the same interface. The provided functions make creating such
34
//! classes simpler. ByteStream is a pure-virtual class, so you do not use it
35
//! on its own, but instead through a subclass such as \a BSocket.
37
//! The signals connectionClosed(), delayedCloseFinished(), readyRead(),
38
//! bytesWritten(), and error() serve the exact same function as those from
39
//! <A HREF="http://doc.trolltech.com/3.1/qsocket.html">QSocket</A>.
41
//! The simplest way to create a ByteStream is to reimplement isOpen(), close(),
42
//! and tryWrite(). Call appendRead() whenever you want to make data available for
43
//! reading. ByteStream will take care of the buffers with regards to the caller,
44
//! and will call tryWrite() when the write buffer gains data. It will be your
45
//! job to call tryWrite() whenever it is acceptable to write more data to
46
//! the underlying system.
48
//! If you need more advanced control, reimplement read(), write(), bytesAvailable(),
49
//! and/or bytesToWrite() as necessary.
51
//! Use appendRead(), appendWrite(), takeRead(), and takeWrite() to modify the
52
//! buffers. If you have more advanced requirements, the buffers can be accessed
53
//! directly with readBuf() and writeBuf().
55
//! Also available are the static convenience functions ByteStream::appendArray()
56
//! and ByteStream::takeArray(), which make dealing with byte queues very easy.
58
class ByteStream::Private
63
QByteArray readBuf, writeBuf;
67
//! Constructs a ByteStream object with parent \a parent.
68
ByteStream::ByteStream(QObject *parent)
75
//! Destroys the object and frees allocated resources.
76
ByteStream::~ByteStream()
82
//! Returns TRUE if the stream is open, meaning that you can write to it.
83
bool ByteStream::isOpen() const
89
//! Closes the stream. If there is data in the write buffer then it will be
90
//! written before actually closing the stream. Once all data has been written,
91
//! the delayedCloseFinished() signal will be emitted.
92
//! \sa delayedCloseFinished()
93
void ByteStream::close()
98
//! Writes array \a a to the stream.
99
void ByteStream::write(const QByteArray &a)
104
bool doWrite = bytesToWrite() == 0 ? true: false;
111
//! Reads bytes \a bytes of data from the stream and returns them as an array. If \a bytes is 0, then
112
//! \a read will return all available data.
113
QByteArray ByteStream::read(int bytes)
115
return takeRead(bytes);
119
//! Returns the number of bytes available for reading.
120
int ByteStream::bytesAvailable() const
122
return d->readBuf.size();
126
//! Returns the number of bytes that are waiting to be written.
127
int ByteStream::bytesToWrite() const
129
return d->writeBuf.size();
133
//! Clears the read buffer.
134
void ByteStream::clearReadBuffer()
136
d->readBuf.resize(0);
140
//! Clears the write buffer.
141
void ByteStream::clearWriteBuffer()
143
d->writeBuf.resize(0);
147
//! Appends \a block to the end of the read buffer.
148
void ByteStream::appendRead(const QByteArray &block)
150
appendArray(&d->readBuf, block);
154
//! Appends \a block to the end of the write buffer.
155
void ByteStream::appendWrite(const QByteArray &block)
157
appendArray(&d->writeBuf, block);
161
//! Returns \a size bytes from the start of the read buffer.
162
//! If \a size is 0, then all available data will be returned.
163
//! If \a del is TRUE, then the bytes are also removed.
164
QByteArray ByteStream::takeRead(int size, bool del)
166
return takeArray(&d->readBuf, size, del);
170
//! Returns \a size bytes from the start of the write buffer.
171
//! If \a size is 0, then all available data will be returned.
172
//! If \a del is TRUE, then the bytes are also removed.
173
QByteArray ByteStream::takeWrite(int size, bool del)
175
return takeArray(&d->writeBuf, size, del);
179
//! Returns a reference to the read buffer.
180
QByteArray & ByteStream::readBuf()
186
//! Returns a reference to the write buffer.
187
QByteArray & ByteStream::writeBuf()
193
//! Attempts to try and write some bytes from the write buffer, and returns the number
194
//! successfully written or -1 on error. The default implementation returns -1.
195
int ByteStream::tryWrite()
201
//! Append array \a b to the end of the array pointed to by \a a.
202
void ByteStream::appendArray(QByteArray *a, const QByteArray &b)
204
int oldsize = a->size();
205
a->resize(oldsize + b.size());
206
memcpy(a->data() + oldsize, b.data(), b.size());
210
//! Returns \a size bytes from the start of the array pointed to by \a from.
211
//! If \a size is 0, then all available data will be returned.
212
//! If \a del is TRUE, then the bytes are also removed.
213
QByteArray ByteStream::takeArray(QByteArray *from, int size, bool del)
222
if(size > (int)from->size())
225
char *r = from->data();
226
memcpy(a.data(), r, size);
228
int newsize = from->size()-size;
229
memmove(r, r+size, newsize);
230
from->resize(newsize);
235
void connectionClosed();
236
void delayedCloseFinished();
238
void bytesWritten(int);
241
//! \fn void ByteStream::connectionClosed()
242
//! This signal is emitted when the remote end of the stream closes.
244
//! \fn void ByteStream::delayedCloseFinished()
245
//! This signal is emitted when all pending data has been written to the stream
246
//! after an attempt to close.
248
//! \fn void ByteStream::readyRead()
249
//! This signal is emitted when data is available to be read.
251
//! \fn void ByteStream::bytesWritten(int x);
252
//! This signal is emitted when data has been successfully written to the stream.
253
//! \a x is the number of bytes written.
255
//! \fn void ByteStream::error(int code)
256
//! This signal is emitted when an error occurs in the stream. The reason for
257
//! error is indicated by \a code.