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