qiodevice.cpp

来自「Trolltech公司发布的图形界面操作系统。可在qt-embedded-2.3」· C++ 代码 · 共 754 行 · 第 1/2 页

    \keyword IO_ReadError
    \keyword IO_WriteError
    \keyword IO_FatalError
    \keyword IO_OpenError
    \keyword IO_ConnectError
    \keyword IO_AbortError
    \keyword IO_TimeOutError
    \keyword IO_UnspecifiedError

    The status codes are:
    \table
    \header \i Status code \i Meaning
    \row \i \c IO_Ok \i The operation was successful.
    \row \i \c IO_ReadError \i Could not read from the device.
    \row \i \c IO_WriteError \i Could not write to the device.
    \row \i \c IO_FatalError \i A fatal unrecoverable error occurred.
    \row \i \c IO_OpenError \i Could not open the device.
    \row \i \c IO_ConnectError \i Could not connect to the device.
    \row \i \c IO_AbortError \i The operation was unexpectedly aborted.
    \row \i \c IO_TimeOutError \i The operation timed out.
    \row \i \c IO_UnspecifiedError \i An unspecified error happened on close.
    \endtable

    \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(QT_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(QT_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(QT_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) to \a s.
*/

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


/*!
    \fn bool QIODevice::open( int mode )

    Opens the I/O device using the specified \a mode. Returns TRUE if
    the device was successfully opened; otherwise returns FALSE.

    The mode parameter \a mode must be an OR'ed combination of the
    following flags.
    \table
    \header \i Mode flags \i Meaning
    \row \i \c IO_Raw \i specifies raw (unbuffered) file access.
    \row \i \c IO_ReadOnly \i opens a file in read-only mode.
    \row \i \c IO_WriteOnly \i opens a file in write-only mode.
    \row \i \c IO_ReadWrite \i opens a file in read/write mode.
    \row \i \c IO_Append \i sets the file index to the end of the file.
    \row \i \c IO_Truncate \i truncates the file.
    \row \i \c IO_Translate \i enables carriage returns and linefeed
    translation for text files under MS-DOS, Windows 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 if you write write
    binary data. Cannot be combined with \c IO_Raw.
    \endtable

    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 QIODevice::Offset 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 position.

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

    \sa size()
*/

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


/*
    The following is a "bad" overload, since it does "not behave essentially
    the same" like the above. So don't use  \overload in the documentation of
    this function and we have to live with the qdoc warning which is generated
    for this.
*/
/*!
    Virtual function that sets the I/O device position to \a pos.
    Returns TRUE if the position was successfully set, i.e. \a pos is
    within range; otherwise returns FALSE.

    \sa size()
*/

bool QIODevice::at( Offset pos )
{
#if defined(QT_CHECK_RANGE)
    if ( pos > size() ) {
#if defined(QT_LARGEFILE_SUPPORT) && defined(QT_ABI_QT4)
	qWarning( "QIODevice::at: Index %llu out of range", pos );
#else
	qWarning( "QIODevice::at: Index %lu out of range", pos );
#endif
	return FALSE;
    }
#endif
    ioIndex = pos;
    return TRUE;
}

/*!
    Virtual function that returns TRUE if the I/O device position is
    at the end of the input; otherwise returns FALSE.
*/

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() == size();
    }
}

/*!
    \fn bool QIODevice::reset()

    Sets the device index position to 0.

    \sa at()
*/


/*!
    \fn int QIODevice::readBlock( char *data, Q_ULONG maxlen )

    Reads at most \a maxlen bytes from the I/O device into \a data and
    returns the number of bytes actually read.

    This function should return -1 if a fatal error occurs and should
    return 0 if there are no bytes to read.

    The device must be opened for reading, and \a data must not be 0.

    This virtual function must be reimplemented by all subclasses.

    \sa writeBlock() isOpen() isReadable()
*/

/*!
    This convenience function returns all of the remaining data in the
    device.
*/
QByteArray QIODevice::readAll()
{
    if ( isDirectAccess() ) {
	// we know the size
	int n = size()-at(); // ### fix for 64-bit or large files?
	int totalRead = 0;
	QByteArray ba( n );
	char* c = ba.data();
	while ( n ) {
	    int r = readBlock( c, n );
	    if ( r < 0 )
		return QByteArray();
	    n -= r;
	    c += r;
	    totalRead += r;
	    // If we have a translated file, then it is possible that
	    // we read less bytes than size() reports
	    if ( atEnd() ) {
		ba.resize( totalRead );
		break;
	    }
	}
	return ba;
    } else {
	// read until we reach the end
	const int blocksize = 512;
	int nread = 0;
	QByteArray ba;
	while ( !atEnd() ) {
	    ba.resize( nread + blocksize );
	    int r = readBlock( ba.data()+nread, blocksize );
	    if ( r < 0 )
		return QByteArray();
	    nread += r;
	}
	ba.resize( nread );
	return ba;
    }
}

/*!
    \fn int QIODevice::writeBlock( const char *data, Q_ULONG len )

    Writes \a len bytes from \a data to the I/O device and returns the
    number of bytes actually written.

    This function should return -1 if a fatal error occurs.

    This virtual function must be reimplemented by all subclasses.

    \sa readBlock()
*/

/*!
    \overload

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

/*!
    Reads a line of text, (or up to \a maxlen bytes if a newline isn't
    encountered) plus a terminating '\0' into \a data. If there is a
    newline at the end if the line, it is not stripped.

    Returns the number of bytes read including the terminating '\0',
    or -1 if an error occurred.

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

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

Q_LONG QIODevice::readLine( char *data, Q_ULONG maxlen )
{
    if ( maxlen == 0 )				// application bug?
	return 0;
    char *p = data;
    while ( --maxlen && (readBlock(p,1)>0) ) {	// read one byte at a time
	if ( *p++ == '\n' )			// end of line
	    break;
    }
    *p++ = '\0';
    return p - 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 \a ch to the I/O device.

    Returns \a ch, or -1 if an error occurred.

    This virtual function must be reimplemented by all subclasses.

    \sa getch(), ungetch()
*/

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

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

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

    Returns \a ch, or -1 if an error occurred.

    This virtual function must be reimplemented by all subclasses.

    \sa getch(), putch()
*/