1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtCore module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file. Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights. These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
42 //#define QIODEVICE_DEBUG
44 #include "qbytearray.h"
46 #include "qiodevice_p.h"
48 #include "qstringlist.h"
51 #ifdef QIODEVICE_DEBUG
57 #ifdef QIODEVICE_DEBUG
58 void debugBinaryString(const QByteArray
&input
)
62 for (int i
= 0; i
< input
.size(); ++i
) {
65 if ((i
% 16) == 15 || i
== (input
.size() - 1)) {
66 printf("\n%15d:", startOffset
);
67 startOffset
+= tmp
.size();
69 for (int j
= 0; j
< tmp
.size(); ++j
)
70 printf(" %02x", int(uchar(tmp
[j
])));
71 for (int j
= tmp
.size(); j
< 16 + 1; ++j
)
73 for (int j
= 0; j
< tmp
.size(); ++j
)
74 printf("%c", isprint(int(uchar(tmp
[j
]))) ? tmp
[j
] : '.');
81 void debugBinaryString(const char *data
, qint64 maxlen
)
83 debugBinaryString(QByteArray(data
, maxlen
));
87 #ifndef QIODEVICE_BUFFERSIZE
88 #define QIODEVICE_BUFFERSIZE Q_INT64_C(16384)
93 #define CHECK_MAXLEN(function, returnType) \
96 qWarning("QIODevice::"#function": Called with maxSize < 0"); \
101 #define CHECK_WRITABLE(function, returnType) \
103 if ((d->openMode & WriteOnly) == 0) { \
104 if (d->openMode == NotOpen) \
106 qWarning("QIODevice::"#function": ReadOnly device"); \
111 #define CHECK_READABLE(function, returnType) \
113 if ((d->openMode & ReadOnly) == 0) { \
114 if (d->openMode == NotOpen) \
116 qWarning("QIODevice::"#function": WriteOnly device"); \
123 QIODevicePrivate::QIODevicePrivate()
124 : openMode(QIODevice::NotOpen
), buffer(QIODEVICE_BUFFERSIZE
),
126 , baseReadLineDataCalled(false)
136 QIODevicePrivate::~QIODevicePrivate()
144 \brief The QIODevice class is the base interface class of all I/O
149 QIODevice provides both a common implementation and an abstract
150 interface for devices that support reading and writing of blocks
151 of data, such as QFile, QBuffer and QTcpSocket. QIODevice is
152 abstract and can not be instantiated, but it is common to use the
153 interface it defines to provide device-independent I/O features.
154 For example, Qt's XML classes operate on a QIODevice pointer,
155 allowing them to be used with various devices (such as files and
158 Before accessing the device, open() must be called to set the
159 correct OpenMode (such as ReadOnly or ReadWrite). You can then
160 write to the device with write() or putChar(), and read by calling
161 either read(), readLine(), or readAll(). Call close() when you are
162 done with the device.
164 QIODevice distinguishes between two types of devices:
165 random-access devices and sequential devices.
168 \o Random-access devices support seeking to arbitrary
169 positions using seek(). The current position in the file is
170 available by calling pos(). QFile and QBuffer are examples of
171 random-access devices.
173 \o Sequential devices don't support seeking to arbitrary
174 positions. The data must be read in one pass. The functions
175 pos() and size() don't work for sequential devices.
176 QTcpSocket and QProcess are examples of sequential devices.
179 You can use isSequential() to determine the type of device.
181 QIODevice emits readyRead() when new data is available for
182 reading; for example, if new data has arrived on the network or if
183 additional data is appended to a file that you are reading
184 from. You can call bytesAvailable() to determine the number of
185 bytes that are currently available for reading. It's common to use
186 bytesAvailable() together with the readyRead() signal when
187 programming with asynchronous devices such as QTcpSocket, where
188 fragments of data can arrive at arbitrary points in
189 time. QIODevice emits the bytesWritten() signal every time a
190 payload of data has been written to the device. Use bytesToWrite()
191 to determine the current amount of data waiting to be written.
193 Certain subclasses of QIODevice, such as QTcpSocket and QProcess,
194 are asynchronous. This means that I/O functions such as write()
195 or read() always return immediately, while communication with the
196 device itself may happen when control goes back to the event loop.
197 QIODevice provides functions that allow you to force these
198 operations to be performed immediately, while blocking the
199 calling thread and without entering the event loop. This allows
200 QIODevice subclasses to be used without an event loop, or in
204 \o waitForReadyRead() - This function suspends operation in the
205 calling thread until new data is available for reading.
207 \o waitForBytesWritten() - This function suspends operation in the
208 calling thread until one payload of data has been written to the
211 \o waitFor....() - Subclasses of QIODevice implement blocking
212 functions for device-specific operations. For example, QProcess
213 has a function called waitForStarted() which suspends operation in
214 the calling thread until the process has started.
217 Calling these functions from the main, GUI thread, may cause your
218 user interface to freeze. Example:
220 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 0
222 By subclassing QIODevice, you can provide the same interface to
223 your own I/O devices. Subclasses of QIODevice are only required to
224 implement the protected readData() and writeData() functions.
225 QIODevice uses these functions to implement all its convenience
226 functions, such as getChar(), readLine() and write(). QIODevice
227 also handles access control for you, so you can safely assume that
228 the device is opened in write mode if writeData() is called.
230 Some subclasses, such as QFile and QTcpSocket, are implemented
231 using a memory buffer for intermediate storing of data. This
232 reduces the number of required device accessing calls, which are
233 often very slow. Buffering makes functions like getChar() and
234 putChar() fast, as they can operate on the memory buffer instead
235 of directly on the device itself. Certain I/O operations, however,
236 don't work well with a buffer. For example, if several users open
237 the same device and read it character by character, they may end
238 up reading the same data when they meant to read a separate chunk
239 each. For this reason, QIODevice allows you to bypass any
240 buffering by passing the Unbuffered flag to open(). When
241 subclassing QIODevice, remember to bypass any buffer you may use
242 when the device is open in Unbuffered mode.
244 \sa QBuffer QFile QTcpSocket
248 \typedef QIODevice::Offset
251 Use \c qint64 instead.
255 \typedef QIODevice::Status
258 Use QIODevice::OpenMode instead, or see the documentation for
263 \enum QIODevice::OpenModeFlag
265 This enum is used with open() to describe the mode in which a device
266 is opened. It is also returned by openMode().
268 \value NotOpen The device is not open.
269 \value ReadOnly The device is open for reading.
270 \value WriteOnly The device is open for writing.
271 \value ReadWrite The device is open for reading and writing.
272 \value Append The device is opened in append mode, so that all data is
273 written to the end of the file.
274 \value Truncate If possible, the device is truncated before it is opened.
275 All earlier contents of the device are lost.
276 \value Text When reading, the end-of-line terminators are
277 translated to '\n'. When writing, the end-of-line
278 terminators are translated to the local encoding, for
279 example '\r\n' for Win32.
280 \value Unbuffered Any buffer in the device is bypassed.
282 Certain flags, such as \c Unbuffered and \c Truncate, are
283 meaningless when used with some subclasses. Some of these
284 restrictions are implied by the type of device that is represented
285 by a subclass; for example, access to a QBuffer is always
286 unbuffered. In other cases, the restriction may be due to the
287 implementation, or may be imposed by the underlying platform; for
288 example, QTcpSocket does not support \c Unbuffered mode, and
289 limitations in the native API prevent QFile from supporting \c
290 Unbuffered on Windows.
293 /*! \fn QIODevice::bytesWritten(qint64 bytes)
295 This signal is emitted every time a payload of data has been
296 written to the device. The \a bytes argument is set to the number
297 of bytes that were written in this payload.
299 bytesWritten() is not emitted recursively; if you reenter the event loop
300 or call waitForBytesWritten() inside a slot connected to the
301 bytesWritten() signal, the signal will not be reemitted (although
302 waitForBytesWritten() may still return true).
308 \fn QIODevice::readyRead()
310 This signal is emitted once every time new data is available for
311 reading from the device. It will only be emitted again once new
312 data is available, such as when a new payload of network data has
313 arrived on your network socket, or when a new block of data has
314 been appended to your device.
316 readyRead() is not emitted recursively; if you reenter the event loop or
317 call waitForReadyRead() inside a slot connected to the readyRead() signal,
318 the signal will not be reemitted (although waitForReadyRead() may still
321 Note for developers implementing classes derived from QIODevice:
322 you should always emit readyRead() when new data has arrived (do not
323 emit it only because there's data still to be read in your
324 buffers). Do not emit readyRead() in other conditions.
329 /*! \fn QIODevice::aboutToClose()
331 This signal is emitted when the device is about to close. Connect
332 this signal if you have operations that need to be performed
333 before the device closes (e.g., if you have data in a separate
334 buffer that needs to be written to the device).
338 \fn QIODevice::readChannelFinished()
341 This signal is emitted when the input (reading) stream is closed
342 in this device. It is emitted as soon as the closing is detected,
343 which means that there might still be data available for reading
350 QIODevice::QIODevice()
351 : d_ptr(new QIODevicePrivate
)
358 QIODevice::QIODevice(QIODevicePrivate
&dd
)
366 Constructs a QIODevice object.
369 QIODevice::QIODevice()
370 : QObject(*new QIODevicePrivate
, 0)
372 #if defined QIODEVICE_DEBUG
373 QFile
*file
= qobject_cast
<QFile
*>(this);
374 printf("%p QIODevice::QIODevice(\"%s\") %s\n", this, metaObject()->className(),
375 qPrintable(file
? file
->fileName() : QString()));
380 Constructs a QIODevice object with the given \a parent.
383 QIODevice::QIODevice(QObject
*parent
)
384 : QObject(*new QIODevicePrivate
, parent
)
386 #if defined QIODEVICE_DEBUG
387 printf("%p QIODevice::QIODevice(%p \"%s\")\n", this, parent
, metaObject()->className());
393 QIODevice::QIODevice(QIODevicePrivate
&dd
, QObject
*parent
)
394 : QObject(dd
, parent
)
401 Destructs the QIODevice object.
403 QIODevice::~QIODevice()
405 #if defined QIODEVICE_DEBUG
406 printf("%p QIODevice::~QIODevice()\n", this);
411 Returns true if this device is sequential; otherwise returns
414 Sequential devices, as opposed to a random-access devices, have no
415 concept of a start, an end, a size, or a current position, and they
416 do not support seeking. You can only read from the device when it
417 reports that data is available. The most common example of a
418 sequential device is a network socket. On Unix, special files such
419 as /dev/zero and fifo pipes are sequential.
421 Regular files, on the other hand, do support random access. They
422 have both a size and a current position, and they also support
423 seeking backwards and forwards in the data stream. Regular files
428 bool QIODevice::isSequential() const
434 Returns the mode in which the device has been opened;
435 i.e. ReadOnly or WriteOnly.
439 QIODevice::OpenMode
QIODevice::openMode() const
441 return d_func()->openMode
;
445 Sets the OpenMode of the device to \a openMode. Call this
446 function to set the open mode if the flags change after the device
449 \sa openMode() OpenMode
451 void QIODevice::setOpenMode(OpenMode openMode
)
453 #if defined QIODEVICE_DEBUG
454 printf("%p QIODevice::setOpenMode(0x%x)\n", this, int(openMode
));
456 d_func()->openMode
= openMode
;
457 d_func()->accessMode
= QIODevicePrivate::Unset
;
461 If \a enabled is true, this function sets the \l Text flag on the device;
462 otherwise the \l Text flag is removed. This feature is useful for classes
463 that provide custom end-of-line handling on a QIODevice.
465 \sa open(), setOpenMode()
467 void QIODevice::setTextModeEnabled(bool enabled
)
473 d
->openMode
&= ~Text
;
477 Returns true if the \l Text flag is enabled; otherwise returns false.
479 \sa setTextModeEnabled()
481 bool QIODevice::isTextModeEnabled() const
483 return d_func()->openMode
& Text
;
487 Returns true if the device is open; otherwise returns false. A
488 device is open if it can be read from and/or written to. By
489 default, this function returns false if openMode() returns
492 \sa openMode() OpenMode
494 bool QIODevice::isOpen() const
496 return d_func()->openMode
!= NotOpen
;
500 Returns true if data can be read from the device; otherwise returns
501 false. Use bytesAvailable() to determine how many bytes can be read.
503 This is a convenience function which checks if the OpenMode of the
504 device contains the ReadOnly flag.
506 \sa openMode() OpenMode
508 bool QIODevice::isReadable() const
510 return (openMode() & ReadOnly
) != 0;
514 Returns true if data can be written to the device; otherwise returns
517 This is a convenience function which checks if the OpenMode of the
518 device contains the WriteOnly flag.
520 \sa openMode() OpenMode
522 bool QIODevice::isWritable() const
524 return (openMode() & WriteOnly
) != 0;
528 Opens the device and sets its OpenMode to \a mode. Returns true if successful;
529 otherwise returns false. This function should be called from any
530 reimplementations of open() or other functions that open the device.
532 \sa openMode() OpenMode
534 bool QIODevice::open(OpenMode mode
)
538 d
->pos
= (mode
& Append
) ? size() : qint64(0);
540 d
->accessMode
= QIODevicePrivate::Unset
;
541 #if defined QIODEVICE_DEBUG
542 printf("%p QIODevice::open(0x%x)\n", this, quint32(mode
));
548 First emits aboutToClose(), then closes the device and sets its
549 OpenMode to NotOpen. The error string is also reset.
551 \sa setOpenMode() OpenMode
553 void QIODevice::close()
556 if (d
->openMode
== NotOpen
)
559 #if defined QIODEVICE_DEBUG
560 printf("%p QIODevice::close()\n", this);
563 #ifndef QT_NO_QOBJECT
566 d
->openMode
= NotOpen
;
567 d
->errorString
.clear();
573 For random-access devices, this function returns the position that
574 data is written to or read from. For sequential devices or closed
575 devices, where there is no concept of a "current position", 0 is
578 The current read/write position of the device is maintained internally by
579 QIODevice, so reimplementing this function is not necessary. When
580 subclassing QIODevice, use QIODevice::seek() to notify QIODevice about
581 changes in the device position.
583 \sa isSequential(), seek()
585 qint64
QIODevice::pos() const
587 Q_D(const QIODevice
);
588 #if defined QIODEVICE_DEBUG
589 printf("%p QIODevice::pos() == %d\n", this, int(d
->pos
));
595 For open random-access devices, this function returns the size of the
596 device. For open sequential devices, bytesAvailable() is returned.
598 If the device is closed, the size returned will not reflect the actual
601 \sa isSequential(), pos()
603 qint64
QIODevice::size() const
605 return d_func()->isSequential() ? bytesAvailable() : qint64(0);
609 For random-access devices, this function sets the current position
610 to \a pos, returning true on success, or false if an error occurred.
611 For sequential devices, the default behavior is to do nothing and
614 When subclassing QIODevice, you must call QIODevice::seek() at the
615 start of your function to ensure integrity with QIODevice's
616 built-in buffer. The base implementation always returns true.
618 \sa pos(), isSequential()
620 bool QIODevice::seek(qint64 pos
)
622 if (d_func()->openMode
== NotOpen
) {
623 qWarning("QIODevice::seek: The device is not open");
627 qWarning("QIODevice::seek: Invalid pos: %d", int(pos
));
632 #if defined QIODEVICE_DEBUG
633 printf("%p QIODevice::seek(%d), before: d->pos = %d, d->buffer.size() = %d\n",
634 this, int(pos
), int(d
->pos
), d
->buffer
.size());
637 qint64 offset
= pos
- d
->pos
;
638 if (!d
->isSequential()) {
643 if (offset
> 0 && !d
->buffer
.isEmpty()) {
644 // When seeking forwards, we need to pop bytes off the front of the
647 int bytesToSkip
= int(qMin
<qint64
>(offset
, INT_MAX
));
648 d
->buffer
.skip(bytesToSkip
);
649 offset
-= bytesToSkip
;
650 } while (offset
> 0);
651 } else if (offset
< 0) {
652 // When seeking backwards, an operation that is only allowed for
653 // random-access devices, the buffer is cleared. The next read
654 // operation will then refill the buffer. We can optimize this, if we
655 // find that seeking backwards becomes a significant performance hit.
658 #if defined QIODEVICE_DEBUG
659 printf("%p \tafter: d->pos == %d, d->buffer.size() == %d\n", this, int(d
->pos
),
666 Returns true if the current read and write position is at the end
667 of the device (i.e. there is no more data available for reading on
668 the device); otherwise returns false.
670 For some devices, atEnd() can return true even though there is more data
671 to read. This special case only applies to devices that generate data in
672 direct response to you calling read() (e.g., \c /dev or \c /proc files on
673 Unix and Mac OS X, or console input / \c stdin on all platforms).
675 \sa bytesAvailable(), read(), isSequential()
677 bool QIODevice::atEnd() const
679 Q_D(const QIODevice
);
680 #if defined QIODEVICE_DEBUG
681 printf("%p QIODevice::atEnd() returns %s, d->openMode == %d, d->pos == %d\n", this, (d
->openMode
== NotOpen
|| d
->pos
== size()) ? "true" : "false",
682 int(d
->openMode
), int(d
->pos
));
684 return d
->openMode
== NotOpen
|| (d
->buffer
.isEmpty() && bytesAvailable() == 0);
688 Seeks to the start of input for random-access devices. Returns
689 true on success; otherwise returns false (for example, if the
692 Note that when using a QTextStream on a QFile, calling reset() on
693 the QFile will not have the expected result because QTextStream
694 buffers the file. Use the QTextStream::seek() function instead.
698 bool QIODevice::reset()
700 #if defined QIODEVICE_DEBUG
701 printf("%p QIODevice::reset()\n", this);
707 Returns the number of bytes that are available for reading. This
708 function is commonly used with sequential devices to determine the
709 number of bytes to allocate in a buffer before reading.
711 Subclasses that reimplement this function must call the base
712 implementation in order to include the size of QIODevices' buffer. Example:
714 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 1
716 \sa bytesToWrite(), readyRead(), isSequential()
718 qint64
QIODevice::bytesAvailable() const
720 Q_D(const QIODevice
);
721 if (!d
->isSequential())
722 return qMax(size() - d
->pos
, qint64(0));
723 return d
->buffer
.size();
727 For buffered devices, this function returns the number of bytes
728 waiting to be written. For devices with no buffer, this function
731 \sa bytesAvailable(), bytesWritten(), isSequential()
733 qint64
QIODevice::bytesToWrite() const
739 Reads at most \a maxSize bytes from the device into \a data, and
740 returns the number of bytes read. If an error occurs, such as when
741 attempting to read from a device opened in WriteOnly mode, this
744 0 is returned when no more data is available for reading. However,
745 reading past the end of the stream is considered an error, so this
746 function returns -1 in those cases (that is, reading on a closed
747 socket or after a process has died).
749 \sa readData() readLine() write()
751 qint64
QIODevice::read(char *data
, qint64 maxSize
)
754 CHECK_READABLE(read
, qint64(-1));
755 CHECK_MAXLEN(read
, qint64(-1));
757 #if defined QIODEVICE_DEBUG
758 printf("%p QIODevice::read(%p, %d), d->pos = %d, d->buffer.size() = %d\n",
759 this, data
, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
761 const bool sequential
= d
->isSequential();
763 // Short circuit for getChar()
765 int chint
= d
->buffer
.getChar();
767 char c
= char(uchar(chint
));
768 if (c
== '\r' && (d
->openMode
& Text
)) {
769 d
->buffer
.ungetChar(c
);
775 #if defined QIODEVICE_DEBUG
776 printf("%p \tread 0x%hhx (%c) returning 1 (shortcut)\n", this,
777 int(c
), isprint(c
) ? c
: '?');
784 qint64 readSoFar
= 0;
785 bool moreToRead
= true;
787 int lastReadChunkSize
= 0;
789 // Try reading from the buffer.
790 if (!d
->buffer
.isEmpty()) {
791 lastReadChunkSize
= d
->buffer
.read(data
+ readSoFar
, maxSize
- readSoFar
);
792 readSoFar
+= lastReadChunkSize
;
794 d
->pos
+= lastReadChunkSize
;
795 #if defined QIODEVICE_DEBUG
796 printf("%p \treading %d bytes from buffer into position %d\n", this, lastReadChunkSize
,
797 int(readSoFar
) - lastReadChunkSize
);
799 } else if ((d
->openMode
& Unbuffered
) == 0 && maxSize
< QIODEVICE_BUFFERSIZE
) {
800 // In buffered mode, we try to fill up the QIODevice buffer before
801 // we do anything else.
802 int bytesToBuffer
= qMax(maxSize
- readSoFar
, QIODEVICE_BUFFERSIZE
);
803 char *writePointer
= d
->buffer
.reserve(bytesToBuffer
);
805 // Make sure the device is positioned correctly.
806 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
808 qint64 readFromDevice
= readData(writePointer
, bytesToBuffer
);
809 d
->buffer
.chop(bytesToBuffer
- (readFromDevice
< 0 ? 0 : int(readFromDevice
)));
811 if (readFromDevice
> 0) {
813 d
->devicePos
+= readFromDevice
;
814 #if defined QIODEVICE_DEBUG
815 printf("%p \treading %d from device into buffer\n", this, int(readFromDevice
));
818 if (readFromDevice
< bytesToBuffer
)
819 d
->buffer
.truncate(int(readFromDevice
));
820 if (!d
->buffer
.isEmpty()) {
821 lastReadChunkSize
= d
->buffer
.read(data
+ readSoFar
, maxSize
- readSoFar
);
822 readSoFar
+= lastReadChunkSize
;
824 d
->pos
+= lastReadChunkSize
;
825 #if defined QIODEVICE_DEBUG
826 printf("%p \treading %d bytes from buffer at position %d\n", this,
827 lastReadChunkSize
, int(readSoFar
));
833 // If we need more, try reading from the device.
834 if (readSoFar
< maxSize
) {
835 // Make sure the device is positioned correctly.
836 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
838 qint64 readFromDevice
= readData(data
+ readSoFar
, maxSize
- readSoFar
);
839 #if defined QIODEVICE_DEBUG
840 printf("%p \treading %d bytes from device (total %d)\n", this, int(readFromDevice
), int(readSoFar
));
842 if (readFromDevice
== -1 && readSoFar
== 0) {
843 // error and we haven't read anything: return immediately
846 if (readFromDevice
<= 0) {
849 // see if we read as much data as we asked for
850 if (readFromDevice
< maxSize
- readSoFar
)
853 lastReadChunkSize
+= int(readFromDevice
);
854 readSoFar
+= readFromDevice
;
856 d
->pos
+= readFromDevice
;
857 d
->devicePos
+= readFromDevice
;
864 if (readSoFar
&& d
->openMode
& Text
) {
865 char *readPtr
= data
+ readSoFar
- lastReadChunkSize
;
866 const char *endPtr
= data
+ readSoFar
;
868 if (readPtr
< endPtr
) {
869 // optimization to avoid initial self-assignment
870 while (*readPtr
!= '\r') {
871 if (++readPtr
== endPtr
)
875 char *writePtr
= readPtr
;
877 while (readPtr
< endPtr
) {
878 char ch
= *readPtr
++;
885 // Make sure we get more data if there is room for more. This
886 // is very important for when someone seeks to the start of a
887 // '\r\n' and reads one character - they should get the '\n'.
888 moreToRead
= (readPtr
!= writePtr
);
891 } while (moreToRead
);
893 #if defined QIODEVICE_DEBUG
894 printf("%p \treturning %d, d->pos == %d, d->buffer.size() == %d\n", this,
895 int(readSoFar
), int(d
->pos
), d
->buffer
.size());
896 debugBinaryString(data
, readSoFar
);
904 Reads at most \a maxSize bytes from the device, and returns the
905 data read as a QByteArray.
907 This function has no way of reporting errors; returning an empty
908 QByteArray() can mean either that no data was currently available
909 for reading, or that an error occurred.
911 QByteArray
QIODevice::read(qint64 maxSize
)
914 CHECK_MAXLEN(read
, QByteArray());
916 qint64 readSoFar
= 0;
918 #if defined QIODEVICE_DEBUG
919 printf("%p QIODevice::read(%d), d->pos = %d, d->buffer.size() = %d\n",
920 this, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
926 qint64 bytesToRead
= qMin(int(maxSize
- readSoFar
), int(sizeof(buffer
)));
927 qint64 readBytes
= read(buffer
, bytesToRead
);
930 tmp
.append(buffer
, (int) readBytes
);
931 readSoFar
+= readBytes
;
932 } while (readSoFar
< maxSize
&& bytesAvailable() > 0);
940 Reads all available data from the device, and returns it as a
943 This function has no way of reporting errors; returning an empty
944 QByteArray() can mean either that no data was currently available
945 for reading, or that an error occurred.
947 QByteArray
QIODevice::readAll()
950 #if defined QIODEVICE_DEBUG
951 printf("%p QIODevice::readAll(), d->pos = %d, d->buffer.size() = %d\n",
952 this, int(d
->pos
), int(d
->buffer
.size()));
956 if (d
->isSequential() || size() == 0) {
957 // Read it in chunks. Use bytesAvailable() as an unreliable hint for
958 // sequential devices, but try to read 4K as a minimum.
959 int chunkSize
= qMax(qint64(4096), bytesAvailable());
960 qint64 totalRead
= 0;
962 tmp
.resize(tmp
.size() + chunkSize
);
963 qint64 readBytes
= read(tmp
.data() + totalRead
, chunkSize
);
964 tmp
.chop(chunkSize
- (readBytes
< 0 ? 0 : readBytes
));
967 totalRead
+= readBytes
;
968 chunkSize
= qMax(qint64(4096), bytesAvailable());
971 // Read it all in one go.
972 tmp
.resize(int(bytesAvailable()));
973 qint64 readBytes
= read(tmp
.data(), tmp
.size());
974 tmp
.resize(readBytes
< 0 ? 0 : int(readBytes
));
980 This function reads a line of ASCII characters from the device, up
981 to a maximum of \a maxSize - 1 bytes, stores the characters in \a
982 data, and returns the number of bytes read. If a line could not be
983 read but no error ocurred, this function returns 0. If an error
984 occurs, this function returns what it could the length of what
985 could be read, or -1 if nothing was read.
987 A terminating '\0' byte is always appended to \a data, so \a
988 maxSize must be larger than 1.
990 Data is read until either of the following conditions are met:
993 \o The first '\n' character is read.
994 \o \a maxSize - 1 bytes are read.
995 \o The end of the device data is detected.
998 For example, the following code reads a line of characters from a
1001 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 2
1003 The newline character ('\n') is included in the buffer. If a
1004 newline is not encountered before maxSize - 1 bytes are read, a
1005 newline will not be inserted into the buffer. On windows newline
1006 characters are replaced with '\n'.
1008 This function calls readLineData(), which is implemented using
1009 repeated calls to getChar(). You can provide a more efficient
1010 implementation by reimplementing readLineData() in your own
1013 \sa getChar(), read(), write()
1015 qint64
QIODevice::readLine(char *data
, qint64 maxSize
)
1019 qWarning("QIODevice::readLine: Called with maxSize < 2");
1023 #if defined QIODEVICE_DEBUG
1024 printf("%p QIODevice::readLine(%p, %d), d->pos = %d, d->buffer.size() = %d\n",
1025 this, data
, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
1028 // Leave room for a '\0'
1031 const bool sequential
= d
->isSequential();
1033 qint64 readSoFar
= 0;
1034 if (!d
->buffer
.isEmpty()) {
1035 readSoFar
= d
->buffer
.readLine(data
, maxSize
);
1037 d
->pos
+= readSoFar
;
1038 #if defined QIODEVICE_DEBUG
1039 printf("%p \tread from buffer: %d bytes, last character read: %hhx\n", this,
1040 int(readSoFar
), data
[int(readSoFar
) - 1]);
1042 debugBinaryString(data
, int(readSoFar
));
1044 #if defined(Q_OS_SYMBIAN)
1045 // Open C fgets strips '\r' but readSoFar gets returned as if it was still there
1046 if ((d
->openMode
& Text
) &&
1048 data
[readSoFar
- 1] == '\0' &&
1049 data
[readSoFar
- 2] == '\n') {
1053 if (readSoFar
&& data
[readSoFar
- 1] == '\n') {
1054 if (d
->openMode
& Text
) {
1055 // QRingBuffer::readLine() isn't Text aware.
1056 if (readSoFar
> 1 && data
[readSoFar
- 2] == '\r') {
1058 data
[readSoFar
- 1] = '\n';
1061 data
[readSoFar
] = '\0';
1066 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
1068 d
->baseReadLineDataCalled
= false;
1069 qint64 readBytes
= readLineData(data
+ readSoFar
, maxSize
- readSoFar
);
1070 #if defined QIODEVICE_DEBUG
1071 printf("%p \tread from readLineData: %d bytes, readSoFar = %d bytes\n", this,
1072 int(readBytes
), int(readSoFar
));
1073 if (readBytes
> 0) {
1074 debugBinaryString(data
, int(readSoFar
+ readBytes
));
1077 if (readBytes
< 0) {
1078 data
[readSoFar
] = '\0';
1079 return readSoFar
? readSoFar
: -1;
1081 readSoFar
+= readBytes
;
1082 if (!d
->baseReadLineDataCalled
&& !sequential
) {
1083 d
->pos
+= readBytes
;
1084 // If the base implementation was not called, then we must
1085 // assume the device position is invalid and force a seek.
1086 d
->devicePos
= qint64(-1);
1088 data
[readSoFar
] = '\0';
1090 if (d
->openMode
& Text
) {
1091 #if defined(Q_OS_SYMBIAN)
1092 // Open C fgets strips '\r' but readSoFar gets returned as if it was still there
1093 if (readSoFar
> 1 && data
[readSoFar
- 1] == '\0' && data
[readSoFar
- 2] == '\n') {
1097 if (readSoFar
> 1 && data
[readSoFar
- 1] == '\n' && data
[readSoFar
- 2] == '\r') {
1098 data
[readSoFar
- 2] = '\n';
1099 data
[readSoFar
- 1] = '\0';
1104 #if defined QIODEVICE_DEBUG
1105 printf("%p \treturning %d, d->pos = %d, d->buffer.size() = %d, size() = %d\n",
1106 this, int(readSoFar
), int(d
->pos
), d
->buffer
.size(), int(size()));
1107 debugBinaryString(data
, int(readSoFar
));
1115 Reads a line from the device, but no more than \a maxSize characters,
1116 and returns the result as a QByteArray.
1118 This function has no way of reporting errors; returning an empty
1119 QByteArray() can mean either that no data was currently available
1120 for reading, or that an error occurred.
1122 QByteArray
QIODevice::readLine(qint64 maxSize
)
1125 CHECK_MAXLEN(readLine
, QByteArray());
1127 const int BufferGrowth
= 4096;
1128 qint64 readSoFar
= 0;
1129 qint64 readBytes
= 0;
1131 #if defined QIODEVICE_DEBUG
1132 printf("%p QIODevice::readLine(%d), d->pos = %d, d->buffer.size() = %d\n",
1133 this, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
1140 tmp
.resize(int(readSoFar
+ qMin(int(maxSize
), BufferGrowth
)));
1142 tmp
.resize(int(readSoFar
+ BufferGrowth
));
1143 readBytes
= readLine(tmp
.data() + readSoFar
, tmp
.size() - readSoFar
);
1147 readSoFar
+= readBytes
;
1148 } while ((!maxSize
|| readSoFar
< maxSize
) &&
1149 readSoFar
+ 1 == tmp
.size() && // +1 due to the ending null
1150 tmp
.at(readSoFar
- 1) != '\n');
1152 if (readSoFar
== 0 && readBytes
== -1)
1153 tmp
.clear(); // return Null if we found an error
1155 tmp
.resize(int(readSoFar
));
1160 Reads up to \a maxSize characters into \a data and returns the
1161 number of characters read.
1163 This function is called by readLine(), and provides its base
1164 implementation, using getChar(). Buffered devices can improve the
1165 performance of readLine() by reimplementing this function.
1167 readLine() appends a '\0' byte to \a data; readLineData() does not
1170 If you reimplement this function, be careful to return the correct
1171 value: it should return the number of bytes read in this line,
1172 including the terminating newline, or 0 if there is no line to be
1173 read at this point. If an error occurs, it should return -1 if and
1174 only if no bytes were read. Reading past EOF is considered an error.
1176 qint64
QIODevice::readLineData(char *data
, qint64 maxSize
)
1179 qint64 readSoFar
= 0;
1181 int lastReadReturn
= 0;
1182 d
->baseReadLineDataCalled
= true;
1184 while (readSoFar
< maxSize
&& (lastReadReturn
= read(&c
, 1)) == 1) {
1191 #if defined QIODEVICE_DEBUG
1192 printf("%p QIODevice::readLineData(%p, %d), d->pos = %d, d->buffer.size() = %d, returns %d\n",
1193 this, data
, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()), int(readSoFar
));
1195 if (lastReadReturn
!= 1 && readSoFar
== 0)
1196 return isSequential() ? lastReadReturn
: -1;
1201 Returns true if a complete line of data can be read from the device;
1202 otherwise returns false.
1204 Note that unbuffered devices, which have no way of determining what
1205 can be read, always return false.
1207 This function is often called in conjunction with the readyRead()
1210 Subclasses that reimplement this function must call the base
1211 implementation in order to include the contents of the QIODevice's buffer. Example:
1213 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 3
1215 \sa readyRead(), readLine()
1217 bool QIODevice::canReadLine() const
1219 return d_func()->buffer
.canReadLine();
1223 Writes at most \a maxSize bytes of data from \a data to the
1224 device. Returns the number of bytes that were actually written, or
1225 -1 if an error occurred.
1227 \sa read() writeData()
1229 qint64
QIODevice::write(const char *data
, qint64 maxSize
)
1232 CHECK_WRITABLE(write
, qint64(-1));
1233 CHECK_MAXLEN(write
, qint64(-1));
1235 const bool sequential
= d
->isSequential();
1236 // Make sure the device is positioned correctly.
1237 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
1241 if (d
->openMode
& Text
) {
1242 const char *endOfData
= data
+ maxSize
;
1243 const char *startOfBlock
= data
;
1245 qint64 writtenSoFar
= 0;
1248 const char *endOfBlock
= startOfBlock
;
1249 while (endOfBlock
< endOfData
&& *endOfBlock
!= '\n')
1252 qint64 blockSize
= endOfBlock
- startOfBlock
;
1253 if (blockSize
> 0) {
1254 qint64 ret
= writeData(startOfBlock
, blockSize
);
1256 if (writtenSoFar
&& !sequential
)
1257 d
->buffer
.skip(writtenSoFar
);
1258 return writtenSoFar
? writtenSoFar
: ret
;
1262 d
->devicePos
+= ret
;
1264 writtenSoFar
+= ret
;
1267 if (endOfBlock
== endOfData
)
1270 qint64 ret
= writeData("\r\n", 2);
1272 if (writtenSoFar
&& !sequential
)
1273 d
->buffer
.skip(writtenSoFar
);
1274 return writtenSoFar
? writtenSoFar
: ret
;
1278 d
->devicePos
+= ret
;
1282 startOfBlock
= endOfBlock
+ 1;
1285 if (writtenSoFar
&& !sequential
)
1286 d
->buffer
.skip(writtenSoFar
);
1287 return writtenSoFar
;
1291 qint64 written
= writeData(data
, maxSize
);
1295 d
->devicePos
+= written
;
1297 if (!d
->buffer
.isEmpty() && !sequential
)
1298 d
->buffer
.skip(written
);
1308 Writes data from a zero-terminated string of 8-bit characters to the
1309 device. Returns the number of bytes that were actually written, or
1310 -1 if an error occurred. This is equivalent to
1313 QIODevice::write(data, qstrlen(data));
1317 \sa read() writeData()
1319 qint64
QIODevice::write(const char *data
)
1321 return write(data
, qstrlen(data
));
1324 /*! \fn qint64 QIODevice::write(const QByteArray &byteArray)
1328 Writes the content of \a byteArray to the device. Returns the number of
1329 bytes that were actually written, or -1 if an error occurred.
1331 \sa read() writeData()
1335 Puts the character \a c back into the device, and decrements the
1336 current position unless the position is 0. This function is
1337 usually called to "undo" a getChar() operation, such as when
1338 writing a backtracking parser.
1340 If \a c was not previously read from the device, the behavior is
1343 void QIODevice::ungetChar(char c
)
1346 CHECK_READABLE(read
, Q_VOID
);
1348 #if defined QIODEVICE_DEBUG
1349 printf("%p QIODevice::ungetChar(0x%hhx '%c')\n", this, c
, isprint(c
) ? c
: '?');
1352 d
->buffer
.ungetChar(c
);
1353 if (!d
->isSequential())
1357 /*! \fn bool QIODevice::putChar(char c)
1359 Writes the character \a c to the device. Returns true on success;
1360 otherwise returns false.
1362 \sa write() getChar() ungetChar()
1364 bool QIODevice::putChar(char c
)
1366 return d_func()->putCharHelper(c
);
1372 bool QIODevicePrivate::putCharHelper(char c
)
1374 return q_func()->write(&c
, 1) == 1;
1377 /*! \fn bool QIODevice::getChar(char *c)
1379 Reads one character from the device and stores it in \a c. If \a c
1380 is 0, the character is discarded. Returns true on success;
1381 otherwise returns false.
1383 \sa read() putChar() ungetChar()
1385 bool QIODevice::getChar(char *c
)
1388 const OpenMode openMode
= d
->openMode
;
1389 if (!(openMode
& ReadOnly
)) {
1390 if (openMode
== NotOpen
)
1391 qWarning("QIODevice::getChar: Closed device");
1393 qWarning("QIODevice::getChar: WriteOnly device");
1397 // Shortcut for QIODevice::read(c, 1)
1398 QRingBuffer
*buffer
= &d
->buffer
;
1399 const int chint
= buffer
->getChar();
1401 char ch
= char(uchar(chint
));
1402 if ((openMode
& Text
) && ch
== '\r') {
1403 buffer
->ungetChar(ch
);
1407 if (!d
->isSequential())
1413 // Fall back to read().
1415 if (read(&ch
, 1) == 1) {
1426 Reads at most \a maxSize bytes from the device into \a data, without side
1427 effects (i.e., if you call read() after peek(), you will get the same
1428 data). Returns the number of bytes read. If an error occurs, such as
1429 when attempting to peek a device opened in WriteOnly mode, this function
1432 0 is returned when no more data is available for reading.
1436 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 4
1440 qint64
QIODevice::peek(char *data
, qint64 maxSize
)
1442 qint64 readBytes
= read(data
, maxSize
);
1445 ungetChar(data
[i
-- - 1]);
1453 Peeks at most \a maxSize bytes from the device, returning the data peeked
1458 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 5
1460 This function has no way of reporting errors; returning an empty
1461 QByteArray() can mean either that no data was currently available
1462 for peeking, or that an error occurred.
1466 QByteArray
QIODevice::peek(qint64 maxSize
)
1468 QByteArray result
= read(maxSize
);
1469 int i
= result
.size();
1470 const char *data
= result
.constData();
1472 ungetChar(data
[i
-- - 1]);
1477 Blocks until new data is available for reading and the readyRead()
1478 signal has been emitted, or until \a msecs milliseconds have
1479 passed. If msecs is -1, this function will not time out.
1481 Returns true if new data is available for reading; otherwise returns
1482 false (if the operation timed out or if an error occurred).
1484 This function can operate without an event loop. It is
1485 useful when writing non-GUI applications and when performing
1486 I/O operations in a non-GUI thread.
1488 If called from within a slot connected to the readyRead() signal,
1489 readyRead() will not be reemitted.
1491 Reimplement this function to provide a blocking API for a custom
1492 device. The default implementation does nothing, and returns false.
1494 \warning Calling this function from the main (GUI) thread
1495 might cause your user interface to freeze.
1497 \sa waitForBytesWritten()
1499 bool QIODevice::waitForReadyRead(int msecs
)
1506 For buffered devices, this function waits until a payload of
1507 buffered written data has been written to the device and the
1508 bytesWritten() signal has been emitted, or until \a msecs
1509 milliseconds have passed. If msecs is -1, this function will
1510 not time out. For unbuffered devices, it returns immediately.
1512 Returns true if a payload of data was written to the device;
1513 otherwise returns false (i.e. if the operation timed out, or if an
1516 This function can operate without an event loop. It is
1517 useful when writing non-GUI applications and when performing
1518 I/O operations in a non-GUI thread.
1520 If called from within a slot connected to the bytesWritten() signal,
1521 bytesWritten() will not be reemitted.
1523 Reimplement this function to provide a blocking API for a custom
1524 device. The default implementation does nothing, and returns false.
1526 \warning Calling this function from the main (GUI) thread
1527 might cause your user interface to freeze.
1529 \sa waitForReadyRead()
1531 bool QIODevice::waitForBytesWritten(int msecs
)
1538 Sets the human readable description of the last device error that
1543 void QIODevice::setErrorString(const QString
&str
)
1545 d_func()->errorString
= str
;
1549 Returns a human-readable description of the last device error that
1552 \sa setErrorString()
1554 QString
QIODevice::errorString() const
1556 Q_D(const QIODevice
);
1557 if (d
->errorString
.isEmpty()) {
1558 #ifdef QT_NO_QOBJECT
1559 return QLatin1String(QT_TRANSLATE_NOOP(QIODevice
, "Unknown error"));
1561 return tr("Unknown error");
1564 return d
->errorString
;
1568 \fn qint64 QIODevice::readData(char *data, qint64 maxSize)
1570 Reads up to \a maxSize bytes from the device into \a data, and
1571 returns the number of bytes read or -1 if an error occurred. If
1572 there are no bytes to be read, this function should return -1 if
1573 there can never be more bytes available (for example: socket
1574 closed, pipe closed, sub-process finished).
1576 This function is called by QIODevice. Reimplement this function
1577 when creating a subclass of QIODevice.
1579 \sa read() readLine() writeData()
1583 \fn qint64 QIODevice::writeData(const char *data, qint64 maxSize)
1585 Writes up to \a maxSize bytes from \a data to the device. Returns
1586 the number of bytes written, or -1 if an error occurred.
1588 This function is called by QIODevice. Reimplement this function
1589 when creating a subclass of QIODevice.
1595 \fn QIODevice::Offset QIODevice::status() const
1597 For device specific error handling, please refer to the
1598 individual device documentation.
1604 \fn QIODevice::Offset QIODevice::at() const
1610 \fn bool QIODevice::at(Offset offset)
1612 Use seek(\a offset) instead.
1615 /*! \fn int QIODevice::flags() const
1617 Use openMode() instead.
1620 /*! \fn int QIODevice::getch()
1622 Use getChar() instead.
1626 \fn bool QIODevice::isAsynchronous() const
1628 This functionality is no longer available. This function always
1633 \fn bool QIODevice::isBuffered() const
1635 Use !(openMode() & QIODevice::Unbuffered) instead.
1639 \fn bool QIODevice::isCombinedAccess() const
1641 Use openMode() instead.
1645 \fn bool QIODevice::isDirectAccess() const
1647 Use !isSequential() instead.
1651 \fn bool QIODevice::isInactive() const
1653 Use isOpen(), isReadable(), or isWritable() instead.
1657 \fn bool QIODevice::isRaw() const
1659 Use openMode() instead.
1663 \fn bool QIODevice::isSequentialAccess() const
1665 Use isSequential() instead.
1669 \fn bool QIODevice::isSynchronous() const
1671 This functionality is no longer available. This function always
1676 \fn bool QIODevice::isTranslated() const
1678 Use openMode() instead.
1682 \fn bool QIODevice::mode() const
1684 Use openMode() instead.
1687 /*! \fn int QIODevice::putch(int ch)
1689 Use putChar(\a ch) instead.
1692 /*! \fn int QIODevice::ungetch(int ch)
1694 Use ungetChar(\a ch) instead.
1698 \fn quint64 QIODevice::readBlock(char *data, quint64 size)
1700 Use read(\a data, \a size) instead.
1703 /*! \fn int QIODevice::state() const
1705 Use isOpen() instead.
1709 \fn qint64 QIODevice::writeBlock(const char *data, quint64 size)
1711 Use write(\a data, \a size) instead.
1715 \fn qint64 QIODevice::writeBlock(const QByteArray &data)
1717 Use write(\a data) instead.
1720 #if defined QT3_SUPPORT
1721 QIODevice::Status
QIODevice::status() const
1723 #if !defined(QT_NO_QOBJECT)
1724 const QFile
*f
= qobject_cast
<const QFile
*>(this);
1725 if (f
) return (int) f
->error();
1727 return isOpen() ? 0 /* IO_Ok */ : 8 /* IO_UnspecifiedError */;
1731 For device specific error handling, please refer to the
1732 individual device documentation.
1736 void QIODevice::resetStatus()
1738 #if !defined(QT_NO_QOBJECT)
1739 QFile
*f
= qobject_cast
<QFile
*>(this);
1740 if (f
) f
->unsetError();
1745 #if !defined(QT_NO_DEBUG_STREAM)
1746 QDebug
operator<<(QDebug debug
, QIODevice::OpenMode modes
)
1748 debug
<< "OpenMode(";
1749 QStringList modeList
;
1750 if (modes
== QIODevice::NotOpen
) {
1751 modeList
<< QLatin1String("NotOpen");
1753 if (modes
& QIODevice::ReadOnly
)
1754 modeList
<< QLatin1String("ReadOnly");
1755 if (modes
& QIODevice::WriteOnly
)
1756 modeList
<< QLatin1String("WriteOnly");
1757 if (modes
& QIODevice::Append
)
1758 modeList
<< QLatin1String("Append");
1759 if (modes
& QIODevice::Truncate
)
1760 modeList
<< QLatin1String("Truncate");
1761 if (modes
& QIODevice::Text
)
1762 modeList
<< QLatin1String("Text");
1763 if (modes
& QIODevice::Unbuffered
)
1764 modeList
<< QLatin1String("Unbuffered");
1767 debug
<< modeList
.join(QLatin1String("|"));