/* * Copyright (c) 2020 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @addtogroup utils_file * @{ * * @brief Performs operations on a file. * * This module allows you to performs file operations such as to open, close, * read, and write a file, and to obtain the file size. * The filing system varies according to the hardware platform. * The following limitations are imposed on a platform that * uses the Serial Peripheral Interface Flash Filing System (SPIFFS): * * * @since 1.0 * @version 1.0 */ /** * @file utils_file.h * * @brief Performs operations on a file, including to open, close, write, read, and delete a file. * * @since 1.0 * @version 1.0 */ #ifndef FILE_SYSTEM_API_H #define FILE_SYSTEM_API_H #ifdef __cplusplus #if __cplusplus extern "C" { #endif #endif /* __cplusplus */ /** * @brief Defines the offset position used by {@link UtilsFileSeek} * in a file to start offsetting from the file header. * */ #ifndef SEEK_SET_FS #define SEEK_SET_FS 0 #endif /** * @brief Defines the offset position used by {@link UtilsFileSeek} * in a file to start offsetting from the current read and write position. * */ #ifndef SEEK_CUR_FS #define SEEK_CUR_FS 1 #endif /** * @brief Defines the offset position used by {@link UtilsFileSeek} * in a file to start offsetting from the end of the file. * */ #ifndef SEEK_END_FS #define SEEK_END_FS 2 #endif /** * @brief Defines a flag used by{@link UtilsFileOpen} to open a file in read-only mode. * */ #ifndef O_RDONLY_FS #define O_RDONLY_FS 00 #endif /** * @brief Defines a flag used by {@link UtilsFileOpen} to open a file in write-only mode. * */ #ifndef O_WRONLY_FS #define O_WRONLY_FS 01 #endif /** * @brief Defines a flag used by {@link UtilsFileOpen} to open a file in read-and-write mode. * */ #ifndef O_RDWR_FS #define O_RDWR_FS 02 #endif /** * @brief Defines a flag used by {@link UtilsFileOpen} to create a file when the file to open does not exist. * */ #ifndef O_CREAT_FS #define O_CREAT_FS 0100 #endif /** * @brief Defines a flag used by {@link UtilsFileOpen} to check whether the file to open exists * when {@link O_CREAT_FS} is already set. * * If the file does not exist, a new file will be created. If the file exists, the file cannot be opened. * */ #ifndef O_EXCL_FS #define O_EXCL_FS 0200 #endif /** * @brief Defines a flag used by {@link UtilsFileOpen} to clear the file content * if the file exists and can be opened in write mode. * */ #ifndef O_TRUNC_FS #define O_TRUNC_FS 01000 #endif /** * @brief Defines a flag used by {@link UtilsFileOpen} to start reading or writing from the end of a file. * */ #ifndef O_APPEND_FS #define O_APPEND_FS 02000 #endif /** * @brief Opens or creates a file. * * @param path Indicates the file to open or create. * @param oflag Indicates the mode of opening a file. The following modes are supported. * oflag | Description * ------------|------------------------------------------------ * O_RDONLY_FS | For details, see {@link O_RDONLY_FS}. * O_WRONLY_FS | For details, see {@link O_WRONLY_FS}. * O_RDWR_FS | For details, see {@link O_RDWR_FS}. * O_CREAT_FS | For details, see {@link O_CREAT_FS}. * O_EXCL_FS | For details, see {@link O_EXCL_FS}. * O_TRUNC_FS | For details, see {@link O_TRUNC_FS}. * O_APPEND_FS | For details, see {@link O_APPEND_FS}. * These modes can be used together, with each of them identified by "or". * @param mode Used for function compatibility. This parameter does not take effect in any scenario. * @return Returns the file descriptor if the file is opened or created; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileOpen(const char* path, int oflag, int mode); /** * @brief Closes a file with the specified file descriptor. * * @param fd Indicates the file descriptor of the file to close. * @return Returns 0 if the file is closed; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileClose(int fd); /** * @brief Reads a specified length of data from a file with the specified file descriptor * and writes the data into the buffer. * * @param fd Indicates the file descriptor of the file to read. * @param buf Indicates the buffer that stores the read data. This is an output parameter. * @param len Indicates the length of the data to read. * @return Returns the number of bytes of the data if the data is read; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileRead(int fd, char* buf, unsigned int len); /** * @brief Writes a specified length of data into a file with the specified file descriptor. * * @param fd Indicates the file descriptor of the file where to write the data. * @param buf Indicates the data to write. * @param len Indicates the length of the data to write. * @return Returns the number of bytes of the data if the data is written; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileWrite(int fd, const char* buf, unsigned int len); /** * @brief Deletes a specified file. * * @param path Indicates the file to delete. * @attention If the number of opened files reaches the upper limit (32), close any of them first. * Otherwise, the file cannot be deleted. * @return Returns 0 if the file is deleted; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileDelete(const char* path); /** * @brief Obtains the file size. * * @param path Indicates the file name. * @param fileSize Indicates the file size. This is an output parameter. * @return Returns 0 if the file size is obtained; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileStat(const char* path, unsigned int* fileSize); /** * @brief Adjusts the read and write position offset in a file. * * @param fd Indicates the file descriptor of the file where the read and write position offset needs adjustment. * @param offset Indicates the offset of the read and write position based on the whence parameter. * The value can be negative if the value of whence is SEEK_CUR_FS or SEEK_END_FS. * @param whence Indicates the start position of the offset. The following start positions are supported. * whence | Description * ------------|------------------------------------------------ * SEEK_SET_FS | Adjusts the read and write position to the file header. * ^ | Then adds the offset after the read and write position. * SEEK_CUR_FS | Adds the offset after the current read and write position. * SEEK_END_FS | Adjusts the read and write position to the end of the file. * ^ | Then adds the offset after the read and write position. * * @return Returns the current read and write position if the operation is successful; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileSeek(int fd, int offset, unsigned int whence); /** * @brief Copies the source file to a target file. * * @param src Indicates the source file to copy. * @param dest Indicates the target file. * @attention If the number of opened files reaches the upper limit (32), close any two files first. * Otherwise, the file cannot be copied. * @return Returns 0 if the operation is successful; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileCopy(const char* src, const char* dest); /** * @brief Moves the source file into a target file. * * @param src Indicates the source file. * @param dest Indicates the target file. * @attention If the number of opened files reaches the upper limit (32), close any two files first. * Otherwise, the file cannot be moved. * @return Returns 0 if the operation is successful; returns -1 otherwise. * @since 1.0 * @version 1.0 */ int UtilsFileMove(const char* src, const char* dest); #ifdef __cplusplus #if __cplusplus } #endif #endif /* __cplusplus */ #endif // FILE_SYSTEM_API_H /** @} */