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

     2 ** 

     3 **

     4 ** Implementation of QIODevice class

     5 **

     6 ** Created : 940913

     7 **

     8 ** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.

     9 **

    10 ** This file is part of the tools module of the Qt GUI Toolkit.

    11 **

    12 ** This file may be distributed under the terms of the Q Public License

    13 ** as defined by Trolltech AS of Norway and appearing in the file

    14 ** LICENSE.QPL included in the packaging of this file.

    15 **

    16 ** This file may be distributed and/or modified under the terms of the

    17 ** GNU General Public License version 2 as published by the Free Software

    18 ** Foundation and appearing in the file LICENSE.GPL included in the

    19 ** packaging of this file.

    20 **

    21 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition

    22 ** licenses may use this file in accordance with the Qt Commercial License

    23 ** Agreement provided with the Software.

    24 **

    25 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE

    26 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

    27 **

    28 ** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for

    29 **   information about Qt Commercial License Agreements.

    30 ** See http://www.trolltech.com/qpl/ for QPL licensing information.

    31 ** See http://www.trolltech.com/gpl/ for GPL licensing information.

    32 **

    33 ** Contact info@trolltech.com if any conditions of this licensing are

    34 ** not clear to you.

    35 **

    36 **********************************************************************/

    37 

    38 #include "qiodevice.h"

    39 

    40 // NOT REVISED

    41 /*!

    42   \class QIODevice qiodevice.h

    43 

    44   \brief The QIODevice class is the base class of I/O devices.

    45 

    46   \ingroup io

    47 

    48   An I/O device represents a medium that one can read bytes from

    49   and/or write bytes to.  The QIODevice class is the abstract

    50   superclass of all such devices; classes like QFile, QBuffer and

    51   QSocket inherit QIODevice and implement virtual functions like

    52   write() appropriately.

    53 

    54   While applications sometimes use QIODevice directly, mostly it is

    55   better to go through QTextStream and QDataStream, which provide

    56   stream operations on any QIODevice subclass.  QTextStream provides

    57   text-oriented stream functionality (for human-readable ASCII files,

    58   for example), while QDataStream deals with binary data in a totally

    59   platform-independent manner.

    60 

    61   The public member functions in QIODevice roughly fall into two

    62   groups: The action functions and the state access functions.  The

    63   most important action functions are: <ul>

    64 

    65   <li> open() opens a device for reading and/or writing, depending on

    66   the argument to open().

    67 

    68   <li> close() closes the device and tidies up.

    69 

    70   <li> readBlock() reads a block of data from the device.

    71 

    72   <li> writeBlock() writes a block of data to the device.

    73 

    74   <li> readLine() reads a line (of text, usually) from the device.

    75 

    76   <li> flush() ensures that all buffered data are written to the real device.

    77 

    78   </ul>There are also some other, less used, action functions: <ul>

    79 

    80   <li> getch() reads a single character.

    81 

    82   <li> ungetch() forgets the last call to getch(), if possible.

    83 

    84   <li> putch() writes a single character.

    85 

    86   <li> size() returns the size of the device, if there is one.

    87 

    88   <li> at() returns the current read/write pointer, if there is one

    89   for this device, or it moves the pointer.

    90 

    91   <li> atEnd() says whether there is more to read, if that is a

    92   meaningful question for this device.

    93 

    94   <li> reset() moves the read/write pointer to the start of the

    95   device, if that is possible for this device.

    96 

    97   </ul>The state access are all "get" functions.  The QIODevice subclass

    98   calls setState() to update the state, and simple access functions

    99   tell the user of the device what the device's state is.  Here are

   100   the settings, and their associated access functions: <ul>

   101 

   102   <li> Access type.  Some devices are direct access (it is possible to

   103   read/write anywhere) while others are sequential.  QIODevice

   104   provides the access functions isDirectAccess(), isSequentialAccess()

   105   and isCombinedAccess() to tell users what a given I/O device

   106   supports.

   107 

   108   <li> Buffering.  Some devices are accessed in raw mode while others

   109   are buffered.  Buffering usually provides greater efficiency,

   110   particularly for small read/write operations.  isBuffered() tells

   111   the user whether a given device is buffered.  (This can often be set

   112   by the application in the call to open().)

   113 

   114   <li> Synchronicity.  Synchronous devices work there and then, for

   115   example files.  When you read from a file, the file delivers its

   116   data right away.  Others, such as a socket connected to a HTTP

   117   server, may not deliver the data until seconds after you ask to read

   118   it.  isSynchronous() and isAsynchronous() tells the user how this

   119   device operates.

   120 

   121   <li> CR/LF translation.  For simplicity, applications often like to

   122   see just a single CR/LF style, and QIODevice subclasses can provide

   123   that.  isTranslated() returns TRUE if this object translates CR/LF

   124   to just LF.  (This can often be set by the application in the call

   125   to open().)

   126 

   127   <li> Accessibility.  Some files cannot be written, for example.

   128   isReadable(), isWritable and isReadWrite() tells the application

   129   whether it can read from and write to a given device.  (This can

   130   often be set by the application in the call to open().)

   131 

   132   <li> Finally, isOpen() returns TRUE if the device is open.  This can

   133   quite obviously be set using open() :)

   134 

   135   </ul>

   136 

   137   QIODevice provides numerous pure virtual functions you need to

   138   implement when subclassing it.  Here is a skeleton subclass with all

   139   the members you are certain to need, and some it's likely that you

   140   will need:

   141 

   142   \code

   143     class YourDevice : public QIODevice

   144     {

   145     public:

   146 	YourDevice();

   147        ~YourDevice();

   148 

   149 	bool open( int mode );

   150 	void close();

   151 	void flush();

   152 

   153 	uint size() const;

   154 	int  at() const;	// not a pure virtual function

   155 	bool at( int );		// not a pure virtual function

   156 	bool atEnd() const;	// not a pure virtual function

   157 

   158 	int readBlock( char *data, uint maxlen );

   159 	int writeBlock( const char *data, uint len );

   160 	int readLine( char *data, uint maxlen );

   161 

   162 	int getch();

   163 	int putch( int );

   164 	int ungetch( int );

   165     };

   166   \endcode

   167 

   168   The three non-pure virtual functions can be ignored if your device

   169   is sequential (e.g. an RS-232 port).

   170 

   171   \sa QDataStream, QTextStream

   172 */

   173 

   174 

   175 /*!

   176   Constructs an I/O device.

   177 */

   178 

   179 QIODevice::QIODevice()

   180 {

   181     ioMode = 0;					// initial mode

   182     ioSt = IO_Ok;

   183     ioIndex = 0;

   184 }

   185 

   186 /*!

   187   Destructs the I/O device.

   188 */

   189 

   190 QIODevice::~QIODevice()

   191 {

   192 }

   193 

   194 

   195 /*!

   196   \fn int QIODevice::flags() const

   197   Returns the current I/O device flags setting.

   198 

   199   Flags consists of mode flags and state flags.

   200 

   201   \sa mode(), state()

   202 */

   203 

   204 /*!

   205   \fn int QIODevice::mode() const

   206   Returns bits OR'ed together that specify the current operation mode.

   207 

   208   These are the flags that were given to the open() function.

   209 

   210   The flags are: \c IO_ReadOnly, \c IO_WriteOnly, \c IO_ReadWrite,

   211   \c IO_Append, \c IO_Truncate and \c IO_Translate.

   212 */

   213 

   214 /*!

   215   \fn int QIODevice::state() const

   216   Returns bits OR'ed together that specify the current state.

   217 

   218   The flags are: \c IO_Open.

   219 

   220   Subclasses may define more flags.

   221 */

   222 

   223 /*!

   224   \fn bool QIODevice::isDirectAccess() const

   225   Returns TRUE if the I/O device is a direct access (not sequential) device,

   226   otherwise FALSE.

   227   \sa isSequentialAccess()

   228 */

   229 

   230 /*!

   231   \fn bool QIODevice::isSequentialAccess() const

   232   Returns TRUE if the I/O device is a sequential access (not direct) device,

   233   otherwise FALSE.  Operations involving size() and at(int) are not valid

   234   on sequential devices.

   235   \sa isDirectAccess()

   236 */

   237 

   238 /*!

   239   \fn bool QIODevice::isCombinedAccess() const

   240   Returns TRUE if the I/O device is a combined access (both direct and

   241   sequential) device,  otherwise FALSE.

   242 

   243   This access method is currently not in use.

   244 */

   245 

   246 /*!

   247   \fn bool QIODevice::isBuffered() const

   248   Returns TRUE if the I/O device is a buffered (not raw) device, otherwise

   249   FALSE.

   250   \sa isRaw()

   251 */

   252 

   253 /*!

   254   \fn bool QIODevice::isRaw() const

   255   Returns TRUE if the I/O device is a raw (not buffered) device, otherwise

   256   FALSE.

   257   \sa isBuffered()

   258 */

   259 

   260 /*!

   261   \fn bool QIODevice::isSynchronous() const

   262   Returns TRUE if the I/O device is a synchronous device, otherwise

   263   FALSE.

   264   \sa isAsynchronous()

   265 */

   266 

   267 /*!

   268   \fn bool QIODevice::isAsynchronous() const

   269   Returns TRUE if the I/O device is a asynchronous device, otherwise

   270   FALSE.

   271 

   272   This mode is currently not in use.

   273 

   274   \sa isSynchronous()

   275 */

   276 

   277 /*!

   278   \fn bool QIODevice::isTranslated() const

   279   Returns TRUE if the I/O device translates carriage-return and linefeed

   280   characters.

   281 

   282   A QFile is translated if it is opened with the \c IO_Translate mode

   283   flag.

   284 */

   285 

   286 /*!

   287   \fn bool QIODevice::isReadable() const

   288   Returns TRUE if the I/O device was opened using \c IO_ReadOnly or

   289   \c IO_ReadWrite mode.

   290   \sa isWritable(), isReadWrite()

   291 */

   292 

   293 /*!

   294   \fn bool QIODevice::isWritable() const

   295   Returns TRUE if the I/O device was opened using \c IO_WriteOnly or

   296   \c IO_ReadWrite mode.

   297   \sa isReadable(), isReadWrite()

   298 */

   299 

   300 /*!

   301   \fn bool QIODevice::isReadWrite() const

   302   Returns TRUE if the I/O device was opened using \c IO_ReadWrite mode.

   303   \sa isReadable(), isWritable()

   304 */

   305 

   306 /*!

   307   \fn bool QIODevice::isInactive() const

   308   Returns TRUE if the I/O device state is 0, i.e. the device is not open.

   309   \sa isOpen()

   310 */

   311 

   312 /*!

   313   \fn bool QIODevice::isOpen() const

   314   Returns TRUE if the I/O device state has been opened, otherwise FALSE.

   315   \sa isInactive()

   316 */

   317 

   318 

   319 /*!

   320   \fn int QIODevice::status() const

   321   Returns the I/O device status.

   322 

   323   The I/O device status returns an error code.	If open() returns FALSE

   324   or readBlock() or writeBlock() return -1, this function can be called to

   325   get the reason why the operation did not succeed.

   326 

   327   The status codes are:

   328   <ul>

   329   <li>\c IO_Ok The operation was successful.

   330   <li>\c IO_ReadError Could not read from the device.

   331   <li>\c IO_WriteError Could not write to the device.

   332   <li>\c IO_FatalError A fatal unrecoverable error occurred.

   333   <li>\c IO_OpenError Could not open the device.

   334   <li>\c IO_ConnectError Could not connect to the device.

   335   <li>\c IO_AbortError The operation was unexpectedly aborted.

   336   <li>\c IO_TimeOutError The operation timed out.

   337   <li>\c IO_OnCloseError An unspecified error happened on close.

   338   </ul>

   339 

   340   \sa resetStatus()

   341 */

   342 

   343 /*!

   344   \fn void QIODevice::resetStatus()

   345 

   346   Sets the I/O device status to \c IO_Ok.

   347 

   348   \sa status()

   349 */

   350 

   351 

   352 /*!

   353   \fn void QIODevice::setFlags( int f )

   354   \internal

   355   Used by subclasses to set the device flags.

   356 */

   357 

   358 /*!

   359   \internal

   360   Used by subclasses to set the device type.

   361 */

   362 

   363 void QIODevice::setType( int t )

   364 {

   365 #if defined(CHECK_RANGE)

   366     if ( (t & IO_TypeMask) != t )

   367 	qWarning( "QIODevice::setType: Specified type out of range" );

   368 #endif

   369     ioMode &= ~IO_TypeMask;			// reset type bits

   370     ioMode |= t;

   371 }

   372 

   373 /*!

   374   \internal

   375   Used by subclasses to set the device mode.

   376 */

   377 

   378 void QIODevice::setMode( int m )

   379 {

   380 #if defined(CHECK_RANGE)

   381     if ( (m & IO_ModeMask) != m )

   382 	qWarning( "QIODevice::setMode: Specified mode out of range" );

   383 #endif

   384     ioMode &= ~IO_ModeMask;			// reset mode bits

   385     ioMode |= m;

   386 }

   387 

   388 /*!

   389   \internal

   390   Used by subclasses to set the device state.

   391 */

   392 

   393 void QIODevice::setState( int s )

   394 {

   395 #if defined(CHECK_RANGE)

   396     if ( ((uint)s & IO_StateMask) != (uint)s )

   397 	qWarning( "QIODevice::setState: Specified state out of range" );

   398 #endif

   399     ioMode &= ~IO_StateMask;			// reset state bits

   400     ioMode |= (uint)s;

   401 }

   402 

   403 /*!

   404   \internal

   405   Used by subclasses to set the device status (not state).

   406 */

   407 

   408 void QIODevice::setStatus( int s )

   409 {

   410     ioSt = s;

   411 }

   412 

   413 

   414 /*!

   415   \fn bool QIODevice::open( int mode )

   416   Opens the I/O device using the specified \e mode.

   417   Returns TRUE if successful, or FALSE if the device could not be opened.

   418 

   419   The mode parameter \e m must be a combination of the following flags.

   420   <ul>

   421   <li>\c IO_Raw specified raw (unbuffered) file access.

   422   <li>\c IO_ReadOnly opens a file in read-only mode.

   423   <li>\c IO_WriteOnly opens a file in write-only mode.

   424   <li>\c IO_ReadWrite opens a file in read/write mode.

   425   <li>\c IO_Append sets the file index to the end of the file.

   426   <li>\c IO_Truncate truncates the file.

   427   <li>\c IO_Translate enables carriage returns and linefeed translation

   428   for text files under MS-DOS, Window, OS/2 and Macintosh.  On Unix systems 

   429   this flag has no effect. Use with caution as it will also transform every linefeed

   430   written to the file into a CRLF pair. This is likely to corrupt your file when

   431   writing binary data to it. Cannot be combined with \c IO_Raw.

   432   </ul>

   433 

   434   This virtual function must be reimplemented by all subclasses.

   435 

   436   \sa close()

   437 */

   438 

   439 /*!

   440   \fn void QIODevice::close()

   441   Closes the I/O device.

   442 

   443   This virtual function must be reimplemented by all subclasses.

   444 

   445   \sa open()

   446 */

   447 

   448 /*!

   449   \fn void QIODevice::flush()

   450 

   451   Flushes an open I/O device.

   452 

   453   This virtual function must be reimplemented by all subclasses.

   454 */

   455 

   456 

   457 /*!

   458   \fn uint QIODevice::size() const

   459   Virtual function that returns the size of the I/O device.

   460   \sa at()

   461 */

   462 

   463 /*!

   464   Virtual function that returns the current I/O device index.

   465 

   466   This index is the data read/write head of the I/O device.

   467 

   468   \sa size()

   469 */

   470 

   471 int QIODevice::at() const

   472 {

   473     return ioIndex;

   474 }

   475 

   476 /*!

   477   Virtual function that sets the I/O device index to \e pos.

   478   \sa size()

   479 */

   480 

   481 bool QIODevice::at( int pos )

   482 {

   483 #if defined(CHECK_RANGE)

   484     if ( (uint)pos > size() ) {

   485 	qWarning( "QIODevice::at: Index %d out of range", pos );

   486 	return FALSE;

   487     }

   488 #endif

   489     ioIndex = pos;

   490     return TRUE;

   491 }

   492 

   493 /*!

   494   Virtual function that returns TRUE if the I/O device index is at the

   495   end of the input.

   496 */

   497 

   498 bool QIODevice::atEnd() const

   499 {

   500     if ( isSequentialAccess() || isTranslated() ) {

   501 	QIODevice* that = (QIODevice*)this;

   502 	int c = that->getch();

   503 	bool result = c < 0;

   504 	that->ungetch(c);

   505 	return result;

   506     } else {

   507 	return at() == (int)size();

   508     }

   509 }

   510 

   511 /*!

   512   \fn bool QIODevice::reset()

   513   Sets the device index to 0.

   514   \sa at()

   515 */

   516 

   517 

   518 /*!

   519   \fn int QIODevice::readBlock( char *data, uint maxlen )

   520   Reads at most \e maxlen bytes from the I/O device into \e data and

   521   returns the number of bytes actually read.

   522 

   523   This virtual function must be reimplemented by all subclasses.

   524 

   525   \sa writeBlock()

   526 */

   527 

   528 /*!

   529   This convenience function returns all of the remaining data in the

   530   device.  Note that this only works for direct access devices, such

   531   as QFile.

   532   

   533   \sa isDirectAccess() 

   534 */

   535 QByteArray QIODevice::readAll()

   536 {

   537     int n = size()-at();

   538     QByteArray ba(size()-at());

   539     char* c = ba.data();

   540     while ( n ) {

   541 	int r = readBlock( c, n );

   542 	if ( r < 0 )

   543 	    return QByteArray();

   544 	n -= r;

   545 	c += r;

   546     }

   547     return ba;

   548 }

   549 

   550 /*!

   551   \fn int QIODevice::writeBlock( const char *data, uint len )

   552   Writes \e len bytes from \e p to the I/O device and returns the number of

   553   bytes actually written.

   554 

   555   This virtual function must be reimplemented by all subclasses.

   556 

   557   \sa readBlock()

   558 */

   559 

   560 /*!

   561   This convenience function is the same as calling

   562   writeBlock( data.data(), data.size() ).

   563 */

   564 int QIODevice::writeBlock( const QByteArray& data )

   565 {

   566     return writeBlock( data.data(), data.size() );

   567 }

   568 

   569 /*!

   570   Reads a line of text, up to \e maxlen bytes including a terminating

   571   \0.  If there is a newline at the end if the line, it is not stripped.

   572 

   573   Returns the number of bytes read, or -1 in case of error.

   574 

   575   This virtual function can be reimplemented much more efficiently by

   576   the most subclasses.

   577 

   578   \sa readBlock(), QTextStream::readLine()

   579 */

   580 

   581 int QIODevice::readLine( char *data, uint maxlen )

   582 {

   583     if ( maxlen == 0 )				// application bug?

   584 	return 0;

   585     int pos = at();				// get current position

   586     int s  = (int)size();			// size of I/O device

   587     char *p = data;

   588     if ( pos >= s )

   589 	return 0;

   590     while ( pos++ < s && --maxlen ) {		// read one byte at a time

   591 	readBlock( p, 1 );

   592 	if ( *p++ == '\n' )			// end of line

   593 	    break;

   594     }

   595     *p++ = '\0';

   596     return (int)((long)p - (long)data);

   597 }

   598 

   599 

   600 /*!

   601   \fn int QIODevice::getch()

   602 

   603   Reads a single byte/character from the I/O device.

   604 

   605   Returns the byte/character read, or -1 if the end of the I/O device has been

   606   reached.

   607 

   608   This virtual function must be reimplemented by all subclasses.

   609 

   610   \sa putch(), ungetch()

   611 */

   612 

   613 /*!

   614   \fn int QIODevice::putch( int ch )

   615 

   616   Writes the character \e ch to the I/O device.

   617 

   618   Returns \e ch, or -1 if some error occurred.

   619 

   620   This virtual function must be reimplemented by all subclasses.

   621 

   622   \sa getch(), ungetch()

   623 */

   624 

   625 /*!

   626   \fn int QIODevice::ungetch( int ch )

   627 

   628   Puts the character \e ch back into the I/O device and decrements the

   629   index if it is not zero.

   630 

   631   This function is normally called to "undo" a getch() operation.

   632 

   633   Returns \e ch, or -1 if some error occurred.

   634 

   635   This virtual function must be reimplemented by all subclasses.

   636 

   637   \sa getch(), putch()

   638 */