CopperSpice API  1.7.2
QFileDevice Class Reference

Provides an interface for reading from and writing to open files. More...

Inheritance diagram for QFileDevice:
QIODevice QObject QFile QSaveFile QTemporaryFile

Public Typedefs

using Permissions = QFlags< Permission >
 
- Public Typedefs inherited from QIODevice
using OpenMode = QFlags< OpenModeFlag >
 

Public Types

enum  FileError
 
enum  MemoryMapFlags
 
enum  Permission
 
- Public Types inherited from QIODevice
enum  OpenModeFlag
 

Public Methods

 ~QFileDevice ()
 
bool atEnd () const override
 
void close () override
 
FileError error () const
 
virtual QString fileName () const
 
bool flush ()
 
int handle () const
 
bool isSequential () const override
 
ucharmap (qint64 offset, qint64 size, MemoryMapFlags flags=NoOptions)
 
virtual Permissions permissions () const
 
qint64 pos () const override
 
virtual bool resize (qint64 size)
 
bool seek (qint64 pos) override
 
virtual bool setPermissions (Permissions permissionSpec)
 
qint64 size () const override
 
bool unmap (uchar *address)
 
void unsetError ()
 
- Public Methods inherited from QIODevice
 QIODevice ()
 
 QIODevice (QObject *parent)
 
virtual ~QIODevice ()
 
virtual qint64 bytesAvailable () const
 
virtual qint64 bytesToWrite () const
 
virtual bool canReadLine () const
 
QString errorString () const
 
bool getChar (char *c)
 
bool isOpen () const
 
bool isReadable () const
 
bool isTextModeEnabled () const
 
bool isWritable () const
 
virtual bool open (OpenMode mode)
 
OpenMode openMode () const
 
qint64 peek (char *data, qint64 maxSize)
 
QByteArray peek (qint64 maxSize)
 
bool putChar (char c)
 
qint64 read (char *data, qint64 maxSize)
 
QByteArray read (qint64 maxSize)
 
QByteArray readAll ()
 
qint64 readLine (char *data, qint64 maxSize)
 
QByteArray readLine (qint64 maxSize=0)
 
virtual bool reset ()
 
void setTextModeEnabled (bool enabled)
 
void ungetChar (char c)
 
virtual bool waitForBytesWritten (int msecs)
 
virtual bool waitForReadyRead (int msecs)
 
qint64 write (const char *data)
 
qint64 write (const char *data, qint64 maxSize)
 
qint64 write (const QByteArray &data)
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &objName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Protected Methods

qint64 readData (char *data, qint64 maxSize) override
 
qint64 readLineData (char *data, qint64 maxSize) override
 
qint64 writeData (const char *data, qint64 maxSize) override
 
- Protected Methods inherited from QIODevice
void setErrorString (const QString &errorString)
 
void setOpenMode (OpenMode openMode)
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Additional Inherited Members

- Public Signals inherited from QIODevice
void aboutToClose ()
 
void bytesWritten (qint64 bytes)
 
void readChannelFinished ()
 
void readyRead ()
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 
- Public Slots inherited from QObject
void deleteLater ()
 
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Properties inherited from QObject
 objectName
 

Detailed Description

The QFileDevice class provides an interface for reading from and writing to open files.

QFileDevice is the base class for I/O devices that can read and write text and binary files and resources. QFile offers the main functionality, QFileDevice serves as a base class for sharing functionality with other file devices such as QTemporaryFile, by providing all the operations that can be done on files that have been opened by QFile or QTemporaryFile.

See also
QFile, QTemporaryFile

Member Typedef Documentation

Typedef for QFlags<Permission>. Refer to QFileDevice::Permissions for documentation.

Member Enumeration Documentation

This enum describes the errors that may be returned by error().

ConstantValueDescription
QFileDevice::NoError0No error occurred.
QFileDevice::ReadError1Error occurred when reading from the file.
QFileDevice::WriteError2Error occurred when writing to the file.
QFileDevice::FatalError3Fatal error occurred.
QFileDevice::ResourceError4 Out of resources (e.g., too many open files, out of memory, etc.)
QFileDevice::OpenError5File could not be opened.
QFileDevice::AbortError6Operation was aborted.
QFileDevice::TimeOutError7Timeout occurred.
QFileDevice::UnspecifiedError8Unspecified error occurred.
QFileDevice::RemoveError9File could not be removed.
QFileDevice::RenameError10File could not be renamed.
QFileDevice::PositionError11 Position in the file could not be changed.
QFileDevice::ResizeError12File could not be resized.
QFileDevice::PermissionsError13File could not be accessed.
QFileDevice::CopyError14File could not be copied.

This enum describes special options that may be used by the map() function.

ConstantValueDescription
QFileDevice::NoOptions0No options.

This enum is used by the permission() function to report the permissions and ownership of a file. The values may be OR-ed together to test multiple permissions and ownership values.

ConstantValueDescription
QFileDevice::ReadOwner0x4000 Readable by the owner of the file.
QFileDevice::WriteOwner0x2000 Writable by the owner of the file.
QFileDevice::ExeOwner0x1000 Executable by the owner of the file.
QFileDevice::ReadUser0x0400Readable by the user.
QFileDevice::WriteUser0x0200Writable by the user.
QFileDevice::ExeUser0x0100Executable by the user.
QFileDevice::ReadGroup0x0040Readable by the group.
QFileDevice::WriteGroup0x0020Writable by the group.
QFileDevice::ExeGroup0x0010Executable by the group.
QFileDevice::ReadOther0x0004Readable by anyone.
QFileDevice::WriteOther0x0002Writable by anyone.
QFileDevice::ExeOther0x0001Executable by anyone.

Because of differences in the platforms supported by CopperSpice the semantics of ReadUser, WriteUser and ExeUser are platform dependent.

On Unix, the rights of the owner of the file are returned and on Windows the rights of the current user are returned. On NTFS file systems ownership and permissions checking is disabled by default for performance reasons. To enable it include the following line.

extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;

Permission checking is then turned on and off by incrementing and decrementing qt_ntfs_permission_lookup by 1.

qt_ntfs_permission_lookup++; // turn checking on
qt_ntfs_permission_lookup--; // turn it off again

Constructor & Destructor Documentation

QFileDevice::~QFileDevice ( )

Destroys the file device, closing it if necessary.

Method Documentation

bool QFileDevice::atEnd ( ) const
overridevirtual

Returns true if the end of the file has been reached, otherwise returns false.

For regular empty files on Unix (e.g. those in /proc), this function returns true, since the file system reports that the size of such a file is 0. Therefore, you should not depend on atEnd() when reading data from such a file, but rather call read() until no more data can be read.

Reimplemented from QIODevice.

void QFileDevice::close ( )
overridevirtual

Calls QFileDevice::flush() and closes the file. Errors from flush are ignored.

See also
QIODevice::close()

Reimplemented from QIODevice.

FileError QFileDevice::error ( ) const

Returns the file error status.

The I/O device status returns an error code. For example, if open() returns false, or a read/write operation returns -1, this function can be called to find out the reason why the operation failed.

See also
unsetError()
QString QFileDevice::fileName ( ) const
virtual

Returns the name of the file. The default implementation in QFileDevice returns a null string.

Reimplemented in QTemporaryFile, QSaveFile, and QFile.

bool QFileDevice::flush ( )

Flushes any buffered data to the file. Returns true if successful, otherwise returns false.

int QFileDevice::handle ( ) const

Returns the file handle of the file. This is a small positive integer, suitable for use with C library functions such as fdopen() and fcntl(). If the file is not open, or there is an error, handle() returns -1.

On systems that use file descriptors for sockets (i.e. Unix systems, but not Windows) the handle can be used with QSocketNotifier as well.

See also
QSocketNotifier
bool QFileDevice::isSequential ( ) const
overridevirtual

Returns true if the file can only be manipulated sequentially, otherwise returns false. Most files support random-access, but some special files may not.

See also
QIODevice::isSequential()

Reimplemented from QIODevice.

uchar * QFileDevice::map ( qint64  offset,
qint64  size,
MemoryMapFlags  flags = NoOptions 
)

Maps size bytes of the file into memory starting at offset. A file should be open for a map to succeed but the file does not need to stay open after the memory has been mapped. When the QFile is destroyed or a new file is opened with this object, any maps that have not been unmapped will automatically be unmapped.

Any mapping options can be passed through flags.

Returns a pointer to the memory or 0 if there is an error.

See also
unmap()
Permissions QFileDevice::permissions ( ) const
virtual

Returns the complete OR-ed together combination of QFile::Permission for the file.

See also
setPermissions()

Reimplemented in QFile.

qint64 QFileDevice::pos ( ) const
overridevirtual

For random-access devices, this method returns the position that data is written to or read from. For sequential devices or closed devices, where there is no concept of a "current position", 0 is returned.

The current read/write position of the device is maintained internally by QIODevice, so reimplementing this method is not necessary. When subclassing QIODevice, use QIODevice::seek() to notify QIODevice about changes in the device position.

See also
isSequential(), seek()

Reimplemented from QIODevice.

qint64 QFileDevice::readData ( char *  data,
qint64  maxSize 
)
overrideprotectedvirtual

Reads up to maxSize bytes from the device into data, and returns the number of bytes read or -1 if an error occurred. If there are no bytes to be read and there can never be more bytes available (examples include socket closed, pipe closed, sub-process finished), returns -1.

This method is called by QIODevice. Reimplement this method when creating a subclass of QIODevice.

When reimplementing it is important this method reads all the required data before returning. This is required in order for QDataStream to be able to operate on the class. QDataStream assumes all the requested information was read and therefore does not retry reading if there was a problem.

See also
read(), readLine(), writeData()

Implements QIODevice.

qint64 QFileDevice::readLineData ( char *  data,
qint64  maxSize 
)
overrideprotectedvirtual

Reads up to maxSize characters into data and returns the number of characters read. This method is called by readLine(), and provides its base implementation, using getChar(). Buffered devices can improve the performance of readLine() by reimplementing this method.

The readLine() method appends a '\0' byte to data, readLineData() does not need to do this.

If you reimplement this method, be careful to return the correct value: it should return the number of bytes read in this line, including the terminating newline, or 0 if there is no line to be read at this point. If an error occurs, it should return -1 if and only if no bytes were read. Reading past EOF is considered an error.

Reimplemented from QIODevice.

bool QFileDevice::resize ( qint64  size)
virtual

Sets the file size (in bytes) size. Returns true if the file if the resize succeeds,false otherwise. If size is larger than the file currently is the new bytes will be set to 0, if size is smaller the file is simply truncated.

See also
size()

Reimplemented in QFile.

bool QFileDevice::seek ( qint64  pos)
overridevirtual

For random-access devices, this method sets the current position to pos returning true on success, or false if an error occurred. For sequential devices, the default behavior is to do nothing and return false.

Seeking beyond the end of a file: If the position is beyond the end of a file, then seek() shall not immediately extend the file. If a write is performed at this position, then the file shall be extended. The content of the file between the previous end of file and the newly written data is UNDEFINED and varies between platforms and file systems.

Reimplemented from QIODevice.

bool QFileDevice::setPermissions ( Permissions  permissionSpec)
virtual

Sets the permissions for the file to the permissionSpec specified. Returns true if successful, or false if the permissions can not be modified.

See also
permissions()

Reimplemented in QFile.

qint64 QFileDevice::size ( ) const
overridevirtual

Returns the size of the file. For regular empty files on Unix (e.g. those in /proc), this function returns 0; the contents of such a file are generated on demand in response to you calling read().

Reimplemented from QIODevice.

bool QFileDevice::unmap ( uchar address)

Unmaps the memory address. Returns true if the unmap succeeds, false otherwise.

See also
map()
void QFileDevice::unsetError ( )

Sets the file error to QFileDevice::NoError.

See also
error()
qint64 QFileDevice::writeData ( const char *  data,
qint64  maxSize 
)
overrideprotectedvirtual

Writes up to maxSize bytes from data to the device. Returns the number of bytes written, or -1 if an error occurred.

This method is called by QIODevice. Reimplement when creating a subclass of QIODevice. When reimplementing it is important that this method writes all the data available before returning. This is required in order for QDataStream to be able to operate on the class. QDataStream assumes all the information was written and therefore does not retry writing if there was a problem.

See also
read(), write()

Implements QIODevice.

Reimplemented in QSaveFile.