qtools/qiodevice.cpp

   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 */