1 /* 2 * Copyright (c) 2023 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 #ifndef RUST_FILE_H 17 #define RUST_FILE_H 18 19 #ifdef __cplusplus 20 #if __cplusplus 21 extern "C" { 22 #endif 23 #endif 24 25 /** 26 * @ingroup rust 27 * @brief Structure for storing file information by line. 28 * @attention Calls the `stringVectorFree` interface to release the instance. 29 */ 30 typedef void StringVector; 31 32 33 /** 34 * @ingroup rust 35 * @brief Enumeration of `lseek` interface to seek within a file. 36 * @param Start Sets the offset from the head of the file. 37 * @param Current Sets the offset from the current position. 38 * @param End Sets the offset from th tail of the file. 39 */ 40 enum SeekPos { 41 START, 42 CURRENT, 43 END 44 }; 45 46 /** 47 * @ingroup rust 48 * @brief Enumeration of `mkdirs` interface to choose ways to create the direction. 49 * @param Single Creates a single level directory. 50 * @param Multiple Creates a multi-level directory. 51 */ 52 enum MakeDirectionMode { 53 SINGLE, 54 MULTIPLE 55 }; 56 57 /** 58 * @ingroup rust 59 * @struct Str 60 * @brief Stores string and its effective length. 61 */ 62 typedef struct { 63 const char* str; 64 unsigned int len; 65 } Str; 66 67 /** 68 * @ingroup rust 69 * @brief Reads the content of a file in a path and split it by line. 70 * @param path file path. 71 * @retval NULL Fails to read the file, stores error information from errno. 72 * @retval !NULL Reads the file successfully, valid `StringVector` pointer. 73 * @attention 74 * 1.The return value needs to be released by calling the `stringVectorFree` method. 75 * 2.The input `path` must be in valid UTF-8 format. 76 * 3.Errors are stored in errno. 77 * @li rust_file.h:The file where the interface is located. 78 */ 79 StringVector* ReadLines(char* path); 80 81 /** 82 * @ingroup rust 83 * @brief Gets a line of content from `StringVector`. 84 * @param lines pointer to `StringVector`. 85 * @retval NULL and error stored in errno Invalid pointer to `StringVector`. 86 * @retval NULL and no error in errno Gets the last line of content in the `StringVector`. 87 * @retval !NULL Valid `Str` pointer, Gets a line of content successfully. 88 * @attention 89 * 1.The input `lines` must be a valid pointer to `StringVector`. 90 * 2.Errors are stored in errno. 91 * @li rust_file.h:The file where the interface is located. 92 */ 93 Str* NextLine(StringVector* lines); 94 95 /** 96 * @ingroup rust 97 * @brief Releases the memory that the `StringVector` pointer points to. 98 * @param lines pointer to `StringVector`. 99 * @li rust_file.h:The file where the interface is located. 100 */ 101 void StringVectorFree(StringVector* lines); 102 103 /** 104 * @ingroup rust 105 * @brief Seeks to an offset, in bytes, in a file. 106 * @param fd file descriptor. 107 * @param offset seek offset. 108 * @param pos seek position. 109 * @attention 110 * 1.It can fail because it may involve flushing a buffer or seek to a negative offset. 111 * 2.Errors are stored in errno. 112 * @li rust_file.h:The file where the interface is located. 113 */ 114 void Lseek(int fd, long long offset, enum SeekPos pos); 115 116 /** 117 * @ingroup rust 118 * @brief Creates a new directory at the given path. 119 * @param path direction path. 120 * @param mode creating ways. 121 * @attention 122 * 1.The input `path` must be in valid UTF-8 format. 123 * 2.Errors are stored in errno. 124 * @li rust_file.h:The file where the interface is located. 125 */ 126 void Mkdirs(char* path, enum MakeDirectionMode mode); 127 128 /** 129 * @ingroup rust 130 * @brief Get the parent directory of the specified file. 131 * @param fd file descriptor. 132 * @retval NULL The path terminates in a root or prefix or the file is closed. 133 * @retval !NULL The parent directory of the specified file. 134 * @attention 135 * 1.Errors are stored in errno. 136 * @li rust_file.h:The file where the interface is located. 137 */ 138 Str* GetParent(int fd); 139 140 /** 141 * @ingroup rust 142 * @brief Releases the memory that the `Str` pointer points to. 143 * @param lines pointer to `Str`. 144 * @li rust_file.h:The file where the interface is located. 145 */ 146 void ParentFree(Str* str); 147 148 #ifdef __cplusplus 149 #if __cplusplus 150 } 151 #endif 152 #endif 153 154 #endif //RUST_FILE_H