就业培训     下载中心     Wiki     联络
登录   注册
  1. 首页
  2. Qt 6.8.5
  3. Qt Core
  4. C++ 类
  5. QFileDevice

QFileDevice 类

QFileDevice 类提供用于读写打开文件的接口。 更多...

头： #include <QFileDevice>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
继承： QIODevice
继承者：

QFile and QSaveFile

注意： 此类的所有函数 可重入 .

公共类型

enum FileError { NoError, ReadError, WriteError, FatalError, ResourceError, …, CopyError }
enum FileHandleFlag { AutoCloseHandle, DontCloseHandle }
flags FileHandleFlags
enum FileTime { FileAccessTime, FileBirthTime, FileMetadataChangeTime, FileModificationTime }
enum MemoryMapFlag { NoOptions, MapPrivateOption }
flags MemoryMapFlags
enum Permission { ReadOwner, WriteOwner, ExeOwner, ReadUser, WriteUser, …, ExeOther }
flags 权限

公共函数

virtual ~QFileDevice ()
QFileDevice::FileError error () const
virtual QString fileName () const
QDateTime fileTime (QFileDevice::FileTime time ) const
bool flush ()
int handle () const
uchar * map (qint64 offset , qint64 size , QFileDevice::MemoryMapFlags flags = NoOptions)
virtual QFileDevice::Permissions permissions () const
virtual bool resize (qint64 sz )
bool setFileTime (const QDateTime & newDate , QFileDevice::FileTime fileTime )
virtual bool setPermissions (QFileDevice::Permissions permissions )
bool unmap (uchar * address )
void unsetError ()

重实现公共函数

virtual bool atEnd () const override
virtual void close () override
virtual bool isSequential () const override
virtual qint64 pos () const override
virtual bool seek (qint64 pos ) override
virtual qint64 size () const override

重实现保护函数

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

宏

(从 6.8 起) QT_NO_USE_NODISCARD_FILE_OPEN
(从 6.8 起) QT_USE_NODISCARD_FILE_OPEN

详细描述

QFileDevice 是 I/O 设备基类，可以读写文本、二进制文件及 resources . QFile 提供主要功能，QFileDevice 充当与其它文件设备共享功能的基类，譬如 QSaveFile ，通过提供所有文件操作，打开通过 QFile or QSaveFile .

另请参阅 QFile and QSaveFile .

成员类型文档编制

enum QFileDevice:: FileError

此枚举描述的错误，返回可能是通过 error () 函数。

常量 值 描述
QFileDevice::NoError 0 没有出现错误。
QFileDevice::ReadError 1 发生错误当读取文件时。
QFileDevice::WriteError 2 出现错误，当写入文件时。
QFileDevice::FatalError 3 出现致命错误。
QFileDevice::ResourceError 4 资源不足 (如：打开的文件太多、内存不足、等)
QFileDevice::OpenError 5 文件无法打开。
QFileDevice::AbortError 6 操作被中止。
QFileDevice::TimeOutError 7 出现超时。
QFileDevice::UnspecifiedError 8 出现未指定错误。
QFileDevice::RemoveError 9 文件无法删除。
QFileDevice::RenameError 10 文件无法重命名。
QFileDevice::PositionError 11 文件位置无法改变。
QFileDevice::ResizeError 12 文件无法重置大小。
QFileDevice::PermissionsError 13 文件无法访问。
QFileDevice::CopyError 14 文件无法拷贝。

enum QFileDevice:: FileHandleFlag
flags QFileDevice:: FileHandleFlags

使用此枚举当打开文件时，以指定附加选项仅适用于文件而不适用于一般 QIODevice .

常量 值 描述
QFileDevice::AutoCloseHandle 0x0001 文件句柄被传入 open () 应关闭通过 close ()，默认行为是 close 仅仅刷新文件，且应用程序负责关闭文件句柄。当按名称打开文件时，忽略此标志，因为 Qt 始终拥有文件句柄且必须关闭它。
QFileDevice::DontCloseHandle 0 若未明确关闭，底层文件句柄保持打开，当 QFile 对象被销毁。

FileHandleFlags 类型是 typedef 对于 QFlags <FileHandleFlag>。它存储 FileHandleFlag 值的 OR 组合。

enum QFileDevice:: FileTime

此枚举用于 fileTime () 和 setFileTime () 函数。

常量 值 描述
QFileDevice::FileAccessTime 0 最近访问文件时 (如：读写)。
QFileDevice::FileBirthTime 1 创建文件时 (Unix 可能不支持)。
QFileDevice::FileMetadataChangeTime 2 最后改变文件元数据时。
QFileDevice::FileModificationTime 3 最近修改文件时。

另请参阅 setFileTime (), fileTime ()，和 QFileInfo::fileTime ().

enum QFileDevice:: MemoryMapFlag
flags QFileDevice:: MemoryMapFlags

此枚举描述的特殊选项可以用于 map () 函数。

常量 值 描述
QFileDevice::NoOptions 0 没有选项。
QFileDevice::MapPrivateOption 0x0001 映射内存将是私有的，所以，任何修改对其它进程是不可见的，且不会写入磁盘。任何这种修改都会丢失，当取消内存映射时。未指定是否对文件做出修改，在映射创建后，将透过映射内存可见。该枚举值在 Qt 5.4 引入。

MemoryMapFlags 类型是 typedef 对于 QFlags <MemoryMapFlag>。它存储 MemoryMapFlag 值的 OR 组合。

enum QFileDevice:: Permission
flags QFileDevice:: 权限

此枚举用于 permission() 函数，以报告文件的权限和所有权。可以把值 OR 在一起，以测试多权限和所有权值。

常量 值 描述
QFileDevice::ReadOwner 0x4000 文件可由文件的所有者读取。
QFileDevice::WriteOwner 0x2000 文件可由文件的所有者写入。
QFileDevice::ExeOwner 0x1000 文件可由文件的所有者执行。
QFileDevice::ReadUser 0x0400 文件对于用户是可读的。
QFileDevice::WriteUser 0x0200 文件对于用户是可写的。
QFileDevice::ExeUser 0x0100 文件可由用户执行。
QFileDevice::ReadGroup 0x0040 文件可由组读取。
QFileDevice::WriteGroup 0x0020 文件可由组写入。
QFileDevice::ExeGroup 0x0010 文件可由组执行。
QFileDevice::ReadOther 0x0004 文件可由其它读取。
QFileDevice::WriteOther 0x0002 文件可由其它写入。
QFileDevice::ExeOther 0x0001 文件可由其它执行。

警告： 由于 Qt 支持的平台差异，ReadUser、WriteUser 及 ExeUser 的语义从属平台：Unix 返回文件所有者的权限，而 Windows 返回当前用户的权限。此行为在未来 Qt 版本中可能改变。

注意： 在 NTFS 文件系统，默认情况下，出于性能原因禁用所有权和权限校验。要启用它，包括以下行： 

extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;

然后打开和关闭权限校验，通过递增和递减 qt_ntfs_permission_lookup by 1. 

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

注意： 由于这是非原子全局变量，它才安全递增或递减 qt_ntfs_permission_lookup 在除主线程外的任何线程已启动前，或在除主线程外的每个线程已结束后。

注意： 从 Qt 6.6 起，变量 qt_ntfs_permission_lookup 被弃用。请使用下列替代。

管理权限校验的安全且轻松方式是使用 RAII 类 QNtfsPermissionCheckGuard . 

void complexFunction()
{
    QNtfsPermissionCheckGuard permissionGuard;  // check is enabled
    // do complex things here that need permission check enabled
}   // as the guard goes out of scope the check is disabled

若需要更细粒度控制，取而代之，采用下列函数管理权限是可能的： 

qAreNtfsPermissionChecksEnabled();   // check status
qEnableNtfsPermissionChecks();       // turn checking on
qDisableNtfsPermissionChecks();      // turn it off again

Permissions 类型是 typedef 对于 QFlags <Permission>。它存储 Permission 值的 OR 组合。

成员函数文档编制

[virtual noexcept] QFileDevice:: ~QFileDevice ()

销毁文件设备，关闭它若有必要。

[override virtual] bool QFileDevice:: atEnd () const

重实现： QIODevice::atEnd () const.

返回 true 若到达 EOF (文件末尾)；否则返回 false。

Unix 常规空文件 (如，那些在 /proc )，此函数返回 true ，由于文件系统把这种文件的大小报告为 0。因此，不应依赖 atEnd() 当读取这种文件数据时，而是调用 read () 直到无法读取更多数据。

[override virtual] void QFileDevice:: close ()

重实现： QIODevice::close ().

调用 QFileDevice::flush () 并关闭文件。忽略 flush 错误。

另请参阅 QIODevice::close ().

QFileDevice::FileError QFileDevice:: error () const

返回文件错误状态。

I/O 设备状态返回错误代码。例如，若 open () 返回 false ，或读/写操作返回 -1，可以调用此函数以找出操作为什么失败的原因。

另请参阅 unsetError ().

[虚拟] QString QFileDevice:: fileName () const

返回文件名。默认实现在 QFileDevice 返回 null 字符串。

QDateTime QFileDevice:: fileTime ( QFileDevice::FileTime time ) const

返回文件时间指定通过 time 。若无法确定时间，返回 QDateTime() (无效日期时间)。

另请参阅 setFileTime (), FileTime ，和 QDateTime::isValid ().

bool QFileDevice:: flush ()

将任何缓冲数据刷新到文件。返回 true 若成功；否则返回 false .

int QFileDevice:: handle () const

返回文件的文件句柄。

这是小正整数，适合用于 C 库函数，譬如 fdopen() and fcntl() 。在套接字使用文件描述符的系统 (即 Unix 系统，而非 Windows) 中，句柄可以用于 QSocketNotifier 还。

若文件未被打开，或存在错误，handle() 返回 -1。

另请参阅 QSocketNotifier .

[override virtual] bool QFileDevice:: isSequential () const

重实现： QIODevice::isSequential () const.

返回 true 若只能按顺序操纵文件；否则返回 false .

大多数文件支持随机访问，但某些特殊文件不可以。

另请参阅 QIODevice::isSequential ().

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

映射 size 字节的文件到内存起始于 offset 。要成功映射，应打开文件。但文件不需要保持打开，在映射内存后。当 QFile 被销毁 (或采用此对象打开新文件)，任何尚未取消映射的映射都将自动取消映射。

映射将拥有如文件的相同打开方式 (读和/或写)，除非使用 MapPrivateOption ，在这种情况下，写入到映射内存始终是可能的。

可以传递任何映射选项透过 flags .

返回内存指针或 nullptr 若存在错误。

另请参阅 unmap ().

[虚拟] QFileDevice::Permissions QFileDevice:: permissions () const

返回用于文件 OR 在一起的完整 QFile::Permission 组合。

另请参阅 setPermissions ().

[override virtual] qint64 QFileDevice:: pos () const

重实现： QIODevice::pos () const.

[override virtual protected] qint64 QFileDevice:: readData ( char * data , qint64 len )

重实现： QIODevice::readData (char *data, qint64 maxSize).

[override virtual protected] qint64 QFileDevice:: readLineData ( char * data , qint64 maxlen )

重实现： QIODevice::readLineData (char *data, qint64 maxSize).

[虚拟] bool QFileDevice:: resize ( qint64 sz )

设置文件大小 (以字节为单位) sz 。返回 true 若重置大小成功；否则 false。若 sz > 文件目前大小，将新字节数设为 0；若 sz 更小，只需截取文件。

警告： 此函数可能失败，若文件不存在。

另请参阅 size ().

[override virtual] bool QFileDevice:: seek ( qint64 pos )

重实现： QIODevice::seek (qint64 pos).

对于随机访问设备，此函数将当前位置设为 pos ，返回 true 当成功时，或 false 若出现错误。对于顺序设备，默认行为是什么都不做并返回 false。

寻址超出 EOF (文件末尾)：若位置超出文件末尾，seek() 不会立即延伸文件。若在此位置履行写入，那么文件将延伸。在文件上一结尾和新近写入数据之间的文件内容 UNDEFINED (未定义)，且因平台和文件系统不同而异。

bool QFileDevice:: setFileTime (const QDateTime & newDate , QFileDevice::FileTime fileTime )

设置文件时间指定通过 fileTime to newDate ，返回 true 若成功；否则返回 false。

注意： 必须打开文件，才能使用此函数。

另请参阅 fileTime () 和 FileTime .

[虚拟] bool QFileDevice:: setPermissions ( QFileDevice::Permissions permissions )

将文件权限设为 permissions 指定。返回 true 若成功，或 false 若权限不能被修改。

警告： 此函数不操纵 ACL (访问控制列表)，这可能限制其有效性。

另请参阅 permissions ().

[override virtual] qint64 QFileDevice:: size () const

重实现： QIODevice::size () const.

返回文件大小。

Unix 常规空文件 (如，那些在 /proc )，此函数返回 0；这种文件的内容是按需生成的，为响应调用 read ().

bool QFileDevice:: unmap ( uchar * address )

取消映射内存 address .

返回 true 若取消映射成功；否则 false。

另请参阅 map ().

void QFileDevice:: unsetError ()

把文件的错误设为 QFileDevice::NoError .

另请参阅 error ().

[override virtual protected] qint64 QFileDevice:: writeData (const char * data , qint64 len )

重实现： QIODevice::writeData (const char *data, qint64 maxSize).

宏文档编制

[since 6.8] QT_NO_USE_NODISCARD_FILE_OPEN

[since 6.8] QT_USE_NODISCARD_FILE_OPEN

File-related I/O classes (such as QFile , QSaveFile , QTemporaryFile ) have an open() method to open the file they act upon. It is important to check the return value of the call to open() before proceeding with reading or writing data into the file.

For this reason, starting with Qt 6.8, some overloads of open() have been marked with the [[nodiscard]] attribute. Since this change may raise warnings in existing codebases, user code can opt-in or opt-out from having the attribute applied by defining certain macros:

  • 若 QT_USE_NODISCARD_FILE_OPEN macro is defined, overloads of open() are marked as [[nodiscard]] .
  • 若 QT_NO_USE_NODISCARD_FILE_OPEN is defined, the overloads of open() are not marked as [[nodiscard]] .
  • If neither macro is defined, then the default up to and including Qt 6.9 is not to have the attribute. Starting from Qt 6.10, the attribute is automatically applied.
  • If both macros are defined, the program is ill-formed.

该函数在 Qt 6.8 引入。

内容

  1. 公共类型

  2. 公共函数

  3. 重实现公共函数

  4. 重实现保护函数

  5. 宏

  6. 详细描述