diff options
| author | Mate Barany <mate.barany@qt.io> | 2023-10-18 16:18:38 +0200 |
|---|---|---|
| committer | Mate Barany <mate.barany@qt.io> | 2023-12-06 20:25:19 +0000 |
| commit | fa79b56bd82df6852aab6819dc31b359ee7b24e7 (patch) | |
| tree | d42df7c30601ed6ec3548ab720821cd0a6ffaae3 /src | |
| parent | a744d308269066e2b9b0ee5f2615e739ac7be688 (diff) | |
Create class documentation for QNtfsPermissionCheckGuard
...and document the related functions as well.
Pick-to: 6.6
Fixes: QTBUG-116350
Change-Id: I038d59f6af46b29e2123bc8b6c24ff4ffea78bbf
Reviewed-by: Marc Mutz <marc.mutz@qt.io>
Reviewed-by: Kai Köhne <kai.koehne@qt.io>
Diffstat (limited to 'src')
| -rw-r--r-- | src/corelib/io/qfile.cpp | 101 | ||||
| -rw-r--r-- | src/corelib/io/qfile.h | 2 | ||||
| -rw-r--r-- | src/corelib/io/qfilesystemengine_win.cpp | 18 |
3 files changed, 102 insertions, 19 deletions
diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp index e1362416307..a360b32ea50 100644 --- a/src/corelib/io/qfile.cpp +++ b/src/corelib/io/qfile.cpp @@ -1250,6 +1250,107 @@ qint64 QFile::size() const */ +/*! + \class QNtfsPermissionCheckGuard + \since 6.6 + \inmodule QtCore + \brief The QNtfsPermissionCheckGuard class is a RAII class to manage NTFS + permission checking. + + \ingroup io + + For performance reasons, QFile, QFileInfo, and related classes do not + perform full ownership and permission (ACL) checking on NTFS file systems + by default. During the lifetime of any instance of this class, that + default is overridden and advanced checking is performed. This provides + a safe and easy way to manage enabling and disabling this change to the + default behavior. + + Example: + + \snippet ntfsp.cpp raii + + This class is available only on Windows. + + \section1 qt_ntfs_permission_lookup + + Prior to Qt 6.6, the user had to directly manipulate the global variable + \c qt_ntfs_permission_lookup. However, this was a non-atomic global + variable and as such it was prone to data races. + + The variable \c qt_ntfs_permission_lookup is therefore deprecated since Qt + 6.6. +*/ + +/*! + \fn QNtfsPermissionCheckGuard::QNtfsPermissionCheckGuard() + + Creates a guard and calls the function qEnableNtfsPermissionChecks(). +*/ + +/*! + \fn QNtfsPermissionCheckGuard::~QNtfsPermissionCheckGuard() + + Destroys the guard and calls the function qDisableNtfsPermissionChecks(). +*/ + + +/*! + \fn bool qEnableNtfsPermissionChecks() + \since 6.6 + \threadsafe + \relates QNtfsPermissionCheckGuard + + Enables permission checking on NTFS file systems. Returns \c true if the check + was already enabled before the call to this function, meaning that there + are other users. + + This function is only available on Windows and makes the direct + manipulation of \l qt_ntfs_permission_lookup obsolete. + + This is a low-level function, please consider the RAII class + \l QNtfsPermissionCheckGuard instead. + + \note The thread-safety of this function holds only as long as there are no + concurrent updates to \l qt_ntfs_permission_lookup. +*/ + +/*! + \fn bool qDisableNtfsPermissionChecks() + \since 6.6 + \threadsafe + \relates QNtfsPermissionCheckGuard + + Disables permission checking on NTFS file systems. Returns \c true if the + check is disabled, meaning that there are no more users. + + This function is only available on Windows and makes the direct + manipulation of \l qt_ntfs_permission_lookup obsolete. + + This is a low-level function and must (only) be called to match one earlier + call to qEnableNtfsPermissionChecks(). Please consider the RAII class + \l QNtfsPermissionCheckGuard instead. + + \note The thread-safety of this function holds only as long as there are no + concurrent updates to \l qt_ntfs_permission_lookup. +*/ + +/*! + \fn bool qAreNtfsPermissionChecksEnabled() + \since 6.6 + \threadsafe + \relates QNtfsPermissionCheckGuard + + Checks the status of the permission checks on NTFS file systems. Returns + \c true if the check is enabled. + + This function is only available on Windows and makes the direct + manipulation of \l qt_ntfs_permission_lookup obsolete. + + \note The thread-safety of this function holds only as long as there are no + concurrent updates to \l qt_ntfs_permission_lookup. +*/ + QT_END_NAMESPACE #ifndef QT_NO_QOBJECT diff --git a/src/corelib/io/qfile.h b/src/corelib/io/qfile.h index 839a2b51fee..1d18dd55c03 100644 --- a/src/corelib/io/qfile.h +++ b/src/corelib/io/qfile.h @@ -26,7 +26,7 @@ namespace std { QT_BEGIN_NAMESPACE -#ifdef Q_OS_WIN +#if defined(Q_OS_WIN) || defined(Q_QDOC) #if QT_DEPRECATED_SINCE(6,6) QT_DEPRECATED_VERSION_X_6_6("Use QNtfsPermissionCheckGuard RAII class instead.") diff --git a/src/corelib/io/qfilesystemengine_win.cpp b/src/corelib/io/qfilesystemengine_win.cpp index 3abbfa3536d..67378e2b5db 100644 --- a/src/corelib/io/qfilesystemengine_win.cpp +++ b/src/corelib/io/qfilesystemengine_win.cpp @@ -390,12 +390,6 @@ static QBasicAtomicInt qt_ntfs_permission_lookup_v2 = Q_BASIC_ATOMIC_INITIALIZER QT_WARNING_PUSH QT_WARNING_DISABLE_DEPRECATED -/*! - \internal - - Returns true if the check was previously enabled. -*/ - bool qEnableNtfsPermissionChecks() noexcept { return qt_ntfs_permission_lookup_v2.fetchAndAddRelaxed(1) @@ -403,12 +397,6 @@ QT_IF_DEPRECATED_SINCE(6, 6, /*nothing*/, + qt_ntfs_permission_lookup) != 0; } -/*! - \internal - - Returns true if the check is disabled, i.e. there are no more users. -*/ - bool qDisableNtfsPermissionChecks() noexcept { return qt_ntfs_permission_lookup_v2.fetchAndSubRelaxed(1) @@ -416,12 +404,6 @@ QT_IF_DEPRECATED_SINCE(6, 6, /*nothing*/, + qt_ntfs_permission_lookup) == 1; } -/*! - \internal - - Returns true if the check is enabled. -*/ - bool qAreNtfsPermissionChecksEnabled() noexcept { return qt_ntfs_permission_lookup_v2.loadRelaxed() |