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
21extern "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 */
32enum 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 */
44enum MakeDirectionMode {
45    SINGLE,
46    MULTIPLE
47};
48
49/**
50 * @ingroup     rust
51 * @struct      Str
52 * @brief       Stores string and its effective length.
53 */
54typedef 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 */
71void* 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 */
79void 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 */
93Str* 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 */
108long 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 */
122int 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 */
134Str* 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 */
147Str* 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 */
155void StrFree(Str* str);
156
157#ifdef __cplusplus
158#if __cplusplus
159}
160#endif
161#endif
162
163#endif //RUST_FILE_H