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
)
623 if (d
->openMode
== NotOpen
) {
624 qWarning("QIODevice::seek: The device is not open");
628 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()) {
644 || offset
>= qint64(d
->buffer
.size()))
645 // When seeking backwards, an operation that is only allowed for
646 // random-access devices, the buffer is cleared. The next read
647 // operation will then refill the buffer. We can optimize this, if we
648 // find that seeking backwards becomes a significant performance hit.
650 else if (!d
->buffer
.isEmpty())
651 d
->buffer
.skip(int(offset
));
653 #if defined QIODEVICE_DEBUG
654 printf("%p \tafter: d->pos == %d, d->buffer.size() == %d\n", this, int(d
->pos
),
661 Returns true if the current read and write position is at the end
662 of the device (i.e. there is no more data available for reading on
663 the device); otherwise returns false.
665 For some devices, atEnd() can return true even though there is more data
666 to read. This special case only applies to devices that generate data in
667 direct response to you calling read() (e.g., \c /dev or \c /proc files on
668 Unix and Mac OS X, or console input / \c stdin on all platforms).
670 \sa bytesAvailable(), read(), isSequential()
672 bool QIODevice::atEnd() const
674 Q_D(const QIODevice
);
675 #if defined QIODEVICE_DEBUG
676 printf("%p QIODevice::atEnd() returns %s, d->openMode == %d, d->pos == %d\n", this, (d
->openMode
== NotOpen
|| d
->pos
== size()) ? "true" : "false",
677 int(d
->openMode
), int(d
->pos
));
679 return d
->openMode
== NotOpen
|| (d
->buffer
.isEmpty() && bytesAvailable() == 0);
683 Seeks to the start of input for random-access devices. Returns
684 true on success; otherwise returns false (for example, if the
687 Note that when using a QTextStream on a QFile, calling reset() on
688 the QFile will not have the expected result because QTextStream
689 buffers the file. Use the QTextStream::seek() function instead.
693 bool QIODevice::reset()
695 #if defined QIODEVICE_DEBUG
696 printf("%p QIODevice::reset()\n", this);
702 Returns the number of bytes that are available for reading. This
703 function is commonly used with sequential devices to determine the
704 number of bytes to allocate in a buffer before reading.
706 Subclasses that reimplement this function must call the base
707 implementation in order to include the size of QIODevices' buffer. Example:
709 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 1
711 \sa bytesToWrite(), readyRead(), isSequential()
713 qint64
QIODevice::bytesAvailable() const
715 Q_D(const QIODevice
);
716 if (!d
->isSequential())
717 return qMax(size() - d
->pos
, qint64(0));
718 return d
->buffer
.size();
722 For buffered devices, this function returns the number of bytes
723 waiting to be written. For devices with no buffer, this function
726 \sa bytesAvailable(), bytesWritten(), isSequential()
728 qint64
QIODevice::bytesToWrite() const
734 Reads at most \a maxSize bytes from the device into \a data, and
735 returns the number of bytes read. If an error occurs, such as when
736 attempting to read from a device opened in WriteOnly mode, this
739 0 is returned when no more data is available for reading. However,
740 reading past the end of the stream is considered an error, so this
741 function returns -1 in those cases (that is, reading on a closed
742 socket or after a process has died).
744 \sa readData() readLine() write()
746 qint64
QIODevice::read(char *data
, qint64 maxSize
)
749 CHECK_READABLE(read
, qint64(-1));
750 CHECK_MAXLEN(read
, qint64(-1));
752 #if defined QIODEVICE_DEBUG
753 printf("%p QIODevice::read(%p, %d), d->pos = %d, d->buffer.size() = %d\n",
754 this, data
, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
756 const bool sequential
= d
->isSequential();
758 // Short circuit for getChar()
761 while ((chint
= d
->buffer
.getChar()) != -1) {
765 char c
= char(uchar(chint
));
766 if (c
== '\r' && (d
->openMode
& Text
))
769 #if defined QIODEVICE_DEBUG
770 printf("%p \tread 0x%hhx (%c) returning 1 (shortcut)\n", this,
771 int(c
), isprint(c
) ? c
: '?');
777 qint64 readSoFar
= 0;
778 bool moreToRead
= true;
780 int lastReadChunkSize
= 0;
782 // Try reading from the buffer.
783 if (!d
->buffer
.isEmpty()) {
784 lastReadChunkSize
= d
->buffer
.read(data
+ readSoFar
, maxSize
- readSoFar
);
785 readSoFar
+= lastReadChunkSize
;
787 d
->pos
+= lastReadChunkSize
;
788 #if defined QIODEVICE_DEBUG
789 printf("%p \treading %d bytes from buffer into position %d\n", this, lastReadChunkSize
,
790 int(readSoFar
) - lastReadChunkSize
);
792 } else if ((d
->openMode
& Unbuffered
) == 0 && maxSize
< QIODEVICE_BUFFERSIZE
) {
793 // In buffered mode, we try to fill up the QIODevice buffer before
794 // we do anything else.
795 int bytesToBuffer
= qMax(maxSize
- readSoFar
, QIODEVICE_BUFFERSIZE
);
796 char *writePointer
= d
->buffer
.reserve(bytesToBuffer
);
798 // Make sure the device is positioned correctly.
799 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
801 qint64 readFromDevice
= readData(writePointer
, bytesToBuffer
);
802 d
->buffer
.chop(bytesToBuffer
- (readFromDevice
< 0 ? 0 : int(readFromDevice
)));
804 if (readFromDevice
> 0) {
806 d
->devicePos
+= readFromDevice
;
807 #if defined QIODEVICE_DEBUG
808 printf("%p \treading %d from device into buffer\n", this, int(readFromDevice
));
811 if (readFromDevice
< bytesToBuffer
)
812 d
->buffer
.truncate(int(readFromDevice
));
813 if (!d
->buffer
.isEmpty()) {
814 lastReadChunkSize
= d
->buffer
.read(data
+ readSoFar
, maxSize
- readSoFar
);
815 readSoFar
+= lastReadChunkSize
;
817 d
->pos
+= lastReadChunkSize
;
818 #if defined QIODEVICE_DEBUG
819 printf("%p \treading %d bytes from buffer at position %d\n", this,
820 lastReadChunkSize
, int(readSoFar
));
826 // If we need more, try reading from the device.
827 if (readSoFar
< maxSize
) {
828 // Make sure the device is positioned correctly.
829 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
831 qint64 readFromDevice
= readData(data
+ readSoFar
, maxSize
- readSoFar
);
832 #if defined QIODEVICE_DEBUG
833 printf("%p \treading %d bytes from device (total %d)\n", this, int(readFromDevice
), int(readSoFar
));
835 if (readFromDevice
== -1 && readSoFar
== 0) {
836 // error and we haven't read anything: return immediately
839 if (readFromDevice
<= 0) {
842 // see if we read as much data as we asked for
843 if (readFromDevice
< maxSize
- readSoFar
)
846 lastReadChunkSize
+= int(readFromDevice
);
847 readSoFar
+= readFromDevice
;
849 d
->pos
+= readFromDevice
;
850 d
->devicePos
+= readFromDevice
;
857 if (readSoFar
&& d
->openMode
& Text
) {
858 char *readPtr
= data
+ readSoFar
- lastReadChunkSize
;
859 const char *endPtr
= data
+ readSoFar
;
861 if (readPtr
< endPtr
) {
862 // optimization to avoid initial self-assignment
863 while (*readPtr
!= '\r') {
864 if (++readPtr
== endPtr
)
868 char *writePtr
= readPtr
;
870 while (readPtr
< endPtr
) {
871 char ch
= *readPtr
++;
878 // Make sure we get more data if there is room for more. This
879 // is very important for when someone seeks to the start of a
880 // '\r\n' and reads one character - they should get the '\n'.
881 moreToRead
= (readPtr
!= writePtr
);
884 } while (moreToRead
);
886 #if defined QIODEVICE_DEBUG
887 printf("%p \treturning %d, d->pos == %d, d->buffer.size() == %d\n", this,
888 int(readSoFar
), int(d
->pos
), d
->buffer
.size());
889 debugBinaryString(data
, readSoFar
);
897 Reads at most \a maxSize bytes from the device, and returns the
898 data read as a QByteArray.
900 This function has no way of reporting errors; returning an empty
901 QByteArray() can mean either that no data was currently available
902 for reading, or that an error occurred.
904 QByteArray
QIODevice::read(qint64 maxSize
)
909 CHECK_MAXLEN(read
, result
);
911 #if defined QIODEVICE_DEBUG
912 printf("%p QIODevice::read(%d), d->pos = %d, d->buffer.size() = %d\n",
913 this, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
918 if (maxSize
!= qint64(int(maxSize
))) {
919 qWarning("QIODevice::read: maxSize argument exceeds QByteArray size limit");
923 qint64 readBytes
= 0;
925 result
.resize(int(maxSize
));
926 if (!result
.size()) {
927 // If resize fails, read incrementally.
930 result
.resize(int(qMin(maxSize
, result
.size() + QIODEVICE_BUFFERSIZE
)));
931 readResult
= read(result
.data() + readBytes
, result
.size() - readBytes
);
932 if (readResult
> 0 || readBytes
== 0)
933 readBytes
+= readResult
;
934 } while (readResult
== QIODEVICE_BUFFERSIZE
);
936 readBytes
= read(result
.data(), result
.size());
943 result
.resize(int(readBytes
));
951 Reads all available data from the device, and returns it as a
954 This function has no way of reporting errors; returning an empty
955 QByteArray() can mean either that no data was currently available
956 for reading, or that an error occurred.
958 QByteArray
QIODevice::readAll()
961 #if defined QIODEVICE_DEBUG
962 printf("%p QIODevice::readAll(), d->pos = %d, d->buffer.size() = %d\n",
963 this, int(d
->pos
), int(d
->buffer
.size()));
967 qint64 readBytes
= 0;
968 if (d
->isSequential() || (readBytes
= size()) == 0) {
969 // Size is unknown, read incrementally.
972 result
.resize(result
.size() + QIODEVICE_BUFFERSIZE
);
973 readResult
= read(result
.data() + readBytes
, result
.size() - readBytes
);
974 if (readResult
> 0 || readBytes
== 0)
975 readBytes
+= readResult
;
976 } while (readResult
> 0);
978 // Read it all in one go.
979 // If resize fails, don't read anything.
980 result
.resize(int(readBytes
- d
->pos
));
981 readBytes
= read(result
.data(), result
.size());
987 result
.resize(int(readBytes
));
993 This function reads a line of ASCII characters from the device, up
994 to a maximum of \a maxSize - 1 bytes, stores the characters in \a
995 data, and returns the number of bytes read. If a line could not be
996 read but no error ocurred, this function returns 0. If an error
997 occurs, this function returns what it could the length of what
998 could be read, or -1 if nothing was read.
1000 A terminating '\0' byte is always appended to \a data, so \a
1001 maxSize must be larger than 1.
1003 Data is read until either of the following conditions are met:
1006 \o The first '\n' character is read.
1007 \o \a maxSize - 1 bytes are read.
1008 \o The end of the device data is detected.
1011 For example, the following code reads a line of characters from a
1014 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 2
1016 The newline character ('\n') is included in the buffer. If a
1017 newline is not encountered before maxSize - 1 bytes are read, a
1018 newline will not be inserted into the buffer. On windows newline
1019 characters are replaced with '\n'.
1021 This function calls readLineData(), which is implemented using
1022 repeated calls to getChar(). You can provide a more efficient
1023 implementation by reimplementing readLineData() in your own
1026 \sa getChar(), read(), write()
1028 qint64
QIODevice::readLine(char *data
, qint64 maxSize
)
1032 qWarning("QIODevice::readLine: Called with maxSize < 2");
1036 #if defined QIODEVICE_DEBUG
1037 printf("%p QIODevice::readLine(%p, %d), d->pos = %d, d->buffer.size() = %d\n",
1038 this, data
, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
1041 // Leave room for a '\0'
1044 const bool sequential
= d
->isSequential();
1046 qint64 readSoFar
= 0;
1047 if (!d
->buffer
.isEmpty()) {
1048 readSoFar
= d
->buffer
.readLine(data
, maxSize
);
1050 d
->pos
+= readSoFar
;
1051 #if defined QIODEVICE_DEBUG
1052 printf("%p \tread from buffer: %d bytes, last character read: %hhx\n", this,
1053 int(readSoFar
), data
[int(readSoFar
) - 1]);
1055 debugBinaryString(data
, int(readSoFar
));
1057 #if defined(Q_OS_SYMBIAN)
1058 // Open C fgets strips '\r' but readSoFar gets returned as if it was still there
1059 if ((d
->openMode
& Text
) &&
1061 data
[readSoFar
- 1] == '\0' &&
1062 data
[readSoFar
- 2] == '\n') {
1066 if (readSoFar
&& data
[readSoFar
- 1] == '\n') {
1067 if (d
->openMode
& Text
) {
1068 // QRingBuffer::readLine() isn't Text aware.
1069 if (readSoFar
> 1 && data
[readSoFar
- 2] == '\r') {
1071 data
[readSoFar
- 1] = '\n';
1074 data
[readSoFar
] = '\0';
1079 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
1081 d
->baseReadLineDataCalled
= false;
1082 qint64 readBytes
= readLineData(data
+ readSoFar
, maxSize
- readSoFar
);
1083 #if defined QIODEVICE_DEBUG
1084 printf("%p \tread from readLineData: %d bytes, readSoFar = %d bytes\n", this,
1085 int(readBytes
), int(readSoFar
));
1086 if (readBytes
> 0) {
1087 debugBinaryString(data
, int(readSoFar
+ readBytes
));
1090 if (readBytes
< 0) {
1091 data
[readSoFar
] = '\0';
1092 return readSoFar
? readSoFar
: -1;
1094 readSoFar
+= readBytes
;
1095 if (!d
->baseReadLineDataCalled
&& !sequential
) {
1096 d
->pos
+= readBytes
;
1097 // If the base implementation was not called, then we must
1098 // assume the device position is invalid and force a seek.
1099 d
->devicePos
= qint64(-1);
1101 data
[readSoFar
] = '\0';
1103 if (d
->openMode
& Text
) {
1104 #if defined(Q_OS_SYMBIAN)
1105 // Open C fgets strips '\r' but readSoFar gets returned as if it was still there
1106 if (readSoFar
> 1 && data
[readSoFar
- 1] == '\0' && data
[readSoFar
- 2] == '\n') {
1110 if (readSoFar
> 1 && data
[readSoFar
- 1] == '\n' && data
[readSoFar
- 2] == '\r') {
1111 data
[readSoFar
- 2] = '\n';
1112 data
[readSoFar
- 1] = '\0';
1117 #if defined QIODEVICE_DEBUG
1118 printf("%p \treturning %d, d->pos = %d, d->buffer.size() = %d, size() = %d\n",
1119 this, int(readSoFar
), int(d
->pos
), d
->buffer
.size(), int(size()));
1120 debugBinaryString(data
, int(readSoFar
));
1128 Reads a line from the device, but no more than \a maxSize characters,
1129 and returns the result as a QByteArray.
1131 This function has no way of reporting errors; returning an empty
1132 QByteArray() can mean either that no data was currently available
1133 for reading, or that an error occurred.
1135 QByteArray
QIODevice::readLine(qint64 maxSize
)
1140 CHECK_MAXLEN(readLine
, result
);
1142 #if defined QIODEVICE_DEBUG
1143 printf("%p QIODevice::readLine(%d), d->pos = %d, d->buffer.size() = %d\n",
1144 this, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()));
1149 if (maxSize
> INT_MAX
) {
1150 qWarning("QIODevice::read: maxSize argument exceeds QByteArray size limit");
1154 result
.resize(int(maxSize
));
1155 qint64 readBytes
= 0;
1156 if (!result
.size()) {
1157 // If resize fails or maxSize == 0, read incrementally
1162 result
.resize(int(qMin(maxSize
, result
.size() + QIODEVICE_BUFFERSIZE
)));
1163 readResult
= readLine(result
.data() + readBytes
, result
.size() - readBytes
);
1164 if (readResult
> 0 || readBytes
== 0)
1165 readBytes
+= readResult
;
1166 } while (readResult
== QIODEVICE_BUFFERSIZE
1167 && result
[int(readBytes
)] != '\n');
1169 readBytes
= readLine(result
.data(), result
.size());
1174 result
.resize(readBytes
);
1180 Reads up to \a maxSize characters into \a data and returns the
1181 number of characters read.
1183 This function is called by readLine(), and provides its base
1184 implementation, using getChar(). Buffered devices can improve the
1185 performance of readLine() by reimplementing this function.
1187 readLine() appends a '\0' byte to \a data; readLineData() does not
1190 If you reimplement this function, be careful to return the correct
1191 value: it should return the number of bytes read in this line,
1192 including the terminating newline, or 0 if there is no line to be
1193 read at this point. If an error occurs, it should return -1 if and
1194 only if no bytes were read. Reading past EOF is considered an error.
1196 qint64
QIODevice::readLineData(char *data
, qint64 maxSize
)
1199 qint64 readSoFar
= 0;
1201 int lastReadReturn
= 0;
1202 d
->baseReadLineDataCalled
= true;
1204 while (readSoFar
< maxSize
&& (lastReadReturn
= read(&c
, 1)) == 1) {
1211 #if defined QIODEVICE_DEBUG
1212 printf("%p QIODevice::readLineData(%p, %d), d->pos = %d, d->buffer.size() = %d, returns %d\n",
1213 this, data
, int(maxSize
), int(d
->pos
), int(d
->buffer
.size()), int(readSoFar
));
1215 if (lastReadReturn
!= 1 && readSoFar
== 0)
1216 return isSequential() ? lastReadReturn
: -1;
1221 Returns true if a complete line of data can be read from the device;
1222 otherwise returns false.
1224 Note that unbuffered devices, which have no way of determining what
1225 can be read, always return false.
1227 This function is often called in conjunction with the readyRead()
1230 Subclasses that reimplement this function must call the base
1231 implementation in order to include the contents of the QIODevice's buffer. Example:
1233 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 3
1235 \sa readyRead(), readLine()
1237 bool QIODevice::canReadLine() const
1239 return d_func()->buffer
.canReadLine();
1243 Writes at most \a maxSize bytes of data from \a data to the
1244 device. Returns the number of bytes that were actually written, or
1245 -1 if an error occurred.
1247 \sa read() writeData()
1249 qint64
QIODevice::write(const char *data
, qint64 maxSize
)
1252 CHECK_WRITABLE(write
, qint64(-1));
1253 CHECK_MAXLEN(write
, qint64(-1));
1255 const bool sequential
= d
->isSequential();
1256 // Make sure the device is positioned correctly.
1257 if (d
->pos
!= d
->devicePos
&& !sequential
&& !seek(d
->pos
))
1261 if (d
->openMode
& Text
) {
1262 const char *endOfData
= data
+ maxSize
;
1263 const char *startOfBlock
= data
;
1265 qint64 writtenSoFar
= 0;
1268 const char *endOfBlock
= startOfBlock
;
1269 while (endOfBlock
< endOfData
&& *endOfBlock
!= '\n')
1272 qint64 blockSize
= endOfBlock
- startOfBlock
;
1273 if (blockSize
> 0) {
1274 qint64 ret
= writeData(startOfBlock
, blockSize
);
1276 if (writtenSoFar
&& !sequential
)
1277 d
->buffer
.skip(writtenSoFar
);
1278 return writtenSoFar
? writtenSoFar
: ret
;
1282 d
->devicePos
+= ret
;
1284 writtenSoFar
+= ret
;
1287 if (endOfBlock
== endOfData
)
1290 qint64 ret
= writeData("\r\n", 2);
1292 if (writtenSoFar
&& !sequential
)
1293 d
->buffer
.skip(writtenSoFar
);
1294 return writtenSoFar
? writtenSoFar
: ret
;
1298 d
->devicePos
+= ret
;
1302 startOfBlock
= endOfBlock
+ 1;
1305 if (writtenSoFar
&& !sequential
)
1306 d
->buffer
.skip(writtenSoFar
);
1307 return writtenSoFar
;
1311 qint64 written
= writeData(data
, maxSize
);
1315 d
->devicePos
+= written
;
1317 if (!d
->buffer
.isEmpty() && !sequential
)
1318 d
->buffer
.skip(written
);
1328 Writes data from a zero-terminated string of 8-bit characters to the
1329 device. Returns the number of bytes that were actually written, or
1330 -1 if an error occurred. This is equivalent to
1333 QIODevice::write(data, qstrlen(data));
1337 \sa read() writeData()
1339 qint64
QIODevice::write(const char *data
)
1341 return write(data
, qstrlen(data
));
1344 /*! \fn qint64 QIODevice::write(const QByteArray &byteArray)
1348 Writes the content of \a byteArray to the device. Returns the number of
1349 bytes that were actually written, or -1 if an error occurred.
1351 \sa read() writeData()
1355 Puts the character \a c back into the device, and decrements the
1356 current position unless the position is 0. This function is
1357 usually called to "undo" a getChar() operation, such as when
1358 writing a backtracking parser.
1360 If \a c was not previously read from the device, the behavior is
1363 void QIODevice::ungetChar(char c
)
1366 CHECK_READABLE(read
, Q_VOID
);
1368 #if defined QIODEVICE_DEBUG
1369 printf("%p QIODevice::ungetChar(0x%hhx '%c')\n", this, c
, isprint(c
) ? c
: '?');
1372 d
->buffer
.ungetChar(c
);
1373 if (!d
->isSequential())
1377 /*! \fn bool QIODevice::putChar(char c)
1379 Writes the character \a c to the device. Returns true on success;
1380 otherwise returns false.
1382 \sa write() getChar() ungetChar()
1384 bool QIODevice::putChar(char c
)
1386 return d_func()->putCharHelper(c
);
1392 bool QIODevicePrivate::putCharHelper(char c
)
1394 return q_func()->write(&c
, 1) == 1;
1397 /*! \fn bool QIODevice::getChar(char *c)
1399 Reads one character from the device and stores it in \a c. If \a c
1400 is 0, the character is discarded. Returns true on success;
1401 otherwise returns false.
1403 \sa read() putChar() ungetChar()
1405 bool QIODevice::getChar(char *c
)
1408 return (1 == read(c
? c
: &ch
, 1));
1414 Reads at most \a maxSize bytes from the device into \a data, without side
1415 effects (i.e., if you call read() after peek(), you will get the same
1416 data). Returns the number of bytes read. If an error occurs, such as
1417 when attempting to peek a device opened in WriteOnly mode, this function
1420 0 is returned when no more data is available for reading.
1424 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 4
1428 qint64
QIODevice::peek(char *data
, qint64 maxSize
)
1430 qint64 readBytes
= read(data
, maxSize
);
1433 ungetChar(data
[i
-- - 1]);
1441 Peeks at most \a maxSize bytes from the device, returning the data peeked
1446 \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 5
1448 This function has no way of reporting errors; returning an empty
1449 QByteArray() can mean either that no data was currently available
1450 for peeking, or that an error occurred.
1454 QByteArray
QIODevice::peek(qint64 maxSize
)
1456 QByteArray result
= read(maxSize
);
1457 int i
= result
.size();
1458 const char *data
= result
.constData();
1460 ungetChar(data
[i
-- - 1]);
1465 Blocks until new data is available for reading and the readyRead()
1466 signal has been emitted, or until \a msecs milliseconds have
1467 passed. If msecs is -1, this function will not time out.
1469 Returns true if new data is available for reading; otherwise returns
1470 false (if the operation timed out or if an error occurred).
1472 This function can operate without an event loop. It is
1473 useful when writing non-GUI applications and when performing
1474 I/O operations in a non-GUI thread.
1476 If called from within a slot connected to the readyRead() signal,
1477 readyRead() will not be reemitted.
1479 Reimplement this function to provide a blocking API for a custom
1480 device. The default implementation does nothing, and returns false.
1482 \warning Calling this function from the main (GUI) thread
1483 might cause your user interface to freeze.
1485 \sa waitForBytesWritten()
1487 bool QIODevice::waitForReadyRead(int msecs
)
1494 For buffered devices, this function waits until a payload of
1495 buffered written data has been written to the device and the
1496 bytesWritten() signal has been emitted, or until \a msecs
1497 milliseconds have passed. If msecs is -1, this function will
1498 not time out. For unbuffered devices, it returns immediately.
1500 Returns true if a payload of data was written to the device;
1501 otherwise returns false (i.e. if the operation timed out, or if an
1504 This function can operate without an event loop. It is
1505 useful when writing non-GUI applications and when performing
1506 I/O operations in a non-GUI thread.
1508 If called from within a slot connected to the bytesWritten() signal,
1509 bytesWritten() will not be reemitted.
1511 Reimplement this function to provide a blocking API for a custom
1512 device. The default implementation does nothing, and returns false.
1514 \warning Calling this function from the main (GUI) thread
1515 might cause your user interface to freeze.
1517 \sa waitForReadyRead()
1519 bool QIODevice::waitForBytesWritten(int msecs
)
1526 Sets the human readable description of the last device error that
1531 void QIODevice::setErrorString(const QString
&str
)
1533 d_func()->errorString
= str
;
1537 Returns a human-readable description of the last device error that
1540 \sa setErrorString()
1542 QString
QIODevice::errorString() const
1544 Q_D(const QIODevice
);
1545 if (d
->errorString
.isEmpty()) {
1546 #ifdef QT_NO_QOBJECT
1547 return QLatin1String(QT_TRANSLATE_NOOP(QIODevice
, "Unknown error"));
1549 return tr("Unknown error");
1552 return d
->errorString
;
1556 \fn qint64 QIODevice::readData(char *data, qint64 maxSize)
1558 Reads up to \a maxSize bytes from the device into \a data, and
1559 returns the number of bytes read or -1 if an error occurred. If
1560 there are no bytes to be read, this function should return -1 if
1561 there can never be more bytes available (for example: socket
1562 closed, pipe closed, sub-process finished).
1564 This function is called by QIODevice. Reimplement this function
1565 when creating a subclass of QIODevice.
1567 \sa read() readLine() writeData()
1571 \fn qint64 QIODevice::writeData(const char *data, qint64 maxSize)
1573 Writes up to \a maxSize bytes from \a data to the device. Returns
1574 the number of bytes written, or -1 if an error occurred.
1576 This function is called by QIODevice. Reimplement this function
1577 when creating a subclass of QIODevice.
1583 \fn QIODevice::Offset QIODevice::status() const
1585 For device specific error handling, please refer to the
1586 individual device documentation.
1592 \fn QIODevice::Offset QIODevice::at() const
1598 \fn bool QIODevice::at(Offset offset)
1600 Use seek(\a offset) instead.
1603 /*! \fn int QIODevice::flags() const
1605 Use openMode() instead.
1608 /*! \fn int QIODevice::getch()
1610 Use getChar() instead.
1614 \fn bool QIODevice::isAsynchronous() const
1616 This functionality is no longer available. This function always
1621 \fn bool QIODevice::isBuffered() const
1623 Use !(openMode() & QIODevice::Unbuffered) instead.
1627 \fn bool QIODevice::isCombinedAccess() const
1629 Use openMode() instead.
1633 \fn bool QIODevice::isDirectAccess() const
1635 Use !isSequential() instead.
1639 \fn bool QIODevice::isInactive() const
1641 Use isOpen(), isReadable(), or isWritable() instead.
1645 \fn bool QIODevice::isRaw() const
1647 Use openMode() instead.
1651 \fn bool QIODevice::isSequentialAccess() const
1653 Use isSequential() instead.
1657 \fn bool QIODevice::isSynchronous() const
1659 This functionality is no longer available. This function always
1664 \fn bool QIODevice::isTranslated() const
1666 Use openMode() instead.
1670 \fn bool QIODevice::mode() const
1672 Use openMode() instead.
1675 /*! \fn int QIODevice::putch(int ch)
1677 Use putChar(\a ch) instead.
1680 /*! \fn int QIODevice::ungetch(int ch)
1682 Use ungetChar(\a ch) instead.
1686 \fn quint64 QIODevice::readBlock(char *data, quint64 size)
1688 Use read(\a data, \a size) instead.
1691 /*! \fn int QIODevice::state() const
1693 Use isOpen() instead.
1697 \fn qint64 QIODevice::writeBlock(const char *data, quint64 size)
1699 Use write(\a data, \a size) instead.
1703 \fn qint64 QIODevice::writeBlock(const QByteArray &data)
1705 Use write(\a data) instead.
1708 #if defined QT3_SUPPORT
1709 QIODevice::Status
QIODevice::status() const
1711 #if !defined(QT_NO_QOBJECT)
1712 const QFile
*f
= qobject_cast
<const QFile
*>(this);
1713 if (f
) return (int) f
->error();
1715 return isOpen() ? 0 /* IO_Ok */ : 8 /* IO_UnspecifiedError */;
1719 For device specific error handling, please refer to the
1720 individual device documentation.
1724 void QIODevice::resetStatus()
1726 #if !defined(QT_NO_QOBJECT)
1727 QFile
*f
= qobject_cast
<QFile
*>(this);
1728 if (f
) f
->unsetError();
1733 #if !defined(QT_NO_DEBUG_STREAM)
1734 QDebug
operator<<(QDebug debug
, QIODevice::OpenMode modes
)
1736 debug
<< "OpenMode(";
1737 QStringList modeList
;
1738 if (modes
== QIODevice::NotOpen
) {
1739 modeList
<< QLatin1String("NotOpen");
1741 if (modes
& QIODevice::ReadOnly
)
1742 modeList
<< QLatin1String("ReadOnly");
1743 if (modes
& QIODevice::WriteOnly
)
1744 modeList
<< QLatin1String("WriteOnly");
1745 if (modes
& QIODevice::Append
)
1746 modeList
<< QLatin1String("Append");
1747 if (modes
& QIODevice::Truncate
)
1748 modeList
<< QLatin1String("Truncate");
1749 if (modes
& QIODevice::Text
)
1750 modeList
<< QLatin1String("Text");
1751 if (modes
& QIODevice::Unbuffered
)
1752 modeList
<< QLatin1String("Unbuffered");
1755 debug
<< modeList
.join(QLatin1String("|"));