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