1 /* 2 * Copyright (c) 2022 FuZhou Lockzhiner Electronic Co., Ltd. All rights reserved. 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 Lockzhiner 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 file.h 39 * 40 * @brief Performs operations on a file, including to open, close, write and read a file. 41 * 42 * @since 1.0 43 * @version 1.0 44 */ 45 46 #ifndef LZ_HARDWARE_FILE_H 47 #define LZ_HARDWARE_FILE_H 48 49 #ifdef __cplusplus 50 #if __cplusplus 51 extern "C" { 52 #endif 53 #endif /* __cplusplus */ 54 55 /** 56 * @brief Defines the offset position used by {@link ToyFileSeek} 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 ToyFileSeek} 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 ToyFileSeek} 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 ToyFileOpen} 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 ToyFileOpen} 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 ToyFileOpen} 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 ToyFileOpen} 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 ToyFileOpen} 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 ToyFileOpen} 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 ToyFileOpen} 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 */ 162 int ToyFileOpen(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 */ 172 int ToyFileClose(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 */ 185 int ToyFileRead(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 */ 197 int ToyFileWrite(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 */ 209 int ToyFileDelete(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 */ 220 int ToyFileStat(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 */ 241 int ToyFileSeek(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 */ 254 int ToyFileCopy(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 */ 267 int ToyFileMove(const char* src, const char* dest); 268 269 #ifdef __cplusplus 270 #if __cplusplus 271 } 272 #endif 273 #endif /* __cplusplus */ 274 275 #endif // LZ_HARDWARE_FILE_H 276