QT（16）- QFileDevice

1 简介

QFileDevice是Qt框架中的一个类，是QIODevice的子类，用于在文件系统中进行I/O操作。QIODevice是Qt中所有I/O设备类的基类，其中包括文件、串口、套接字等等。

QFileDevice封装了文件系统中文件和设备的共同特性，提供了一些通用的I/O操作接口，如读、写、定位和判断文件末尾等。在实际开发中，我们经常使用QFile类（QFile是QFileDevice的子类）来操作文件。

2 公有类型

2.1 enum QFileDevice::FileError

2.2 enum QFileDevice：：FileHandleFlag

2.3 enum QFileDevice::FileTime

2.4 enum QFileDevice：：MemoryMapFlags

2.5 enum QFileDevice::Permission

3 公有函数

3.1 error

QFileDevice::FileError QFileDevice::error() const
QFileDevice::error()是一个用于返回文件错误状态的函数。在进行文件I/O操作时，可能会出现各种错误，例如打开文件失败、读写文件失败等等。当发生这些错误时，可以通过调用error()函数来获取错误码，以便进行错误处理。

可以使用errorString()获取错误信息

QFile file("example.txt");
if (!file.open(QIODevice::ReadOnly)) {
    qDebug() << "Failed to open file, error code: " << file.error();
    qDebug() << "Error message: " << file.errorString();
}

3.2 fileName

QString QFileDevice::fileName() const
获得文件名称

3.3 fileTime

QDateTime QFileDevice::fileTime(QFileDevice::FileTime time) const
QFileDevice::fileTime(QFileDevice::FileTime time)是一个Qt 5.10版本引入的函数，用于返回文件指定时间的值。其中，time参数是一个枚举类型，用于指定要返回的时间类型，可能的值包括：

FileAccessTime：最后访问时间。
FileModificationTime：最后修改时间。
FileBirthTime：创建时间（仅在支持的文件系统中可用）。
如果文件的时间不能确定，则返回一个无效的日期时间值QDateTime()。

时间可能和操作系统上看的时间不一样

QFile file("4.txt");
qDebug()<<"创建时间："<<file.fileTime(QFileDevice::FileBirthTime).toString(DATETIMEFORMAT);
qDebug()<<"最近访问时间："<<file.fileTime(QFileDevice::FileAccessTime).toString(DATETIMEFORMAT);
qDebug()<<"修改文件时间："<< file.fileTime(QFileDevice::FileModificationTime).toString(DATETIMEFORMAT);
qDebug()<<"上次访问时间："<<file.fileTime(QFileDevice::FileMetadataChangeTime).toString(DATETIMEFORMAT);

bool QFileDevice::setFileTime(const QDateTime &newDate, QFileDevice::FileTime fileTime)
setFileTime()函数是QFileDevice类中的一个成员函数，用于设置文件的时间戳。该函数接受两个参数：一个QDateTime类型的参数newDate，用于指定新的时间戳；一个QFileDevice::FileTime类型的参数fileTime，用于指定要设置的时间戳类型。

调用setFileTime()函数时，如果文件当前已经被打开，则会将指定类型的时间戳设置为新的时间戳，并返回true表示设置成功。如果文件没有被打开，或者设置时间戳失败，则返回false表示设置失败。

3.4 flush()

bool QFileDevice::flush()
QFileDevice::flush()函数用于将文件中的缓冲数据刷新到磁盘中，以确保所有已写入的数据都已被写入到磁盘中。该函数会将所有已缓冲的数据都刷新到文件中，即使该文件尚未关闭。

flush()函数返回一个布尔值，表示缓冲区的数据是否成功写入文件。如果缓冲数据成功写入文件，则返回true，否则返回false。

使用flush()函数的主要场景是在进行文件写操作时，当需要确保写入的数据已经被写入磁盘后，才能进行下一步操作。例如，在对关键数据进行写操作时，需要确保数据已经写入磁盘中，以防止系统崩溃或意外断电等情况下导致数据丢失。

3.5 handle

int QFileDevice::handle() const
QFileDevice::handle()函数返回文件的文件句柄（file handle），文件句柄是一个小的正整数，适用于使用C库函数（如fdopen()和fcntl()）进行操作的场景，例如：

将文件句柄转换为文件流：可以使用fdopen()函数将文件句柄转换为标准C库的文件流，以便使用C库函数进行文件操作。
修改文件句柄的属性：可以使用fcntl()函数修改文件句柄的属性，如文件读写方式、文件状态标志等等。
在使用文件句柄进行文件操作时，需要注意，文件句柄只在操作系统内部有效，不同的操作系统使用的文件句柄类型和取值范围可能不同，因此不建议将文件句柄泄露到应用程序外部。

如果文件未打开或出现错误，则handle()函数返回-1。

3.6 map

uchar *QFileDevice::map(qint64 offset, qint64 size, QFileDevice::MemoryMapFlags flags = NoOptions)
QFileDevice::map(qint64 offset, qint64 size, QFileDevice::MemoryMapFlags flags = NoOptions)函数用于将文件中的一段区域映射到内存中，从而可以在内存中对文件进行读写操作。其中，offset参数表示从文件中哪个位置开始映射，size参数表示映射的字节数。该函数返回一个指向内存映射区域的指针。

在进行内存映射时，需要注意以下几点：

内存映射需要文件处于打开状态。如果文件未打开，则映射将失败。
内存映射的大小不能超过文件的大小。如果映射的字节数超过了文件的大小，将会导致内存访问越界，从而可能导致程序崩溃或者数据丢失。
内存映射会将文件映射到进程的地址空间中。如果映射区域过大，可能会占用大量的内存资源，从而导致系统性能下降。
如果使用了QFileDevice::MapPrivateOption选项，则可以在内存中对文件进行读写操作。否则，只能对内存映射区域进行读操作。

bool QFileDevice::unmap(uchar *address)

unmap()函数是QFileDevice类中的一个成员函数，用于将使用map()函数映射到内存中的文件解除映射。该函数接受一个uchar*类型的参数address，用于指定要解除映射的内存地址。

调用unmap()函数时，如果参数address指定的内存地址是使用map()函数映射到内存中的文件地址，则会将该内存地址解除映射，并返回true表示解除映射成功。如果参数address不是使用map()函数映射到内存中的文件地址，或者解除映射失败，则返回false表示解除映射失败。

3.7 permissions

QFileDevice::Permissions QFileDevice::permissions() const
permissions()函数是QFileDevice类中的一个成员函数，用于返回文件的完整权限，即将QFile::Permission枚举值进行按位或运算后的结果。

bool QFileDevice::setPermissions(QFileDevice::Permissions permissions)
设置权限

3.8 resize

bool QFileDevice::resize(qint64 sz)
resize()函数是QFileDevice类中的一个成员函数，用于调整文件的大小。该函数接受一个qint64类型的参数sz，用于指定文件调整后的大小，单位为字节。

调用resize()函数时，如果文件当前的大小小于指定的大小，则会在文件末尾添加零字节，直到文件的大小等于指定的大小为止。如果文件当前的大小大于指定的大小，则文件中的内容将被截断，只保留前sz个字节的内容。

resize()函数的返回值为布尔类型，表示文件调整大小是否成功。如果函数调用成功，则返回true，否则返回false。

3.9 unsetError

unsetError()函数是QFileDevice类中的一个成员函数，用于将文件的错误状态重置为QFileDevice::NoError。调用该函数后，文件的错误状态会被清除，相当于没有发生过任何错误。

在进行文件操作时，如果发生了错误（如文件不存在、无法打开文件、文件读写失败等），可以调用setError()函数将文件的错误状态设置为相应的错误码，以便于后续的错误处理。在处理完错误后，可以调用unsetError()函数将文件的错误状态重置为QFileDevice::NoError，以便于继续进行文件操作。

4 重新实现的公共函数

4.1 atEnd

virtual bool atEnd() const override
atEnd()是QIODevice类中的一个虚函数，用于判断当前读取位置是否位于数据流的末尾。该函数没有参数，返回值为布尔类型，表示当前读取位置是否位于数据流的末尾。如果读取位置位于数据流的末尾，则返回true；否则返回false。

在QIODevice的派生类中，如QFile、QTcpSocket、QUdpSocket等，都可以重载atEnd()函数，根据具体的数据流类型实现相应的功能。

QFile file("test.txt");
if (file.open(QIODevice::ReadOnly)) {
    // 读取文件内容
    QByteArray data;
    while (!file.atEnd()) {
        data += file.read(1024);
    }
    file.close();
}

4.2 close

virtual void close() override
close()函数是QIODevice类中的一个虚函数，用于关闭数据流，释放底层资源。该函数没有参数，也没有返回值。

4.3 isSequential()

virtual bool isSequential() const override
isSequential()是QIODevice类中的一个虚函数，用于判断当前数据流是否是顺序读写的。该函数没有参数，返回值为布尔类型，表示当前数据流是否是顺序读写的。如果数据流是顺序读写的，则返回true；否则返回false。

在QIODevice的派生类中，如QFile、QTcpSocket、QUdpSocket等，都可以重载isSequential()函数，根据具体的数据流类型实现相应的功能。

顺序读写的数据流是指不能在数据流中随机定位的数据流，例如网络套接字、串口等。这种数据流只能从头到尾按照顺序进行读写操作，不能随意跳跃读写。相反，文件等数据流则可以随意定位和读写。

4.4 pos

virtual qint64 pos() const override
pos()是QIODevice类中的一个虚函数，用于获取当前读写位置在数据流中的字节偏移量。该函数没有参数，返回值为qint64类型，表示当前读写位置在数据流中的字节偏移量。

在QIODevice的派生类中，如QFile、QTcpSocket、QUdpSocket等，都可以重载pos()函数，根据具体的数据流类型实现相应的功能。

字节偏移量指的是数据流中某个位置相对于数据流起始位置的字节距离。以文件为例，文件中每个字节都有一个唯一的地址，可以通过该地址唯一确定文件中的某个位置。字节偏移量就是相对于文件起始位置的字节距离。

例如，假设有一个大小为10字节的文件，文件中每个字节的地址分别为0、1、2、3、4、5、6、7、8、9。如果当前读取位置在第5个字节处，则该位置的字节偏移量为4（因为字节偏移量从0开始计数）。如果需要将读取位置移动到第8个字节处，则可以调用seek()函数，并将参数设置为8，这样读取位置就会从第5个字节移动到第8个字节。

在读写数据流时，通常需要使用字节偏移量来定位读写位置，例如在文件中查找某个特定的内容、在网络套接字中接收固定长度的数据等。因此，了解字节偏移量的概念和使用方法，对于编写高效、可靠的数据流操作代码非常重要。

4.5 seek

virtual bool seek(qint64 pos) override
seek()是QIODevice类中的一个虚函数，用于将当前读写位置移动到指定的字节偏移量处。该函数的参数为qint64类型，表示需要移动的字节偏移量，返回值为布尔类型，表示是否移动成功。如果移动成功，则返回true；否则返回false。

在QIODevice的派生类中，如QFile、QTcpSocket、QUdpSocket等，都可以重载seek()函数，根据具体的数据流类型实现相应的功能。

4.6 size

virtual qint64 size() const override
返回文件大小

5 重新实现的受保护函数

virtual qint64 readData(char *data, qint64 len) override
virtual qint64 readLineData(char *data, qint64 maxlen) override
virtual qint64 writeData(const char *data, qint64 len) override

readData()：从数据流中读取最多len字节的数据，并将数据存储在data缓冲区中。该函数的返回值为qint64类型，表示实际读取的字节数。如果读取失败，则返回-1。

readLineData()：从数据流中读取一行数据，最多读取maxlen字节。行数据的结束标志为\n或\r\n。该函数的返回值为qint64类型，表示实际读取的字节数。如果读取失败，则返回-1。

writeData()：将data缓冲区中的len字节数据写入到数据流中。该函数的返回值为qint64类型，表示实际写入的字节数。如果写入失败，则返回-1。