1/*
2 * Copyright (c) 2020 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup utils_file
18 * @{
19 *
20 * @brief Performs operations on a file.
21 *
22 * This module allows you to performs file operations such as to open, close,
23 * read, and write a file, and to obtain the file size.
24 * The filing system varies according to the hardware platform.
25 * The following limitations are imposed on a platform that
26 * uses the Serial Peripheral Interface Flash Filing System (SPIFFS):
27 * <ul>
28 *    <li>Multi-level directories are not supported.</li>
29 *    <li>A file name can have a maximum length of 32 bytes (including the end-of-text character in the string).</li>
30 *    <li>A maximum of 32 files can be opened at the same time.</li>
31 * </ul>
32 *
33 * @since 1.0
34 * @version 1.0
35 */
36
37/**
38 * @file utils_file.h
39 *
40 * @brief Performs operations on a file, including to open, close, write, read, and delete a file.
41 *
42 * @since 1.0
43 * @version 1.0
44 */
45
46#ifndef FILE_SYSTEM_API_H
47#define FILE_SYSTEM_API_H
48
49#ifdef __cplusplus
50#if __cplusplus
51extern "C" {
52#endif
53#endif /* __cplusplus */
54
55/**
56 * @brief Defines the offset position used by {@link UtilsFileSeek}
57 * in a file to start offsetting from the file header.
58 *
59 */
60#ifndef SEEK_SET_FS
61#define SEEK_SET_FS  0
62#endif
63
64/**
65 * @brief Defines the offset position used by {@link UtilsFileSeek}
66 * in a file to start offsetting from the current read and write position.
67 *
68 */
69#ifndef SEEK_CUR_FS
70#define SEEK_CUR_FS  1
71#endif
72
73/**
74 * @brief Defines the offset position used by {@link UtilsFileSeek}
75 * in a file to start offsetting from the end of the file.
76 *
77 */
78#ifndef SEEK_END_FS
79#define SEEK_END_FS  2
80#endif
81
82/**
83 * @brief Defines a flag used by{@link UtilsFileOpen} to open a file in read-only mode.
84 *
85 */
86#ifndef O_RDONLY_FS
87#define O_RDONLY_FS  00
88#endif
89
90/**
91 * @brief Defines a flag used by {@link UtilsFileOpen} to open a file in write-only mode.
92 *
93 */
94#ifndef O_WRONLY_FS
95#define O_WRONLY_FS  01
96#endif
97
98/**
99 * @brief Defines a flag used by {@link UtilsFileOpen} to open a file in read-and-write mode.
100 *
101 */
102#ifndef O_RDWR_FS
103#define O_RDWR_FS    02
104#endif
105
106/**
107 * @brief Defines a flag used by {@link UtilsFileOpen} to create a file when the file to open does not exist.
108 *
109 */
110#ifndef O_CREAT_FS
111#define O_CREAT_FS   0100
112#endif
113
114/**
115 * @brief Defines a flag used by {@link UtilsFileOpen} to check whether the file to open exists
116 * when {@link O_CREAT_FS} is already set.
117 *
118 * If the file does not exist, a new file will be created. If the file exists, the file cannot be opened.
119 *
120 */
121#ifndef O_EXCL_FS
122#define O_EXCL_FS    0200
123#endif
124
125/**
126 * @brief Defines a flag used by {@link UtilsFileOpen} to clear the file content
127 * if the file exists and can be opened in write mode.
128 *
129 */
130#ifndef O_TRUNC_FS
131#define O_TRUNC_FS   01000
132#endif
133
134/**
135 * @brief Defines a flag used by {@link UtilsFileOpen} to start reading or writing from the end of a file.
136 *
137 */
138#ifndef O_APPEND_FS
139#define O_APPEND_FS  02000
140#endif
141
142/**
143 * @brief Opens or creates a file.
144 *
145 * @param path Indicates the file to open or create.
146 * @param oflag Indicates the mode of opening a file. The following modes are supported.
147 * oflag | Description
148 * ------------|------------------------------------------------
149 * O_RDONLY_FS | For details, see {@link O_RDONLY_FS}.
150 * O_WRONLY_FS | For details, see {@link O_WRONLY_FS}.
151 * O_RDWR_FS | For details, see {@link O_RDWR_FS}.
152 * O_CREAT_FS | For details, see {@link O_CREAT_FS}.
153 * O_EXCL_FS | For details, see {@link O_EXCL_FS}.
154 * O_TRUNC_FS | For details, see {@link O_TRUNC_FS}.
155 * O_APPEND_FS | For details, see {@link O_APPEND_FS}.
156 * These modes can be used together, with each of them identified by "or".
157 * @param mode Used for function compatibility. This parameter does not take effect in any scenario.
158 * @return Returns the file descriptor if the file is opened or created; returns <b>-1</b> otherwise.
159 * @since 1.0
160 * @version 1.0
161 */
162int UtilsFileOpen(const char* path, int oflag, int mode);
163
164/**
165 * @brief Closes a file with the specified file descriptor.
166 *
167 * @param fd Indicates the file descriptor of the file to close.
168 * @return Returns <b>0</b> if the file is closed; returns <b>-1</b> otherwise.
169 * @since 1.0
170 * @version 1.0
171 */
172int UtilsFileClose(int fd);
173
174/**
175 * @brief Reads a specified length of data from a file with the specified file descriptor
176 * and writes the data into the buffer.
177 *
178 * @param fd Indicates the file descriptor of the file to read.
179 * @param buf Indicates the buffer that stores the read data. This is an output parameter.
180 * @param len Indicates the length of the data to read.
181 * @return Returns the number of bytes of the data if the data is read; returns <b>-1</b> otherwise.
182 * @since 1.0
183 * @version 1.0
184 */
185int UtilsFileRead(int fd, char* buf, unsigned int len);
186
187/**
188 * @brief Writes a specified length of data into a file with the specified file descriptor.
189 *
190 * @param fd Indicates the file descriptor of the file where to write the data.
191 * @param buf Indicates the data to write.
192 * @param len Indicates the length of the data to write.
193 * @return Returns the number of bytes of the data if the data is written; returns <b>-1</b> otherwise.
194 * @since 1.0
195 * @version 1.0
196 */
197int UtilsFileWrite(int fd, const char* buf, unsigned int len);
198
199/**
200 * @brief Deletes a specified file.
201 *
202 * @param path Indicates the file to delete.
203 * @attention If the number of opened files reaches the upper limit (32), close any of them first.
204 * Otherwise, the file cannot be deleted.
205 * @return Returns <b>0</b> if the file is deleted; returns <b>-1</b> otherwise.
206 * @since 1.0
207 * @version 1.0
208 */
209int UtilsFileDelete(const char* path);
210
211/**
212 * @brief Obtains the file size.
213 *
214 * @param path Indicates the file name.
215 * @param fileSize Indicates the file size. This is an output parameter.
216 * @return Returns <b>0</b> if the file size is obtained; returns <b>-1</b> otherwise.
217 * @since 1.0
218 * @version 1.0
219 */
220int UtilsFileStat(const char* path, unsigned int* fileSize);
221
222/**
223 * @brief Adjusts the read and write position offset in a file.
224 *
225 * @param fd Indicates the file descriptor of the file where the read and write position offset needs adjustment.
226 * @param offset Indicates the offset of the read and write position based on the <b>whence</b> parameter.
227 * The value can be negative if the value of <b>whence</b> is <b>SEEK_CUR_FS</b> or <b>SEEK_END_FS</b>.
228 * @param whence Indicates the start position of the offset. The following start positions are supported.
229 * whence | Description
230 * ------------|------------------------------------------------
231 * SEEK_SET_FS | Adjusts the read and write position to the file header.
232 *      ^      | Then adds the offset after the read and write position.
233 * SEEK_CUR_FS | Adds the offset after the current read and write position.
234 * SEEK_END_FS | Adjusts the read and write position to the end of the file.
235 *      ^      | Then adds the offset after the read and write position.
236 *
237 * @return Returns the current read and write position if the operation is successful; returns <b>-1</b> otherwise.
238 * @since 1.0
239 * @version 1.0
240 */
241int UtilsFileSeek(int fd, int offset, unsigned int whence);
242
243/**
244 * @brief Copies the source file to a target file.
245 *
246 * @param src Indicates the source file to copy.
247 * @param dest Indicates the target file.
248 * @attention If the number of opened files reaches the upper limit (32), close any two files first.
249 * Otherwise, the file cannot be copied.
250 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise.
251 * @since 1.0
252 * @version 1.0
253 */
254int UtilsFileCopy(const char* src, const char* dest);
255
256/**
257 * @brief Moves the source file into a target file.
258 *
259 * @param src Indicates the source file.
260 * @param dest Indicates the target file.
261 * @attention If the number of opened files reaches the upper limit (32), close any two files first.
262 * Otherwise, the file cannot be moved.
263 * @return Returns <b>0</b> if the operation is successful; returns <b>-1</b> otherwise.
264 * @since 1.0
265 * @version 1.0
266 */
267int UtilsFileMove(const char* src, const char* dest);
268
269#ifdef __cplusplus
270#if __cplusplus
271}
272#endif
273#endif /* __cplusplus */
274
275#endif  // FILE_SYSTEM_API_H
276/** @} */