Debian Codegraph @

docs/filesystem/dcapfile.zh_CN.dox

raw
1 /*!
2 @~chinese
3 @ingroup dfilesystem
4 @file include/filesystem/dcapfile.h
5
6 @class Dtk::Core::DCapFile
7 @brief 对于文件操作的安全封装, 提供了带有安全管控的文件读取, 相关漏洞见[CWE_22](https://cwe.mitre.org/data/definitions/22.html)
8
9 @fn explicit Dtk::Core::DCapFile(QObject *parent = nullptr)
10 @brief 默认构造函数, 创建一个文件默认文件对象
11
12 @fn Dtk::Core::DCapFile::DCapFile(const QString &name, QObject *parent)
13 @brief 重载的构造函数, 接受传入一个文件名, 并创建一个文件对象
14 @note 调用此构造函数相当于调用默认构造函数+`DCapFile::setFileName()`
15
16 @fn void Dtk::Core::DCapFile::setFileName(const QString &name)
17 @brief 传入需要操作的文件名
18
19 @fn bool Dtk::Core::DCapFile::exists() const
20 @brief 文件是否存在
21 @note 此处的存在指当前由setFileName() 指定的文件或者是在构造时指定的文件是否可读可写
22 @note 需要在构造时或者手动指定了文件名才可以使用此函数, 否则请调用其重载的函数
23
24 @fn static bool Dtk::Core::DCapFile::exists(const QString &fileName)
25 @brief 文件是否存在
26 @param[in] fileName 文件名
27 @note 此处的存在指的是此函数的传入的文件名指向的文件是否可读可写
28
29 @fn QString Dtk::Core::DCapFile::readLink() const
30 @brief 读取软连接, 如果软连接指向的文件不允许读写, 则返回空字符串
31 @note 此方法在Qt版本>=5.13后**废弃**
32 @return 返回软连接指向的文件或者目录的绝对路径
33 @note 需要在构造时或者手动指定了文件名才可以使用此函数, 否则请调用其重载的函数
34 @sa [readLink](https://doc.qt.io/qt-5/qfile-obsolete.html#readLink-1)
35
36 @fn QString Dtk::Core::DCapFile::symLinkTarget() const
37 @brief 这是一个重载函数<br>
38 返回符号链接, 或Windows上的快捷方式指向的文件或目录的绝对路径, 如果该对象不是符号链接, 则返回一个空字符串。
39
40 @fn bool Dtk::Core::DCapFile::remove()
41 @brief 如果文件存在则删除文件
42 @note 此处的存在指当前由setFileName() 指定的文件或者是在构造时指定的文件是否可读可写
43 @note 需要在构造时或者手动指定了文件名才可以使用此函数, 否则请调用其重载的函数
44 @note 文件需要在删除前被关闭
45
46 @fn static bool Dtk::Core::DCapFile::remove(const QString &fileName)
47 @brief 如果文件存在则删除文件
48 @param[in] fileName 文件名
49 @note 此处的存在指的是此函数的传入的文件名指向的文件是否可读可写
50 @note 文件需要在删除前被关闭
51 @sa DCapFile::remove()
52
53 @fn bool Dtk::Core::DCapFile::moveToTrash()
54 @brief 如果文件存在则将文件移动至默认回收站(垃圾桶)
55 @note 此处的存在指当前由setFileName() 指定的文件或者是在构造时指定的文件是否可读可写
56 @note 需要在构造时或者手动指定了文件名才可以使用此函数, 否则请调用其重载的函数
57 @note 此方法仅在Qt版本>=5.15.0后可用
58
59 @fn bool Dtk::Core::DCapFile::moveToTrash(const QString &fileName, QString *pathInTrash)
60 @brief 如果传入文件名对应文件存在则将文件移动至指定回收站(垃圾桶)
61 @note 此处的存在指的是此函数的传入的文件名指向的文件是否可读可写
62 @note 此方法仅在Qt版本>=5.15.0后可用
63 @param[in] fileName 文件名
64 @param[in] pathInTrash 回收站路径
65
66 @fn bool Dtk::Core::DCapFile::rename(const QString &newName)
67 @brief 如果文件名存在则重命名文件
68 @param[in] newName 新文件名
69 @note 需要在构造时或者手动指定了文件名才可以使用此函数, 否则请调用其重载的函数
70
71 @fn static bool Dtk::Core::DCapFile::rename(const QString &oldName, const QString &newName)
72 @brief 如果文件名存在则重命名文件
73 @param[in] oldName 旧文件名
74 @param[in] newName 新文件名
75
76 @fn bool Dtk::Core::DCapFile::link(const QString &newName)
77 @brief 创建一个名为newName的链接
78 @details 该链接指向当前由`setFileName()`指定的文件或者是在构造时指定的文件。链接是什么取决于底层文件系统(无论是Windows上的快捷方式还是Unix上的符号链接)。如果成功, 则返回ture;否则返回false
79 @note 如果是windows系统的newName参数必须有`.lnk`合法后缀才可用
80 @param[in] newName 新文件名
81
82 @fn static bool Dtk::Core::DCapFile::link(const QString &oldname, const QString &newName)
83 @brief 该函数是重载`DCapFile::link()`区别是需要手动传入原始文件名
84 @sa DCapFile::link(const QString &newName)
85
86 @fn bool Dtk::Core::DCapFile::copy(const QString &newName)
87 @brief `setFileName()`指定的文件或者是在构造时指定的文件复制一份, 名为newName<br>
88 如果成功, 则返回ture;否则返回false
89 @note 确保文件在复制之前是关闭的
90 @note 如果复制的文件是一个符号链接(symlink), 它所指的文件被复制, 而不是链接本身。除了权限
91 会被复制外, 其他的文件元数据都不会被复制。
92 @note 如果一个名称为 newName 的文件已经存在, `copy()`将会返回true但是并不会覆盖它
93
94 @fn static bool Dtk::Core::DCapFile::copy(const QString &fileName, const QString &newName)
95 @brief 该函数是重载`DCapFile::copy(const QString &newName)`区别是需要手动传入原始文件名
96 @sa DCapFile::copy(const QString &newName)
97
98 @fn bool Dtk::Core::DCapFile::open(OpenMode flags)
99 @brief 使用OpenMode模式打开文件, 如果成功返回true;否则返回false<br>
100 @details 模式如下:<br>
101 NotOpen = 0x0000, <br>
102 ReadOnly = 0x0001, <br>
103 WriteOnly = 0x0002, <br>
104 ReadWrite = ReadOnly | WriteOnly, <br>
105 Append = 0x0004, <br>
106 Truncate = 0x0008, <br>
107 Text = 0x0010, <br>
108 Unbuffered = 0x0020, <br>
109 NewOnly = 0x0040, <br>
110 ExistingOnly = 0x0080<br>
111 @note 在只写或读写模式下, 如果相关文件不存在, 该函数将在打开文件之前尝试创建一个新文件
112
113 @fn bool Dtk::Core::DCapFile::resize(qint64 sz)
114 @brief 设置文件大小sz(以字节为单位)。如果调整大小成功, 则返回true;否则为false。如果sz大于当前文件, 则新字节将设置为 0;如果sz较小, 则文件将被简单地截断
115 @note 如果文件不存在, 此函数可能会无效
116
117 @fn static bool Dtk::Core::DCapFile::resize(const QString &filename, qint64 sz)
118 @brief 该函数是重载`DCapFile::resize(qint64 sz)`区别是手动指定文件名
119 @sa DCapFile::resize(qint64 sz)
120
121 */
122
123 /*!
124 @class Dtk::Core::DCapFile
125 @brief 对于文件夹操作的封装
126
127 @fn Dtk::Core::DCapDir::DCapDir(const DCapDir &)
128 @brief 拷贝构造函数 构造一个DCapDir对象, 该对象是目录目录的DCapDir对象的副本
129
130 @fn Dtk::Core::DCapDir::DCapDir(const QString &path = QString())
131 @brief 构造指向给定目录路径的DCapDir。如果 path 为空, 则使用程序的工作目录`.`
132
133 @fn Dtk::Core::DCapDir::DCapDir(const QString &path,
134 const QString &nameFilter, SortFlags sort = SortFlags(Name | IgnoreCase),
135 Filters filter = AllEntries)
136 @brief 构造具有路径路径的DCapDir对象
137 @details 该 DCapDir 使用nameFilter按名称筛选其条目, 并使用筛选器 按属性筛选其条目。它还使用排序对名称进行排序。<br>
138 默认名称筛选器是一个空字符串, 它不排除任何内容;默认筛选器是“所有条目”, 这也意味着不排除任何内容。默认排序为“名称|忽略大小写, 即按名称排序, 不区分大小写。
139 如果path为空字符串, DCapDir 将使用 “.”(当前目录)<br>
140 如果nameFilter为空字符串, DCapDir 将使用名称筛选器“*”(所有文件)
141 @note 路径不需要存在
142
143 @fn void Dtk::Core::DCapDir::setPath(const QString &path)
144 @brief 将目录的路径设置为path。该路径被清除了多余的"."、"... "和多个分隔符。没有检查这个路径的
145 目录是否真的存在;<br>
146 路径可以是绝对路径也可以是相对路径, 绝对路径以目录分隔符"/"开始(在Windows下可以选择在前面加一个驱动器号, 例如: C:\)<br>
147 相对路径以目录名开始, 并指定一个相对于当前目录的路径。一个绝对路径的例子是字符串"/etc/apt", 一个相对路径例子是 "src/1/"<br>
148
149 @fn bool Dtk::Core::DCapDir::cd(const QString &dirName)
150 @brief 将DCapDir的目录更改为dirName。
151 如果新目录存在, 则返回true;否则返回false
152 请注意, 如果新目录不存在, 则不执行逻辑`cd()`操作
153
154 @fn QStringList Dtk::Core::DCapDir::entryList(Filters filters = NoFilter, SortFlags sort = NoSort) const
155 @brief 返回目录中所有文件和目录的名称列表
156 @details 这些名称根据以前使用`setNameFilters()` 和`setFilter()`
157 设置的名称和属性筛选器排序, 并根据使用`setSorting() 设置的标志进行排序。<br>
158 可以使用过滤器和排序参数覆盖属性过滤器和排序规范。
159 如果目录不可读、不存在或与规范不匹配, 则返回空列表。
160
161 @fn QString Dtk::Core::DCapDir::entryList(const QStringList &nameFilters, Filters filters = NoFilter,
162 SortFlags sort = NoSort)
163 @brief 重载函数, 返回目录中所有文件和目录的名称列表
164 @sa entryList(Filters filters = NoFilter, SortFlags sort = NoSort)
165
166 @fn bool Dtk::Core::DCapDir::mkdir(const QString &dirName) const
167 @brief 创建文件夹
168
169 @fn bool Dtk::Core::DCapDir::rmdir(const QString &dirName) const
170 @brief 移除文件夹
171
172 @fn bool Dtk::Core::DCapDir::mkpath(const QString &dirPath)
173 @brief 创建目录
174
175 @fn bool Dtk::Core::DCapDir::rmpath(const QString &dirPath)
176 @brief 移除目录
177
178 @fn bool Dtk::Core::DCapDir::exists() const
179 @brief 文件夹是否存在(如果找到同名文件, 此函数将返回 false)
180
181 @fn bool Dtk::Core::DCapDir::exists(const QString &name) const
182 @brief 指定文件夹是否存在(如果找到同名文件, 此函数将返回 false)
183
184 @fn bool Dtk::Core::DCapDir::remove(const QString &fileName)
185 @brief 移除文件夹
186
187 @fn bool Dtk::Core::DCapDir::rename(const QString &oldName, const QString &newName)
188 @brief 重命名文件夹
189 @param[in] oldName 旧文件夹名
190 @param[in] newName 新文件夹名
191
192 */