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     bool moveToTrash();
0214     static bool moveToTrash(const QString &fileName, QString *pathInTrash = nullptr);
0215 #ifdef Q_QDOC
0216     static bool moveToTrash(const std::filesystem::path &fileName, QString *pathInTrash = nullptr);
0217 #elif QT_CONFIG(cxx17_filesystem)
0218     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0219     static bool moveToTrash(const T &fileName, QString *pathInTrash = nullptr)
0220     {
0221         return moveToTrash(QtPrivate::fromFilesystemPath(fileName), pathInTrash);
0222     }
0223 #endif // QT_CONFIG(cxx17_filesystem)
0224
0225     bool rename(const QString &newName);
0226     static bool rename(const QString &oldName, const QString &newName);
0227 #ifdef Q_QDOC
0228     bool rename(const std::filesystem::path &newName);
0229     static bool rename(const std::filesystem::path &oldName,
0230                        const std::filesystem::path &newName);
0231 #elif QT_CONFIG(cxx17_filesystem)
0232     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0233     bool rename(const T &newName)
0234     {
0235         return rename(QtPrivate::fromFilesystemPath(newName));
0236     }
0237     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0238     static bool rename(const T &oldName, const T &newName)
0239     {
0240         return rename(QtPrivate::fromFilesystemPath(oldName),
0241                       QtPrivate::fromFilesystemPath(newName));
0242     }
0243 #endif // QT_CONFIG(cxx17_filesystem)
0244
0245     bool link(const QString &newName);
0246     static bool link(const QString &fileName, const QString &newName);
0247 #ifdef Q_QDOC
0248     bool link(const std::filesystem::path &newName);
0249     static bool link(const std::filesystem::path &fileName,
0250                      const std::filesystem::path &newName);
0251 #elif QT_CONFIG(cxx17_filesystem)
0252     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0253     bool link(const T &newName)
0254     {
0255         return link(QtPrivate::fromFilesystemPath(newName));
0256     }
0257     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0258     static bool link(const T &fileName, const T &newName)
0259     {
0260         return link(QtPrivate::fromFilesystemPath(fileName),
0261                     QtPrivate::fromFilesystemPath(newName));
0262     }
0263 #endif // QT_CONFIG(cxx17_filesystem)
0264
0265     bool copy(const QString &newName);
0266     static bool copy(const QString &fileName, const QString &newName);
0267 #ifdef Q_QDOC
0268     bool copy(const std::filesystem::path &newName);
0269     static bool copy(const std::filesystem::path &fileName,
0270                      const std::filesystem::path &newName);
0271 #elif QT_CONFIG(cxx17_filesystem)
0272     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0273     bool copy(const T &newName)
0274     {
0275         return copy(QtPrivate::fromFilesystemPath(newName));
0276     }
0277     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0278     static bool copy(const T &fileName, const T &newName)
0279     {
0280         return copy(QtPrivate::fromFilesystemPath(fileName),
0281                     QtPrivate::fromFilesystemPath(newName));
0282     }
0283 #endif // QT_CONFIG(cxx17_filesystem)
0284
0285     bool open(OpenMode flags) override;
0286     bool open(OpenMode flags, Permissions permissions);
0287     bool open(FILE *f, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle);
0288     bool open(int fd, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle);
0289
0290     qint64 size() const override;
0291
0292     bool resize(qint64 sz) override;
0293     static bool resize(const QString &filename, qint64 sz);
0294
0295     Permissions permissions() const override;
0296     static Permissions permissions(const QString &filename);
0297     bool setPermissions(Permissions permissionSpec) override;
0298     static bool setPermissions(const QString &filename, Permissions permissionSpec);
0299 #ifdef Q_QDOC
0300     static Permissions permissions(const std::filesystem::path &filename);
0301     static bool setPermissions(const std::filesystem::path &filename, Permissions permissionSpec);
0302 #elif QT_CONFIG(cxx17_filesystem)
0303     template<typename T,  QtPrivate::ForceFilesystemPath<T> = 0>
0304     static Permissions permissions(const T &filename)
0305     {
0306         return permissions(QtPrivate::fromFilesystemPath(filename));
0307     }
0308     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0309     static bool setPermissions(const T &filename, Permissions permissionSpec)
0310     {
0311         return setPermissions(QtPrivate::fromFilesystemPath(filename), permissionSpec);
0312     }
0313 #endif // QT_CONFIG(cxx17_filesystem)
0314
0315 protected:
0316 #ifdef QT_NO_QOBJECT
0317     QFile(QFilePrivate &dd);
0318 #else
0319     QFile(QFilePrivate &dd, QObject *parent = nullptr);
0320 #endif
0321
0322 private:
0323     friend class QTemporaryFile;
0324     Q_DISABLE_COPY(QFile)
0325 };
0326
0327 QT_END_NAMESPACE
0328
0329 #endif // QFILE_H