include/QtCore/qfile.h

0001 // Copyright (C) 2020 The Qt Company Ltd.
0002 // Copyright (C) 2016 Intel Corporation.
0003 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0004
0005 #ifndef QFILE_H
0006 #define QFILE_H
0007
0008 #include <QtCore/qfiledevice.h>
0009 #include <QtCore/qstring.h>
0010 #include <stdio.h>
0011
0012 #if QT_CONFIG(cxx17_filesystem)
0013 #include <filesystem>
0014 #elif defined(Q_QDOC)
0015 namespace std {
0016     namespace filesystem {
0017         class path {
0018         };
0019     };
0020 };
0021 #endif
0022
0023 #ifdef open
0024 #error qfile.h must be included before any header file that defines open
0025 #endif
0026
0027 QT_BEGIN_NAMESPACE
0028
0029 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0030
0031 #if QT_DEPRECATED_SINCE(6,6)
0032 QT_DEPRECATED_VERSION_X_6_6("Use QNtfsPermissionCheckGuard RAII class instead.")
0033 Q_CORE_EXPORT extern int qt_ntfs_permission_lookup;      // defined in qfilesystemengine_win.cpp
0034 #endif
0035
0036 Q_CORE_EXPORT bool qEnableNtfsPermissionChecks() noexcept;
0037 Q_CORE_EXPORT bool qDisableNtfsPermissionChecks() noexcept;
0038 Q_CORE_EXPORT bool qAreNtfsPermissionChecksEnabled() noexcept;
0039
0040 class QNtfsPermissionCheckGuard
0041 {
0042     Q_DISABLE_COPY_MOVE(QNtfsPermissionCheckGuard)
0043 public:
0044     Q_NODISCARD_CTOR
0045     QNtfsPermissionCheckGuard()
0046     {
0047         qEnableNtfsPermissionChecks();
0048     }
0049
0050     ~QNtfsPermissionCheckGuard()
0051     {
0052         qDisableNtfsPermissionChecks();
0053     }
0054 };
0055 #endif // Q_OS_WIN
0056
0057 #if QT_CONFIG(cxx17_filesystem)
0058 namespace QtPrivate {
0059 inline QString fromFilesystemPath(const std::filesystem::path &path)
0060 {
0061 #ifdef Q_OS_WIN
0062     return QString::fromStdWString(path.native());
0063 #else
0064     return QString::fromStdString(path.native());
0065 #endif
0066 }
0067
0068 inline std::filesystem::path toFilesystemPath(const QString &path)
0069 {
0070     return std::filesystem::path(reinterpret_cast<const char16_t *>(path.cbegin()),
0071                                  reinterpret_cast<const char16_t *>(path.cend()));
0072 }
0073
0074 // Both std::filesystem::path and QString (without QT_NO_CAST_FROM_ASCII) can be implicitly
0075 // constructed from string literals so we force the std::fs::path parameter to only
0076 // accept std::fs::path with no implicit conversions.
0077 template<typename T>
0078 using ForceFilesystemPath = typename std::enable_if_t<std::is_same_v<std::filesystem::path, T>, int>;
0079 }
0080 #endif // QT_CONFIG(cxx17_filesystem)
0081
0082 class QTemporaryFile;
0083 class QFilePrivate;
0084
0085 // ### Qt 7: remove this, and make constructors always explicit.
0086 #if (QT_VERSION >= QT_VERSION_CHECK(6, 9, 0)) || defined(QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH)
0087 #  define QFILE_MAYBE_EXPLICIT explicit
0088 #else
0089 #  define QFILE_MAYBE_EXPLICIT Q_IMPLICIT
0090 #endif
0091
0092 class Q_CORE_EXPORT QFile : public QFileDevice
0093 {
0094 #ifndef QT_NO_QOBJECT
0095     Q_OBJECT
0096 #endif
0097     Q_DECLARE_PRIVATE(QFile)
0098
0099 public:
0100     QFile();
0101     QFILE_MAYBE_EXPLICIT QFile(const QString &name);
0102 #ifdef Q_QDOC
0103     QFILE_MAYBE_EXPLICIT QFile(const std::filesystem::path &name);
0104 #elif QT_CONFIG(cxx17_filesystem)
0105     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0106     QFILE_MAYBE_EXPLICIT QFile(const T &name) : QFile(QtPrivate::fromFilesystemPath(name))
0107     {
0108     }
0109 #endif // QT_CONFIG(cxx17_filesystem)
0110
0111 #ifndef QT_NO_QOBJECT
0112     explicit QFile(QObject *parent);
0113     QFile(const QString &name, QObject *parent);
0114
0115 #ifdef Q_QDOC
0116     QFile(const std::filesystem::path &path, QObject *parent);
0117 #elif QT_CONFIG(cxx17_filesystem)
0118     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0119     QFile(const T &path, QObject *parent) : QFile(QtPrivate::fromFilesystemPath(path), parent)
0120     {
0121     }
0122 #endif // QT_CONFIG(cxx17_filesystem)
0123 #endif // !QT_NO_QOBJECT
0124     ~QFile();
0125
0126     QString fileName() const override;
0127 #if QT_CONFIG(cxx17_filesystem) || defined(Q_QDOC)
0128     std::filesystem::path filesystemFileName() const
0129     { return QtPrivate::toFilesystemPath(fileName()); }
0130 #endif
0131     void setFileName(const QString &name);
0132 #ifdef Q_QDOC
0133     void setFileName(const std::filesystem::path &name);
0134 #elif QT_CONFIG(cxx17_filesystem)
0135     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0136     void setFileName(const T &name)
0137     {
0138         setFileName(QtPrivate::fromFilesystemPath(name));
0139     }
0140 #endif // QT_CONFIG(cxx17_filesystem)
0141
0142 #if defined(Q_OS_DARWIN)
0143     // Mac always expects filenames in UTF-8... and decomposed...
0144     static inline QByteArray encodeName(const QString &fileName)
0145     {
0146         return fileName.normalized(QString::NormalizationForm_D).toUtf8();
0147     }
0148     static QString decodeName(const QByteArray &localFileName)
0149     {
0150         // note: duplicated in qglobal.cpp (qEnvironmentVariable)
0151         return QString::fromUtf8(localFileName).normalized(QString::NormalizationForm_C);
0152     }
0153     static inline QString decodeName(const char *localFileName)
0154     {
0155         return QString::fromUtf8(localFileName).normalized(QString::NormalizationForm_C);
0156     }
0157 #else
0158     static inline QByteArray encodeName(const QString &fileName)
0159     {
0160         return fileName.toLocal8Bit();
0161     }
0162     static QString decodeName(const QByteArray &localFileName)
0163     {
0164         return QString::fromLocal8Bit(localFileName);
0165     }
0166     static inline QString decodeName(const char *localFileName)
0167     {
0168         return QString::fromLocal8Bit(localFileName);
0169     }
0170 #endif
0171
0172     bool exists() const;
0173     static bool exists(const QString &fileName);
0174 #ifdef Q_QDOC
0175     static bool exists(const std::filesystem::path &fileName);
0176 #elif QT_CONFIG(cxx17_filesystem)
0177     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0178     static bool exists(const T &fileName)
0179     {
0180         return exists(QtPrivate::fromFilesystemPath(fileName));
0181     }
0182 #endif // QT_CONFIG(cxx17_filesystem)
0183
0184     QString symLinkTarget() const;
0185     static QString symLinkTarget(const QString &fileName);
0186 #ifdef Q_QDOC
0187     std::filesystem::path filesystemSymLinkTarget() const;
0188     static std::filesystem::path filesystemSymLinkTarget(const std::filesystem::path &fileName);
0189 #elif QT_CONFIG(cxx17_filesystem)
0190     std::filesystem::path filesystemSymLinkTarget() const
0191     {
0192         return QtPrivate::toFilesystemPath(symLinkTarget());
0193     }
0194     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0195     static std::filesystem::path filesystemSymLinkTarget(const T &fileName)
0196     {
0197         return QtPrivate::toFilesystemPath(symLinkTarget(QtPrivate::fromFilesystemPath(fileName)));
0198     }
0199 #endif // QT_CONFIG(cxx17_filesystem)
0200
0201     bool remove();
0202     static bool remove(const QString &fileName);
0203 #ifdef Q_QDOC
0204     static bool remove(const std::filesystem::path &fileName);
0205 #elif QT_CONFIG(cxx17_filesystem)
0206     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0207     static bool remove(const T &fileName)
0208     {
0209         return remove(QtPrivate::fromFilesystemPath(fileName));
0210     }
0211 #endif // QT_CONFIG(cxx17_filesystem)
0212
0213     static bool supportsMoveToTrash() Q_DECL_PURE_FUNCTION;
0214     bool moveToTrash();
0215     static bool moveToTrash(const QString &fileName, QString *pathInTrash = nullptr);
0216 #ifdef Q_QDOC
0217     static bool moveToTrash(const std::filesystem::path &fileName, QString *pathInTrash = nullptr);
0218 #elif QT_CONFIG(cxx17_filesystem)
0219     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0220     static bool moveToTrash(const T &fileName, QString *pathInTrash = nullptr)
0221     {
0222         return moveToTrash(QtPrivate::fromFilesystemPath(fileName), pathInTrash);
0223     }
0224 #endif // QT_CONFIG(cxx17_filesystem)
0225
0226     bool rename(const QString &newName);
0227     static bool rename(const QString &oldName, const QString &newName);
0228 #ifdef Q_QDOC
0229     bool rename(const std::filesystem::path &newName);
0230     static bool rename(const std::filesystem::path &oldName,
0231                        const std::filesystem::path &newName);
0232 #elif QT_CONFIG(cxx17_filesystem)
0233     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0234     bool rename(const T &newName)
0235     {
0236         return rename(QtPrivate::fromFilesystemPath(newName));
0237     }
0238     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0239     static bool rename(const T &oldName, const T &newName)
0240     {
0241         return rename(QtPrivate::fromFilesystemPath(oldName),
0242                       QtPrivate::fromFilesystemPath(newName));
0243     }
0244 #endif // QT_CONFIG(cxx17_filesystem)
0245
0246     bool link(const QString &newName);
0247     static bool link(const QString &fileName, const QString &newName);
0248 #ifdef Q_QDOC
0249     bool link(const std::filesystem::path &newName);
0250     static bool link(const std::filesystem::path &fileName,
0251                      const std::filesystem::path &newName);
0252 #elif QT_CONFIG(cxx17_filesystem)
0253     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0254     bool link(const T &newName)
0255     {
0256         return link(QtPrivate::fromFilesystemPath(newName));
0257     }
0258     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0259     static bool link(const T &fileName, const T &newName)
0260     {
0261         return link(QtPrivate::fromFilesystemPath(fileName),
0262                     QtPrivate::fromFilesystemPath(newName));
0263     }
0264 #endif // QT_CONFIG(cxx17_filesystem)
0265
0266     bool copy(const QString &newName);
0267     static bool copy(const QString &fileName, const QString &newName);
0268 #ifdef Q_QDOC
0269     bool copy(const std::filesystem::path &newName);
0270     static bool copy(const std::filesystem::path &fileName,
0271                      const std::filesystem::path &newName);
0272 #elif QT_CONFIG(cxx17_filesystem)
0273     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0274     bool copy(const T &newName)
0275     {
0276         return copy(QtPrivate::fromFilesystemPath(newName));
0277     }
0278     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0279     static bool copy(const T &fileName, const T &newName)
0280     {
0281         return copy(QtPrivate::fromFilesystemPath(fileName),
0282                     QtPrivate::fromFilesystemPath(newName));
0283     }
0284 #endif // QT_CONFIG(cxx17_filesystem)
0285
0286     QFILE_MAYBE_NODISCARD bool open(OpenMode flags) override;
0287     QFILE_MAYBE_NODISCARD bool open(OpenMode flags, Permissions permissions);
0288     QFILE_MAYBE_NODISCARD bool open(FILE *f, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle);
0289     QFILE_MAYBE_NODISCARD bool open(int fd, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle);
0290
0291     qint64 size() const override;
0292
0293     bool resize(qint64 sz) override;
0294     static bool resize(const QString &filename, qint64 sz);
0295
0296     Permissions permissions() const override;
0297     static Permissions permissions(const QString &filename);
0298     bool setPermissions(Permissions permissionSpec) override;
0299     static bool setPermissions(const QString &filename, Permissions permissionSpec);
0300 #ifdef Q_QDOC
0301     static Permissions permissions(const std::filesystem::path &filename);
0302     static bool setPermissions(const std::filesystem::path &filename, Permissions permissionSpec);
0303 #elif QT_CONFIG(cxx17_filesystem)
0304     template<typename T,  QtPrivate::ForceFilesystemPath<T> = 0>
0305     static Permissions permissions(const T &filename)
0306     {
0307         return permissions(QtPrivate::fromFilesystemPath(filename));
0308     }
0309     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0310     static bool setPermissions(const T &filename, Permissions permissionSpec)
0311     {
0312         return setPermissions(QtPrivate::fromFilesystemPath(filename), permissionSpec);
0313     }
0314 #endif // QT_CONFIG(cxx17_filesystem)
0315
0316 protected:
0317 #ifdef QT_NO_QOBJECT
0318     QFile(QFilePrivate &dd);
0319 #else
0320     QFile(QFilePrivate &dd, QObject *parent = nullptr);
0321 #endif
0322
0323 private:
0324     friend class QTemporaryFile;
0325     Q_DISABLE_COPY(QFile)
0326 };
0327
0328 QT_END_NAMESPACE
0329
0330 #endif // QFILE_H