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 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; 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 */ 130 int 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 */ 146 int 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 */ 156 long 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 */ 166 long 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 */ 178 void 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 */ 190 long 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 */ 205 bool 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 */ 218 bool 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 */ 232 bool 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 */ 244 bool 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 */ 259 int64_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 */ 275 int 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 */ 285 int64_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 */ 295 int64_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 */ 307 void 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 */ 319 int64_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 */ 332 bool 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 */ 344 bool OH_ResourceManager_ReleaseRawFileDescriptor64(const RawFileDescriptor64 *descriptor); 345 346 #ifdef __cplusplus 347 }; 348 #endif 349 350 /** @} */ 351 #endif // GLOBAL_RAW_FILE_H 352