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

所有成员列表，包括继承成员
QFileDevice 属于输入/输出和网络 .

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

公共类型

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	Permissions

公共函数

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

详细描述

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:: Permissions

此枚举用于 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).

QFileDevice 类

公共类型

公共函数

重实现公共函数

重实现保护函数

详细描述

成员类型文档编制

enum QFileDevice:: FileError

enum QFileDevice:: FileHandleFlag flags QFileDevice:: FileHandleFlags

enum QFileDevice:: FileTime

enum QFileDevice:: MemoryMapFlag flags QFileDevice:: MemoryMapFlags

enum QFileDevice:: Permission flags QFileDevice:: Permissions

成员函数文档编制

[virtual noexcept] QFileDevice:: ~QFileDevice ()

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

[override virtual] void QFileDevice:: close ()

QFileDevice::FileError QFileDevice:: error () const

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

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

bool QFileDevice:: flush ()

int QFileDevice:: handle () const

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

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

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

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

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

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

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

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