qiodevice.cpp

doxygen(一个自动从源代码生成文档的工具)的源代码

  Returns the I/O device status.

  The I/O device status returns an error code.	If open() returns FALSE
  or readBlock() or writeBlock() return -1, this function can be called to
  get the reason why the operation did not succeed.

  The status codes are:
  <ul>
  <li>\c IO_Ok The operation was successful.
  <li>\c IO_ReadError Could not read from the device.
  <li>\c IO_WriteError Could not write to the device.
  <li>\c IO_FatalError A fatal unrecoverable error occurred.
  <li>\c IO_OpenError Could not open the device.
  <li>\c IO_ConnectError Could not connect to the device.
  <li>\c IO_AbortError The operation was unexpectedly aborted.
  <li>\c IO_TimeOutError The operation timed out.
  <li>\c IO_OnCloseError An unspecified error happened on close.
  </ul>

  \sa resetStatus()
*/

/*!
  \fn void QIODevice::resetStatus()

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

  \sa status()
*/


/*!
  \fn void QIODevice::setFlags( int f )
  \internal
  Used by subclasses to set the device flags.
*/

/*!
  \internal
  Used by subclasses to set the device type.
*/

void QIODevice::setType( int t )
{
#if defined(CHECK_RANGE)
    if ( (t & IO_TypeMask) != t )
	qWarning( "QIODevice::setType: Specified type out of range" );
#endif
    ioMode &= ~IO_TypeMask;			// reset type bits
    ioMode |= t;
}

/*!
  \internal
  Used by subclasses to set the device mode.
*/

void QIODevice::setMode( int m )
{
#if defined(CHECK_RANGE)
    if ( (m & IO_ModeMask) != m )
	qWarning( "QIODevice::setMode: Specified mode out of range" );
#endif
    ioMode &= ~IO_ModeMask;			// reset mode bits
    ioMode |= m;
}

/*!
  \internal
  Used by subclasses to set the device state.
*/

void QIODevice::setState( int s )
{
#if defined(CHECK_RANGE)
    if ( ((uint)s & IO_StateMask) != (uint)s )
	qWarning( "QIODevice::setState: Specified state out of range" );
#endif
    ioMode &= ~IO_StateMask;			// reset state bits
    ioMode |= (uint)s;
}

/*!
  \internal
  Used by subclasses to set the device status (not state).
*/

void QIODevice::setStatus( int s )
{
    ioSt = s;
}


/*!
  \fn bool QIODevice::open( int mode )
  Opens the I/O device using the specified \e mode.
  Returns TRUE if successful, or FALSE if the device could not be opened.

  The mode parameter \e m must be a combination of the following flags.
  <ul>
  <li>\c IO_Raw specified raw (unbuffered) file access.
  <li>\c IO_ReadOnly opens a file in read-only mode.
  <li>\c IO_WriteOnly opens a file in write-only mode.
  <li>\c IO_ReadWrite opens a file in read/write mode.
  <li>\c IO_Append sets the file index to the end of the file.
  <li>\c IO_Truncate truncates the file.
  <li>\c IO_Translate enables carriage returns and linefeed translation
  for text files under MS-DOS, Window, OS/2 and Macintosh.  On Unix systems 
  this flag has no effect. Use with caution as it will also transform every linefeed
  written to the file into a CRLF pair. This is likely to corrupt your file when
  writing binary data to it. Cannot be combined with \c IO_Raw.
  </ul>

  This virtual function must be reimplemented by all subclasses.

  \sa close()
*/

/*!
  \fn void QIODevice::close()
  Closes the I/O device.

  This virtual function must be reimplemented by all subclasses.

  \sa open()
*/

/*!
  \fn void QIODevice::flush()

  Flushes an open I/O device.

  This virtual function must be reimplemented by all subclasses.
*/


/*!
  \fn uint QIODevice::size() const
  Virtual function that returns the size of the I/O device.
  \sa at()
*/

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

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

  \sa size()
*/

int QIODevice::at() const
{
    return ioIndex;
}

/*!
  Virtual function that sets the I/O device index to \e pos.
  \sa size()
*/

bool QIODevice::at( int pos )
{
#if defined(CHECK_RANGE)
    if ( (uint)pos > size() ) {
	qWarning( "QIODevice::at: Index %d out of range", pos );
	return FALSE;
    }
#endif
    ioIndex = pos;
    return TRUE;
}

/*!
  Virtual function that returns TRUE if the I/O device index is at the
  end of the input.
*/

bool QIODevice::atEnd() const
{
    if ( isSequentialAccess() || isTranslated() ) {
	QIODevice* that = (QIODevice*)this;
	int c = that->getch();
	bool result = c < 0;
	that->ungetch(c);
	return result;
    } else {
	return at() == (int)size();
    }
}

/*!
  \fn bool QIODevice::reset()
  Sets the device index to 0.
  \sa at()
*/


/*!
  \fn int QIODevice::readBlock( char *data, uint maxlen )
  Reads at most \e maxlen bytes from the I/O device into \e data and
  returns the number of bytes actually read.

  This virtual function must be reimplemented by all subclasses.

  \sa writeBlock()
*/

/*!
  This convenience function returns all of the remaining data in the
  device.  Note that this only works for direct access devices, such
  as QFile.
  
  \sa isDirectAccess() 
*/
QByteArray QIODevice::readAll()
{
    int n = size()-at();
    QByteArray ba(size()-at());
    char* c = ba.data();
    while ( n ) {
	int r = readBlock( c, n );
	if ( r < 0 )
	    return QByteArray();
	n -= r;
	c += r;
    }
    return ba;
}

/*!
  \fn int QIODevice::writeBlock( const char *data, uint len )
  Writes \e len bytes from \e p to the I/O device and returns the number of
  bytes actually written.

  This virtual function must be reimplemented by all subclasses.

  \sa readBlock()
*/

/*!
  This convenience function is the same as calling
  writeBlock( data.data(), data.size() ).
*/
int QIODevice::writeBlock( const QByteArray& data )
{
    return writeBlock( data.data(), data.size() );
}

/*!
  Reads a line of text, up to \e maxlen bytes including a terminating
  \0.  If there is a newline at the end if the line, it is not stripped.

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

  This virtual function can be reimplemented much more efficiently by
  the most subclasses.

  \sa readBlock(), QTextStream::readLine()
*/

int QIODevice::readLine( char *data, uint maxlen )
{
    if ( maxlen == 0 )				// application bug?
	return 0;
    int pos = at();				// get current position
    int s  = (int)size();			// size of I/O device
    char *p = data;
    if ( pos >= s )
	return 0;
    while ( pos++ < s && --maxlen ) {		// read one byte at a time
	readBlock( p, 1 );
	if ( *p++ == '\n' )			// end of line
	    break;
    }
    *p++ = '\0';
    return (int)((long)p - (long)data);
}


/*!
  \fn int QIODevice::getch()

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

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

  This virtual function must be reimplemented by all subclasses.

  \sa putch(), ungetch()
*/

/*!
  \fn int QIODevice::putch( int ch )

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

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

  This virtual function must be reimplemented by all subclasses.

  \sa getch(), ungetch()
*/

/*!
  \fn int QIODevice::ungetch( int ch )

  Puts the character \e ch back into the I/O device and decrements the
  index if it is not zero.

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

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

  This virtual function must be reimplemented by all subclasses.

  \sa getch(), putch()
*/