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(const char* path);
72 
73 /**
74  * @ingroup     rust
75  * @brief       Drop iterator to release fd
76  * @param       iter pointer to reader iterator.
77  * @li          rust_file.h:The file where the interface is located.
78  */
79 void DropReaderIterator(void* iter);
80 
81 /**
82  * @ingroup     rust
83  * @brief       Reads a line from the reader iterator.
84  * @param       iter   pointer to reader iterator.
85  * @retval      NULL and error stored in errno  Invalid pointer to iterator.
86  * @retval      NULL and no error in errno      Gets the last line of content from the iterator.
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(void* iter);
94 
95 /**
96  * @ingroup     rust
97  * @brief       Seeks to an offset, in bytes, in a file.
98  * @param       fd      file descriptor.
99  * @param       offset  seek offset.
100  * @param       pos     seek position.
101  * @retval      >=0     the resulting offset location.
102  * @retval      -1      error occurs.
103  * @attention
104  * 1.It can fail because it may involve flushing a buffer or seek to a negative offset.
105  * 2.Errors are stored in errno.
106  * @li          rust_file.h:The file where the interface is located.
107  */
108 long long int Lseek(int fd, long long offset, enum SeekPos pos);
109 
110 /**
111  * @ingroup     rust
112  * @brief       Creates a new directory at the given path.
113  * @param       path    direction path.
114  * @param       mode    creating ways.
115  * @retval      0       Created successfully.
116  * @retval      -1      Creation failed.
117  * @attention
118  * 1.The input `path` must be in valid UTF-8 format.
119  * 2.Errors are stored in errno.
120  * @li          rust_file.h:The file where the interface is located.
121  */
122 int Mkdirs(const char* path, enum MakeDirectionMode mode);
123 
124 /**
125  * @ingroup     rust
126  * @brief       Get the parent directory of the specified file.
127  * @param       fd      file descriptor.
128  * @retval      NULL    The path terminates in a root or prefix or the file is closed.
129  * @retval      !NULL   The parent directory of the specified file.
130  * @attention
131  * 1.Errors are stored in errno.
132  * @li          rust_file.h:The file where the interface is located.
133  */
134 Str* GetParent(int fd);
135 
136 /**
137  * @ingroup     rust
138  * @brief       Cut the file name by the specified length.
139  * @param       path    file name.
140  * @param       size    specified length.
141  * @retval      NULL    The file name is empty or error.
142  * @retval      !NULL   The result of the file name after cutting.
143  * @attention
144  * 1.Errors are stored in errno.
145  * @li          rust_file.h:The file where the interface is located.
146  */
147 Str* CutFileName(const char* path, size_t size);
148 
149 /**
150  * @ingroup     rust
151  * @brief       Releases the memory that the `Str` pointer points to.
152  * @param       lines   pointer to `Str`.
153  * @li          rust_file.h:The file where the interface is located.
154  */
155 void StrFree(Str* str);
156 
157 #ifdef __cplusplus
158 #if __cplusplus
159 }
160 #endif
161 #endif
162 
163 #endif //RUST_FILE_H