就業培訓     下載中心     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 ().

[virtual] 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 ().

[virtual] 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).

[virtual] 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 .

[virtual] 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. 詳細描述