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 * @kit LocalizationKit
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
46extern "C" {
47#endif
48
49struct RawFile;
50
51/**
52 * @brief Provides access to a raw file.
53 *
54 * @since 11
55 * @version 1.0
56 */
57struct RawFile64;
58
59/**
60 * @brief Provides access to a raw file.
61 *
62 *
63 *
64 * @since 8
65 * @version 1.0
66 */
67typedef struct RawFile RawFile;
68
69/**
70 * @brief Provides access to a raw file.
71 *
72 * @since 11
73 * @version 1.0
74 */
75typedef 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 */
86typedef 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 */
106typedef 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;
126 *         if the number reaches the end of file (EOF) or rawFile is nullptr also returns <b>0</b>
127 * @since 8
128 * @version 1.0
129 */
130int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, size_t length);
131
132/**
133 * @brief Uses the 32-bit data type to seek a data read position based on the specified offset within a raw file.
134 *
135 * @param rawFile Indicates the pointer to {@link RawFile}.
136 * @param offset Indicates the specified offset.
137 * @param whence Indicates the new read position, which can be one of the following values: \n
138 * <b>0</b>: The new read position is set to <b>offset</b>. \n
139 * <b>1</b>: The read position is set to the current position plus <b>offset</b>. \n
140 * <b>2</b>: The read position is set to the end of file (EOF) plus <b>offset</b>.
141 * @return Returns <b>(int) 0</b> if the operation is successful; returns <b>(int) -1</b> if an error
142 * occurs.
143 * @since 8
144 * @version 1.0
145 */
146int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence);
147
148/**
149 * @brief Obtains the raw file length represented by an long.
150 *
151 * @param rawFile Indicates the pointer to {@link RawFile}.
152 * @return Returns the total length of the raw file. If rawFile is nullptr also returns 0.
153 * @since 8
154 * @version 1.0
155 */
156long OH_ResourceManager_GetRawFileSize(RawFile *rawFile);
157
158/**
159 * @brief Obtains the remaining raw file length represented by an long.
160 *
161 * @param rawFile Indicates the pointer to {@link RawFile}.
162 * @return Returns the remaining length of the raw file. If rawFile is nullptr also returns 0.
163 * @since 11
164 * @version 1.0
165 */
166long OH_ResourceManager_GetRawFileRemainingLength(const RawFile *rawFile);
167
168/**
169 * @brief Closes an opened {@link RawFile} and releases all associated resources.
170 *
171 *
172 *
173 * @param rawFile Indicates the pointer to {@link RawFile}.
174 * @see OH_ResourceManager_OpenRawFile
175 * @since 8
176 * @version 1.0
177 */
178void OH_ResourceManager_CloseRawFile(RawFile *rawFile);
179
180/**
181 * @brief Obtains the current offset of a raw file, represented by an long.
182 *
183 * The current offset of a raw file.
184 *
185 * @param rawFile Indicates the pointer to {@link RawFile}.
186 * @return Returns the current offset of a raw file. If rawFile is nullptr also returns 0.
187 * @since 8
188 * @version 1.0
189 */
190long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile);
191
192/**
193 * @brief Opens the file descriptor of a raw file based on the long offset and file length.
194 *
195 * The opened raw file descriptor is used to read the raw file.
196 *
197 * @param rawFile Indicates the pointer to {@link RawFile}.
198 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
199 * @return Returns true: open the raw file descriptor successfully, false: the raw file is not allowed to access.
200 * @since 8
201 * @version 1.0
202 * @deprecated since 12
203 * @useinstead OH_ResourceManager_GetRawFileDescriptorData
204 */
205bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor);
206
207/**
208 * @brief Obtains the file descriptor of a raw file based on the long offset and file length.
209 *
210 * The obtains raw file descriptor is used to read the raw file.
211 *
212 * @param rawFile Indicates the pointer to {@link RawFile}.
213 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
214 * @return Returns true: obtains the raw file descriptor successfully, false: the raw file is not allowed to access.
215 * @since 12
216 * @version 1.0
217 */
218bool OH_ResourceManager_GetRawFileDescriptorData(const RawFile *rawFile, RawFileDescriptor *descriptor);
219
220/**
221 * @brief Closes the file descriptor of a raw file.
222 *
223 * The opened raw file descriptor must be released after used to avoid the file descriptor leak.
224 *
225 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
226 * @return Returns true: closes the raw file descriptor successfully, false: closes the raw file descriptor failed.
227 * @since 8
228 * @version 1.0
229 * @deprecated since 12
230 * @useinstead OH_ResourceManager_ReleaseRawFileDescriptorData
231 */
232bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor);
233
234/**
235 * @brief Release the file descriptor of a raw file.
236 *
237 * The opened raw file descriptor must be released after used to avoid the file descriptor leak.
238 *
239 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
240 * @return Returns true: release the raw file descriptor successfully, false: release the raw file descriptor failed.
241 * @since 12
242 * @version 1.0
243 */
244bool OH_ResourceManager_ReleaseRawFileDescriptorData(const RawFileDescriptor *descriptor);
245
246/**
247 * @brief Reads a raw file.
248 *
249 * This function attempts to read data of <b>length</b> bytes from the current offset. using a 64-bit
250 *
251 * @param rawFile Indicates the pointer to {@link RawFile64}.
252 * @param buf Indicates the pointer to the buffer for receiving the data read.
253 * @param length Indicates the number of bytes to read.
254 * @return Returns the number of bytes read if any;
255 *         returns <b>0</b> if the number reaches the end of file (EOF). or rawFile is nullptr also returns 0
256 * @since 11
257 * @version 1.0
258 */
259int64_t OH_ResourceManager_ReadRawFile64(const RawFile64 *rawFile, void *buf, int64_t length);
260
261/**
262 * @brief Uses the 64-bit data type to seek a data read position based on the specified offset within a raw file.
263 *
264 * @param rawFile Indicates the pointer to {@link RawFile64}.
265 * @param offset Indicates the specified offset.
266 * @param whence Indicates the new read position, which can be one of the following values: \n
267 * <b>0</b>: The new read position is set to <b>offset</b>. \n
268 * <b>1</b>: The read position is set to the current position plus <b>offset</b>. \n
269 * <b>2</b>: The read position is set to the end of file (EOF) plus <b>offset</b>.
270 * @return Returns <b>(int) 0</b> if the operation is successful; returns <b>(int) -1</b> if an error
271 * occurs.
272 * @since 11
273 * @version 1.0
274 */
275int OH_ResourceManager_SeekRawFile64(const RawFile64 *rawFile, int64_t offset, int whence);
276
277/**
278 * @brief Obtains the raw file length represented by an int64_t.
279 *
280 * @param rawFile Indicates the pointer to {@link RawFile64}.
281 * @return Returns the total length of the raw file. If rawFile is nullptr also returns 0.
282 * @since 11
283 * @version 1.0
284 */
285int64_t OH_ResourceManager_GetRawFileSize64(RawFile64 *rawFile);
286
287/**
288 * @brief Obtains the remaining raw file length represented by an int64_t.
289 *
290 * @param rawFile Indicates the pointer to {@link RawFile64}.
291 * @return Returns the remaining length of the raw file. If rawFile is nullptr also returns 0.
292 * @since 11
293 * @version 1.0
294 */
295int64_t OH_ResourceManager_GetRawFileRemainingLength64(const RawFile64 *rawFile);
296
297/**
298 * @brief Closes an opened {@link RawFile64} and releases all associated resources.
299 *
300 *
301 *
302 * @param rawFile Indicates the pointer to {@link RawFile64}.
303 * @see OH_ResourceManager_OpenRawFile64
304 * @since 11
305 * @version 1.0
306 */
307void OH_ResourceManager_CloseRawFile64(RawFile64 *rawFile);
308
309/**
310 * @brief Obtains the current offset of a raw file, represented by an int64_t.
311 *
312 * The current offset of a raw file.
313 *
314 * @param rawFile Indicates the pointer to {@link RawFile64}.
315 * @return Returns the current offset of a raw file. If rawFile is nullptr also returns 0.
316 * @since 11
317 * @version 1.0
318 */
319int64_t OH_ResourceManager_GetRawFileOffset64(const RawFile64 *rawFile);
320
321/**
322 * @brief Opens the file descriptor of a raw file based on the int64_t offset and file length.
323 *
324 * The opened raw file descriptor is used to read the raw file.
325 *
326 * @param rawFile Indicates the pointer to {@link RawFile64}.
327 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
328 * @return Returns true: open the raw file descriptor successfully, false: the raw file is not allowed to access.
329 * @since 11
330 * @version 1.0
331 */
332bool OH_ResourceManager_GetRawFileDescriptor64(const RawFile64 *rawFile, RawFileDescriptor64 *descriptor);
333
334/**
335 * @brief Closes the file descriptor of a raw file.
336 *
337 * The opened raw file descriptor must be released after used to avoid the file descriptor leak.
338 *
339 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP.
340 * @return Returns true: closes the raw file descriptor successfully, false: closes the raw file descriptor failed.
341 * @since 11
342 * @version 1.0
343 */
344bool OH_ResourceManager_ReleaseRawFileDescriptor64(const RawFileDescriptor64 *descriptor);
345
346#ifdef __cplusplus
347};
348#endif
349
350/** @} */
351#endif // GLOBAL_RAW_FILE_H
352