1 /*
2  * Copyright (c) 2022-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 /**
17  * @addtogroup rawfile
18  * @{
19  *
20  * @brief Provides native functions for the resource manager to operate raw file directories and their raw files.
21  *
22  * You can use the resource manager to traverse, open, seek, read, and close raw files.
23  *
24  * @since 8
25  * @version 1.0
26  */
27 
28 /**
29  * @file raw_file.h
30  *
31  * @brief Declares native functions related to raw file.
32  *
33  * For example, you can use the functions to search for, read, and close raw files.
34  *
35  * @since 8
36  * @version 1.0
37  */
38 #ifndef GLOBAL_RAW_FILE_H
39 #define GLOBAL_RAW_FILE_H
40 
41 #include <stddef.h>
42 #include <stdint.h>
43 #include <stdbool.h>
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 struct RawFile;
50 
51 /**
52  * @brief Provides access to a raw file.
53  *
54  * @since 11
55  * @version 1.0
56  */
57 struct RawFile64;
58 
59 /**
60  * @brief Provides access to a raw file.
61  *
62  *
63  *
64  * @since 8
65  * @version 1.0
66  */
67 typedef struct RawFile RawFile;
68 
69 /**
70  * @brief Provides access to a raw file.
71  *
72  * @since 11
73  * @version 1.0
74  */
75 typedef struct RawFile64 RawFile64;
76 
77 /**
78  * @brief Represent the raw file descriptor's info.
79  *
80  * The RawFileDescriptor is an output parameter in the {@link OH_ResourceManager_GetRawFileDescriptor},
81  * and describes the raw file's file descriptor, start position and the length in the HAP.
82  *
83  * @since 8
84  * @version 1.0
85  */
86 typedef struct {
87     /** the raw file fd */
88     int fd;
89 
90     /** the offset from where the raw file starts in the HAP */
91     long start;
92 
93     /** the length of the raw file in the HAP. */
94     long length;
95 } RawFileDescriptor;
96 
97 /**
98  * @brief Represent the raw file descriptor's info.
99  *
100  * The RawFileDescriptor64 is an output parameter in the {@link OH_ResourceManager_GetRawFileDescriptor64},
101  * and describes the raw file's file descriptor, start position and the length in the HAP.
102  *
103  * @since 11
104  * @version 1.0
105  */
106 typedef struct {
107     /** the raw file fd */
108     int fd;
109 
110     /** the offset from where the raw file starts in the HAP */
111     int64_t start;
112 
113     /** the length of the raw file in the HAP. */
114     int64_t length;
115 } RawFileDescriptor64;
116 
117 /**
118  * @brief Reads a raw file.
119  *
120  * This function attempts to read data of <b>length</b> bytes from the current offset.
121  *
122  * @param rawFile Indicates the pointer to {@link RawFile}.
123  * @param buf Indicates the pointer to the buffer for receiving the data read.
124  * @param length Indicates the number of bytes to read.
125  * @return Returns the number of bytes read if any; returns <b>0</b> if the number reaches the end of file (EOF).
126  * @since 8
127  * @version 1.0
128  */
129 int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, size_t length);
130 
131 /**
132  * @brief Uses the 32-bit data type to seek a data read position based on the specified offset within a raw file.
133  *
134  * @param rawFile Indicates the pointer to {@link RawFile}.
135  * @param offset Indicates the specified offset.
136  * @param whence Indicates the new read position, which can be one of the following values: \n
137  * <b>0</b>: The new read position is set to <b>offset</b>. \n
138  * <b>1</b>: The read position is set to the current position plus <b>offset</b>. \n
139  * <b>2</b>: The read position is set to the end of file (EOF) plus <b>offset</b>.
140  * @return Returns <b>(int) 0</b> if the operation is successful; returns <b>(int) -1</b> if an error
141  * occurs.
142  * @since 8
143  * @version 1.0
144  */
145 int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence);
146 
147 /**
148  * @brief Obtains the raw file length represented by an long.
149  *
150  * @param rawFile Indicates the pointer to {@link RawFile}.
151  * @return Returns the total length of the raw file.
152  * @since 8
153  * @version 1.0
154  */
155 long OH_ResourceManager_GetRawFileSize(RawFile *rawFile);
156 
157 /**
158  * @brief Obtains the remaining raw file length represented by an long.
159  *
160  * @param rawFile Indicates the pointer to {@link RawFile}.
161  * @return Returns the remaining length of the raw file.
162  * @since 11
163  * @version 1.0
164  */
165 long OH_ResourceManager_GetRawFileRemainingLength(const RawFile *rawFile);
166 
167 /**
168  * @brief Closes an opened {@link RawFile} and releases all associated resources.
169  *
170  *
171  *
172  * @param rawFile Indicates the pointer to {@link RawFile}.
173  * @see OH_ResourceManager_OpenRawFile
174  * @since 8
175  * @version 1.0
176  */
177 void OH_ResourceManager_CloseRawFile(RawFile *rawFile);
178 
179 /**
180  * @brief Obtains the current offset of a raw file, represented by an long.
181  *
182  * The current offset of a raw file.
183  *
184  * @param rawFile Indicates the pointer to {@link RawFile}.
185  * @return Returns the current offset of a raw file.
186  * @since 8
187  * @version 1.0
188  */
189 long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile);
190 
191 /**
192  * @brief Opens the file descriptor of a raw file based on the long offset and file length.
193  *
194  * The opened raw file descriptor is used to read the raw file.
195  *
196  * @param rawFile Indicates the pointer to {@link RawFile}.
197  * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
198  * @return Returns true: open the raw file descriptor successfully, false: the raw file is not allowed to access.
199  * @since 8
200  * @version 1.0
201  * @deprecated since 12
202  * @useinstead OH_ResourceManager_GetRawFileDescriptorData
203  */
204 bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor);
205 
206 /**
207  * @brief Obtains the file descriptor of a raw file based on the long offset and file length.
208  *
209  * The obtains raw file descriptor is used to read the raw file.
210  *
211  * @param rawFile Indicates the pointer to {@link RawFile}.
212  * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
213  * @return Returns true: obtains the raw file descriptor successfully, false: the raw file is not allowed to access.
214  * @since 12
215  * @version 1.0
216  */
217 bool OH_ResourceManager_GetRawFileDescriptorData(const RawFile *rawFile, RawFileDescriptor *descriptor);
218 
219 /**
220  * @brief Closes the file descriptor of a raw file.
221  *
222  * The opened raw file descriptor must be released after used to avoid the file descriptor leak.
223  *
224  * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
225  * @return Returns true: closes the raw file descriptor successfully, false: closes the raw file descriptor failed.
226  * @since 8
227  * @version 1.0
228  * @deprecated since 12
229  * @useinstead OH_ResourceManager_ReleaseRawFileDescriptorData
230  */
231 bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor);
232 
233 /**
234  * @brief Release the file descriptor of a raw file.
235  *
236  * The opened raw file descriptor must be released after used to avoid the file descriptor leak.
237  *
238  * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
239  * @return Returns true: release the raw file descriptor successfully, false: release the raw file descriptor failed.
240  * @since 12
241  * @version 1.0
242  */
243 bool OH_ResourceManager_ReleaseRawFileDescriptorData(const RawFileDescriptor *descriptor);
244 
245 /**
246  * @brief Reads a raw file.
247  *
248  * This function attempts to read data of <b>length</b> bytes from the current offset. using a 64-bit
249  *
250  * @param rawFile Indicates the pointer to {@link RawFile64}.
251  * @param buf Indicates the pointer to the buffer for receiving the data read.
252  * @param length Indicates the number of bytes to read.
253  * @return Returns the number of bytes read if any; returns <b>0</b> if the number reaches the end of file (EOF).
254  * @since 11
255  * @version 1.0
256  */
257 int64_t OH_ResourceManager_ReadRawFile64(const RawFile64 *rawFile, void *buf, int64_t length);
258 
259 /**
260  * @brief Uses the 64-bit data type to seek a data read position based on the specified offset within a raw file.
261  *
262  * @param rawFile Indicates the pointer to {@link RawFile64}.
263  * @param offset Indicates the specified offset.
264  * @param whence Indicates the new read position, which can be one of the following values: \n
265  * <b>0</b>: The new read position is set to <b>offset</b>. \n
266  * <b>1</b>: The read position is set to the current position plus <b>offset</b>. \n
267  * <b>2</b>: The read position is set to the end of file (EOF) plus <b>offset</b>.
268  * @return Returns <b>(int) 0</b> if the operation is successful; returns <b>(int) -1</b> if an error
269  * occurs.
270  * @since 11
271  * @version 1.0
272  */
273 int OH_ResourceManager_SeekRawFile64(const RawFile64 *rawFile, int64_t offset, int whence);
274 
275 /**
276  * @brief Obtains the raw file length represented by an int64_t.
277  *
278  * @param rawFile Indicates the pointer to {@link RawFile64}.
279  * @return Returns the total length of the raw file.
280  * @since 11
281  * @version 1.0
282  */
283 int64_t OH_ResourceManager_GetRawFileSize64(RawFile64 *rawFile);
284 
285 /**
286  * @brief Obtains the remaining raw file length represented by an int64_t.
287  *
288  * @param rawFile Indicates the pointer to {@link RawFile64}.
289  * @return Returns the remaining length of the raw file.
290  * @since 11
291  * @version 1.0
292  */
293 int64_t OH_ResourceManager_GetRawFileRemainingLength64(const RawFile64 *rawFile);
294 
295 /**
296  * @brief Closes an opened {@link RawFile64} and releases all associated resources.
297  *
298  *
299  *
300  * @param rawFile Indicates the pointer to {@link RawFile64}.
301  * @see OH_ResourceManager_OpenRawFile64
302  * @since 11
303  * @version 1.0
304  */
305 void OH_ResourceManager_CloseRawFile64(RawFile64 *rawFile);
306 
307 /**
308  * @brief Obtains the current offset of a raw file, represented by an int64_t.
309  *
310  * The current offset of a raw file.
311  *
312  * @param rawFile Indicates the pointer to {@link RawFile64}.
313  * @return Returns the current offset of a raw file.
314  * @since 11
315  * @version 1.0
316  */
317 int64_t OH_ResourceManager_GetRawFileOffset64(const RawFile64 *rawFile);
318 
319 /**
320  * @brief Opens the file descriptor of a raw file based on the int64_t offset and file length.
321  *
322  * The opened raw file descriptor is used to read the raw file.
323  *
324  * @param rawFile Indicates the pointer to {@link RawFile64}.
325  * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
326  * @return Returns true: open the raw file descriptor successfully, false: the raw file is not allowed to access.
327  * @since 11
328  * @version 1.0
329  */
330 bool OH_ResourceManager_GetRawFileDescriptor64(const RawFile64 *rawFile, RawFileDescriptor64 *descriptor);
331 
332 /**
333  * @brief Closes the file descriptor of a raw file.
334  *
335  * The opened raw file descriptor must be released after used to avoid the file descriptor leak.
336  *
337  * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
338  * @return Returns true: closes the raw file descriptor successfully, false: closes the raw file descriptor failed.
339  * @since 11
340  * @version 1.0
341  */
342 bool OH_ResourceManager_ReleaseRawFileDescriptor64(const RawFileDescriptor64 *descriptor);
343 
344 #ifdef __cplusplus
345 };
346 #endif
347 
348 /** @} */
349 #endif // GLOBAL_RAW_FILE_H
350