1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtCore module of the Qt Toolkit.

     8 **

     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

    14 ** this package.

    15 **

    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.

    23 **

    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.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 //#define QIODEVICE_DEBUG

    43 

    44 #include "qbytearray.h"

    45 #include "qdebug.h"

    46 #include "qiodevice_p.h"

    47 #include "qfile.h"

    48 #include "qstringlist.h"

    49 #include <limits.h>

    50 

    51 #ifdef QIODEVICE_DEBUG

    52 #  include <ctype.h>

    53 #endif

    54 

    55 QT_BEGIN_NAMESPACE

    56 

    57 #ifdef QIODEVICE_DEBUG

    58 void debugBinaryString(const QByteArray &input)

    59 {

    60     QByteArray tmp;

    61     int startOffset = 0;

    62     for (int i = 0; i < input.size(); ++i) {

    63         tmp += input[i];

    64 

    65         if ((i % 16) == 15 || i == (input.size() - 1)) {

    66             printf("\n%15d:", startOffset);

    67             startOffset += tmp.size();

    68 

    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)

    72                 printf("   ");

    73             for (int j = 0; j < tmp.size(); ++j)

    74                 printf("%c", isprint(int(uchar(tmp[j]))) ? tmp[j] : '.');

    75             tmp.clear();

    76         }

    77     }

    78     printf("\n\n");

    79 }

    80 

    81 void debugBinaryString(const char *data, qint64 maxlen)

    82 {

    83     debugBinaryString(QByteArray(data, maxlen));

    84 }

    85 #endif

    86 

    87 #ifndef QIODEVICE_BUFFERSIZE

    88 #define QIODEVICE_BUFFERSIZE Q_INT64_C(16384)

    89 #endif

    90 

    91 #define Q_VOID

    92 

    93 #define CHECK_MAXLEN(function, returnType) \

    94     do { \

    95         if (maxSize < 0) { \

    96             qWarning("QIODevice::"#function": Called with maxSize < 0"); \

    97             return returnType; \

    98         } \

    99     } while (0)

   100 

   101 #define CHECK_WRITABLE(function, returnType) \

   102    do { \

   103        if ((d->openMode & WriteOnly) == 0) { \

   104            if (d->openMode == NotOpen) \

   105                return returnType; \

   106            qWarning("QIODevice::"#function": ReadOnly device"); \

   107            return returnType; \

   108        } \

   109    } while (0)

   110 

   111 #define CHECK_READABLE(function, returnType) \

   112    do { \

   113        if ((d->openMode & ReadOnly) == 0) { \

   114            if (d->openMode == NotOpen) \

   115                return returnType; \

   116            qWarning("QIODevice::"#function": WriteOnly device"); \

   117            return returnType; \

   118        } \

   119    } while (0)

   120 

   121 /*! \internal

   122  */

   123 QIODevicePrivate::QIODevicePrivate()

   124     : openMode(QIODevice::NotOpen), buffer(QIODEVICE_BUFFERSIZE),

   125       pos(0), devicePos(0)

   126        , baseReadLineDataCalled(false)

   127        , accessMode(Unset)

   128 #ifdef QT_NO_QOBJECT

   129        , q_ptr(0)

   130 #endif

   131 {

   132 }

   133 

   134 /*! \internal

   135  */

   136 QIODevicePrivate::~QIODevicePrivate()

   137 {

   138 }

   139 

   140 /*!

   141     \class QIODevice

   142     \reentrant

   143 

   144     \brief The QIODevice class is the base interface class of all I/O

   145     devices in Qt.

   146 

   147     \ingroup io

   148 

   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

   156     buffers).

   157 

   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.

   163 

   164     QIODevice distinguishes between two types of devices:

   165     random-access devices and sequential devices.

   166 

   167     \list

   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.

   172 

   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.

   177     \endlist

   178 

   179     You can use isSequential() to determine the type of device.

   180 

   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.

   192 

   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

   201     a separate thread:

   202 

   203     \list

   204     \o waitForReadyRead() - This function suspends operation in the

   205     calling thread until new data is available for reading.

   206 

   207     \o waitForBytesWritten() - This function suspends operation in the

   208     calling thread until one payload of data has been written to the

   209     device.

   210 

   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.

   215     \endlist

   216 

   217     Calling these functions from the main, GUI thread, may cause your

   218     user interface to freeze. Example:

   219 

   220     \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 0

   221 

   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.

   229 

   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.

   243 

   244     \sa QBuffer QFile QTcpSocket

   245 */

   246 

   247 /*!

   248     \typedef QIODevice::Offset

   249     \compat

   250 

   251     Use \c qint64 instead.

   252 */

   253 

   254 /*!

   255     \typedef QIODevice::Status

   256     \compat

   257 

   258     Use QIODevice::OpenMode instead, or see the documentation for

   259     specific devices.

   260 */

   261 

   262 /*!

   263     \enum QIODevice::OpenModeFlag

   264 

   265     This enum is used with open() to describe the mode in which a device

   266     is opened. It is also returned by openMode().

   267 

   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.

   281 

   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.

   291 */

   292 

   293 /*!     \fn QIODevice::bytesWritten(qint64 bytes)

   294 

   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.

   298 

   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).

   303 

   304     \sa readyRead()

   305 */

   306 

   307 /*!

   308     \fn QIODevice::readyRead()

   309 

   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.

   315 

   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

   319     return true).

   320 

   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.

   325 

   326     \sa bytesWritten()

   327 */

   328 

   329 /*! \fn QIODevice::aboutToClose()

   330 

   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).

   335 */

   336 

   337 /*!

   338     \fn QIODevice::readChannelFinished()

   339     \since 4.4

   340 

   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

   344     with read().

   345 

   346     \sa atEnd(), read()

   347 */

   348 

   349 #ifdef QT_NO_QOBJECT

   350 QIODevice::QIODevice()

   351     : d_ptr(new QIODevicePrivate)

   352 {

   353     d_ptr->q_ptr = this;

   354 }

   355 

   356 /*! \internal

   357 */

   358 QIODevice::QIODevice(QIODevicePrivate &dd)

   359     : d_ptr(&dd)

   360 {

   361     d_ptr->q_ptr = this;

   362 }

   363 #else

   364 

   365 /*!

   366     Constructs a QIODevice object.

   367 */

   368 

   369 QIODevice::QIODevice()

   370     : QObject(*new QIODevicePrivate, 0)

   371 {

   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()));

   376 #endif

   377 }

   378 

   379 /*!

   380     Constructs a QIODevice object with the given \a parent.

   381 */

   382 

   383 QIODevice::QIODevice(QObject *parent)

   384     : QObject(*new QIODevicePrivate, parent)

   385 {

   386 #if defined QIODEVICE_DEBUG

   387     printf("%p QIODevice::QIODevice(%p \"%s\")\n", this, parent, metaObject()->className());

   388 #endif

   389 }

   390 

   391 /*! \internal

   392 */

   393 QIODevice::QIODevice(QIODevicePrivate &dd, QObject *parent)

   394     : QObject(dd, parent)

   395 {

   396 }

   397 #endif

   398 

   399 

   400 /*!

   401     Destructs the QIODevice object.

   402 */

   403 QIODevice::~QIODevice()

   404 {

   405 #if defined QIODEVICE_DEBUG

   406     printf("%p QIODevice::~QIODevice()\n", this);

   407 #endif

   408 }

   409 

   410 /*!

   411     Returns true if this device is sequential; otherwise returns

   412     false.

   413 

   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.

   420 

   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

   424     are non-sequential.

   425 

   426     \sa bytesAvailable()

   427 */

   428 bool QIODevice::isSequential() const

   429 {

   430     return false;

   431 }

   432 

   433 /*!

   434     Returns the mode in which the device has been opened;

   435     i.e. ReadOnly or WriteOnly.

   436 

   437     \sa OpenMode

   438 */

   439 QIODevice::OpenMode QIODevice::openMode() const

   440 {

   441     return d_func()->openMode;

   442 }

   443 

   444 /*!

   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

   447     has been opened.

   448 

   449     \sa openMode() OpenMode

   450 */

   451 void QIODevice::setOpenMode(OpenMode openMode)

   452 {

   453 #if defined QIODEVICE_DEBUG

   454     printf("%p QIODevice::setOpenMode(0x%x)\n", this, int(openMode));

   455 #endif

   456     d_func()->openMode = openMode;

   457     d_func()->accessMode = QIODevicePrivate::Unset;

   458 }

   459 

   460 /*!

   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.

   464 

   465     \sa open(), setOpenMode()

   466  */

   467 void QIODevice::setTextModeEnabled(bool enabled)

   468 {

   469     Q_D(QIODevice);

   470     if (enabled)

   471         d->openMode |= Text;

   472     else

   473         d->openMode &= ~Text;

   474 }

   475 

   476 /*!

   477     Returns true if the \l Text flag is enabled; otherwise returns false.

   478 

   479     \sa setTextModeEnabled()

   480 */

   481 bool QIODevice::isTextModeEnabled() const

   482 {

   483     return d_func()->openMode & Text;

   484 }

   485 

   486 /*!

   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

   490     \c NotOpen.

   491 

   492     \sa openMode() OpenMode

   493 */

   494 bool QIODevice::isOpen() const

   495 {

   496     return d_func()->openMode != NotOpen;

   497 }

   498 

   499 /*!

   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.

   502 

   503     This is a convenience function which checks if the OpenMode of the

   504     device contains the ReadOnly flag.

   505 

   506     \sa openMode() OpenMode

   507 */

   508 bool QIODevice::isReadable() const

   509 {

   510     return (openMode() & ReadOnly) != 0;

   511 }

   512 

   513 /*!

   514     Returns true if data can be written to the device; otherwise returns

   515     false.

   516 

   517     This is a convenience function which checks if the OpenMode of the

   518     device contains the WriteOnly flag.

   519 

   520     \sa openMode() OpenMode

   521 */

   522 bool QIODevice::isWritable() const

   523 {

   524     return (openMode() & WriteOnly) != 0;

   525 }

   526 

   527 /*!

   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.

   531 

   532     \sa openMode() OpenMode

   533 */

   534 bool QIODevice::open(OpenMode mode)

   535 {

   536     Q_D(QIODevice);

   537     d->openMode = mode;

   538     d->pos = (mode & Append) ? size() : qint64(0);

   539     d->buffer.clear();

   540     d->accessMode = QIODevicePrivate::Unset;

   541 #if defined QIODEVICE_DEBUG

   542     printf("%p QIODevice::open(0x%x)\n", this, quint32(mode));

   543 #endif

   544     return true;

   545 }

   546 

   547 /*!

   548     First emits aboutToClose(), then closes the device and sets its

   549     OpenMode to NotOpen. The error string is also reset.

   550 

   551     \sa setOpenMode() OpenMode

   552 */

   553 void QIODevice::close()

   554 {

   555     Q_D(QIODevice);

   556     if (d->openMode == NotOpen)

   557         return;

   558 

   559 #if defined QIODEVICE_DEBUG

   560     printf("%p QIODevice::close()\n", this);

   561 #endif

   562 

   563 #ifndef QT_NO_QOBJECT

   564     emit aboutToClose();

   565 #endif

   566     d->openMode = NotOpen;

   567     d->errorString.clear();

   568     d->pos = 0;

   569     d->buffer.clear();

   570 }

   571 

   572 /*!

   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

   576     returned.

   577 

   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.

   582 

   583     \sa isSequential(), seek()

   584 */

   585 qint64 QIODevice::pos() const

   586 {

   587     Q_D(const QIODevice);

   588 #if defined QIODEVICE_DEBUG

   589     printf("%p QIODevice::pos() == %d\n", this, int(d->pos));

   590 #endif

   591     return d->pos;

   592 }

   593 

   594 /*!

   595     For open random-access devices, this function returns the size of the

   596     device. For open sequential devices, bytesAvailable() is returned.

   597 

   598     If the device is closed, the size returned will not reflect the actual

   599     size of the device.

   600 

   601     \sa isSequential(), pos()

   602 */

   603 qint64 QIODevice::size() const

   604 {

   605     return d_func()->isSequential() ?  bytesAvailable() : qint64(0);

   606 }

   607 

   608 /*!

   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

   612     return false.

   613 

   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.

   617 

   618     \sa pos(), isSequential()

   619 */

   620 bool QIODevice::seek(qint64 pos)

   621 {

   622     if (d_func()->openMode == NotOpen) {

   623         qWarning("QIODevice::seek: The device is not open");

   624         return false;

   625     }

   626     if (pos < 0) {

   627         qWarning("QIODevice::seek: Invalid pos: %d", int(pos));

   628         return false;

   629     }

   630 

   631     Q_D(QIODevice);

   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());

   635 #endif

   636 

   637     qint64 offset = pos - d->pos;

   638     if (!d->isSequential()) {

   639         d->pos = pos;

   640         d->devicePos = pos;

   641     }

   642 

   643     if (offset > 0 && !d->buffer.isEmpty()) {

   644         // When seeking forwards, we need to pop bytes off the front of the

   645         // buffer.

   646         do {

   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.

   656         d->buffer.clear();

   657     }

   658 #if defined QIODEVICE_DEBUG

   659     printf("%p \tafter: d->pos == %d, d->buffer.size() == %d\n", this, int(d->pos),

   660            d->buffer.size());

   661 #endif

   662     return true;

   663 }

   664 

   665 /*!

   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.

   669 

   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).

   674 

   675     \sa bytesAvailable(), read(), isSequential()

   676 */

   677 bool QIODevice::atEnd() const

   678 {

   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));

   683 #endif

   684     return d->openMode == NotOpen || (d->buffer.isEmpty() && bytesAvailable() == 0);

   685 }

   686 

   687 /*!

   688     Seeks to the start of input for random-access devices. Returns

   689     true on success; otherwise returns false (for example, if the

   690     device is not open).

   691 

   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.

   695 

   696     \sa seek()

   697 */

   698 bool QIODevice::reset()

   699 {

   700 #if defined QIODEVICE_DEBUG

   701     printf("%p QIODevice::reset()\n", this);

   702 #endif

   703     return seek(0);

   704 }

   705 

   706 /*!

   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.

   710 

   711     Subclasses that reimplement this function must call the base

   712     implementation in order to include the size of QIODevices' buffer. Example:

   713 

   714     \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 1

   715 

   716     \sa bytesToWrite(), readyRead(), isSequential()

   717 */

   718 qint64 QIODevice::bytesAvailable() const

   719 {

   720     Q_D(const QIODevice);

   721     if (!d->isSequential())

   722         return qMax(size() - d->pos, qint64(0));

   723     return d->buffer.size();

   724 }

   725 

   726 /*!

   727     For buffered devices, this function returns the number of bytes

   728     waiting to be written. For devices with no buffer, this function

   729     returns 0.

   730 

   731     \sa bytesAvailable(), bytesWritten(), isSequential()

   732 */

   733 qint64 QIODevice::bytesToWrite() const

   734 {

   735     return qint64(0);

   736 }

   737 

   738 /*!

   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

   742     function returns -1.

   743 

   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).

   748 

   749     \sa readData() readLine() write()

   750 */

   751 qint64 QIODevice::read(char *data, qint64 maxSize)

   752 {

   753     Q_D(QIODevice);

   754     CHECK_READABLE(read, qint64(-1));

   755     CHECK_MAXLEN(read, qint64(-1));

   756 

   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()));

   760 #endif

   761     const bool sequential = d->isSequential();

   762 

   763     // Short circuit for getChar()

   764     if (maxSize == 1) {

   765         int chint = d->buffer.getChar();

   766         if (chint != -1) {

   767             char c = char(uchar(chint));

   768             if (c == '\r' && (d->openMode & Text)) {

   769                 d->buffer.ungetChar(c);

   770             } else {

   771                 if (data)

   772                     *data = c;

   773                 if (!sequential)

   774                     ++d->pos;

   775 #if defined QIODEVICE_DEBUG

   776                 printf("%p \tread 0x%hhx (%c) returning 1 (shortcut)\n", this,

   777                        int(c), isprint(c) ? c : '?');

   778 #endif

   779                 return qint64(1);

   780             }

   781         }

   782     }

   783 

   784     qint64 readSoFar = 0;

   785     bool moreToRead = true;

   786     do {

   787         int lastReadChunkSize = 0;

   788 

   789         // Try reading from the buffer.

   790         if (!d->buffer.isEmpty()) {

   791             lastReadChunkSize = d->buffer.read(data + readSoFar, maxSize - readSoFar);

   792             readSoFar += lastReadChunkSize;

   793             if (!sequential)

   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);

   798 #endif

   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);

   804 

   805             // Make sure the device is positioned correctly.

   806             if (d->pos != d->devicePos && !sequential && !seek(d->pos))

   807                 return qint64(-1);

   808             qint64 readFromDevice = readData(writePointer, bytesToBuffer);

   809             d->buffer.chop(bytesToBuffer - (readFromDevice < 0 ? 0 : int(readFromDevice)));

   810 

   811             if (readFromDevice > 0) {

   812                 if (!sequential)

   813                     d->devicePos += readFromDevice;

   814 #if defined QIODEVICE_DEBUG

   815                 printf("%p \treading %d from device into buffer\n", this, int(readFromDevice));

   816 #endif

   817 

   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;

   823                     if (!sequential)

   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));

   828 #endif

   829                 }

   830             }

   831         }

   832 

   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))

   837                 return qint64(-1);

   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));

   841 #endif

   842             if (readFromDevice == -1 && readSoFar == 0) {

   843                 // error and we haven't read anything: return immediately

   844                 return -1;

   845             }

   846             if (readFromDevice <= 0) {

   847                 moreToRead = false;

   848             } else {

   849                 // see if we read as much data as we asked for

   850                 if (readFromDevice < maxSize - readSoFar)

   851                     moreToRead = false;

   852 

   853                 lastReadChunkSize += int(readFromDevice);

   854                 readSoFar += readFromDevice;

   855                 if (!sequential) {

   856                     d->pos += readFromDevice;

   857                     d->devicePos += readFromDevice;

   858                 }

   859             }

   860         } else {

   861             moreToRead = false;

   862         }

   863 

   864         if (readSoFar && d->openMode & Text) {

   865             char *readPtr = data + readSoFar - lastReadChunkSize;

   866             const char *endPtr = data + readSoFar;

   867 

   868             if (readPtr < endPtr) {

   869                 // optimization to avoid initial self-assignment

   870                 while (*readPtr != '\r') {

   871                     if (++readPtr == endPtr)

   872                         return readSoFar;

   873                 }

   874 

   875                 char *writePtr = readPtr;

   876 

   877                 while (readPtr < endPtr) {

   878                     char ch = *readPtr++;

   879                     if (ch != '\r')

   880                         *writePtr++ = ch;

   881                     else

   882                         --readSoFar;

   883                 }

   884 

   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);

   889             }

   890         }

   891     } while (moreToRead);

   892 

   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);

   897 #endif

   898     return readSoFar;

   899 }

   900 

   901 /*!

   902     \overload

   903 

   904     Reads at most \a maxSize bytes from the device, and returns the

   905     data read as a QByteArray.

   906 

   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.

   910 */

   911 QByteArray QIODevice::read(qint64 maxSize)

   912 {

   913     Q_D(QIODevice);

   914     CHECK_MAXLEN(read, QByteArray());

   915     QByteArray tmp;

   916     qint64 readSoFar = 0;

   917     char buffer[4096];

   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()));

   921 #else

   922     Q_UNUSED(d);

   923 #endif

   924 

   925     do {

   926         qint64 bytesToRead = qMin(int(maxSize - readSoFar), int(sizeof(buffer)));

   927         qint64 readBytes = read(buffer, bytesToRead);

   928         if (readBytes <= 0)

   929             break;

   930         tmp.append(buffer, (int) readBytes);

   931         readSoFar += readBytes;

   932     } while (readSoFar < maxSize && bytesAvailable() > 0);

   933 

   934     return tmp;

   935 }

   936 

   937 /*!

   938     \overload

   939 

   940     Reads all available data from the device, and returns it as a

   941     QByteArray.

   942 

   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.

   946 */

   947 QByteArray QIODevice::readAll()

   948 {

   949     Q_D(QIODevice);

   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()));

   953 #endif

   954 

   955     QByteArray tmp;

   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;

   961         forever {

   962             tmp.resize(tmp.size() + chunkSize);

   963             qint64 readBytes = read(tmp.data() + totalRead, chunkSize);

   964             tmp.chop(chunkSize - (readBytes < 0 ? 0 : readBytes));

   965             if (readBytes <= 0)

   966                 return tmp;

   967             totalRead += readBytes;

   968             chunkSize = qMax(qint64(4096), bytesAvailable());

   969         }

   970     } else {

   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));

   975     }

   976     return tmp;

   977 }

   978 

   979 /*!

   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.

   986 

   987     A terminating '\0' byte is always appended to \a data, so \a

   988     maxSize must be larger than 1.

   989 

   990     Data is read until either of the following conditions are met:

   991 

   992     \list

   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.

   996     \endlist

   997 

   998     For example, the following code reads a line of characters from a

   999     file:

  1000 

  1001     \snippet doc/src/snippets/code/src_corelib_io_qiodevice.cpp 2

  1002 

  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'.

  1007 

  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

  1011     subclass.

  1012 

  1013     \sa getChar(), read(), write()

  1014 */

  1015 qint64 QIODevice::readLine(char *data, qint64 maxSize)

  1016 {

  1017     Q_D(QIODevice);

  1018     if (maxSize < 2) {

  1019         qWarning("QIODevice::readLine: Called with maxSize < 2");

  1020         return qint64(-1);

  1021     }

  1022 

  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()));

  1026 #endif

  1027 

  1028     // Leave room for a '\0'

  1029     --maxSize;

  1030 

  1031     const bool sequential = d->isSequential();

  1032 

  1033     qint64 readSoFar = 0;

  1034     if (!d->buffer.isEmpty()) {

  1035         readSoFar = d->buffer.readLine(data, maxSize);

  1036         if (!sequential)

  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]);

  1041         if (readSoFar)

  1042             debugBinaryString(data, int(readSoFar));

  1043 #endif

  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) &&

  1047             readSoFar > 1 &&

  1048             data[readSoFar - 1] == '\0' &&

  1049             data[readSoFar - 2] == '\n') {

  1050             --readSoFar;

  1051         }

  1052 #endif

  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') {

  1057                     --readSoFar;

  1058                     data[readSoFar - 1] = '\n';

  1059                 }

  1060             }

  1061             data[readSoFar] = '\0';

  1062             return readSoFar;

  1063         }

  1064     }

  1065 

  1066     if (d->pos != d->devicePos && !sequential && !seek(d->pos))

  1067         return qint64(-1);

  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));

  1075     }

  1076 #endif

  1077     if (readBytes < 0) {

  1078         data[readSoFar] = '\0';

  1079         return readSoFar ? readSoFar : -1;

  1080     }

  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);

  1087     }

  1088     data[readSoFar] = '\0';

  1089 

  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') {

  1094             --readSoFar;

  1095         }

  1096 #endif

  1097         if (readSoFar > 1 && data[readSoFar - 1] == '\n' && data[readSoFar - 2] == '\r') {

  1098             data[readSoFar - 2] = '\n';

  1099             data[readSoFar - 1] = '\0';

  1100             --readSoFar;

  1101         }

  1102     }

  1103 

  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));

  1108 #endif

  1109     return readSoFar;

  1110 }

  1111 

  1112 /*!

  1113     \overload

  1114 

  1115     Reads a line from the device, but no more than \a maxSize characters,

  1116     and returns the result as a QByteArray.

  1117 

  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.

  1121 */

  1122 QByteArray QIODevice::readLine(qint64 maxSize)

  1123 {

  1124     Q_D(QIODevice);

  1125     CHECK_MAXLEN(readLine, QByteArray());

  1126     QByteArray tmp;

  1127     const int BufferGrowth = 4096;

  1128     qint64 readSoFar = 0;

  1129     qint64 readBytes = 0;

  1130 

  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()));

  1134 #else