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 * @since 8 38 * @version 1.0 39 */ 40 #ifndef GLOBAL_RAW_FILE_H 41 #define GLOBAL_RAW_FILE_H 42 43 #include <stddef.h> 44 #include <stdint.h> 45 #include <stdbool.h> 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 struct RawFile; 52 53 /** 54 * @brief Provides access to a raw file. 55 * 56 * @since 11 57 * @version 1.0 58 */ 59 struct RawFile64; 60 61 /** 62 * @brief Provides access to a raw file. 63 * 64 * 65 * 66 * @since 8 67 * @version 1.0 68 */ 69 typedef struct RawFile RawFile; 70 71 /** 72 * @brief Provides access to a raw file. 73 * 74 * @since 11 75 * @version 1.0 76 */ 77 typedef struct RawFile64 RawFile64; 78 79 /** 80 * @brief Represent the raw file descriptor's info. 81 * 82 * The RawFileDescriptor is an output parameter in the {@link OH_ResourceManager_GetRawFileDescriptor}, 83 * and describes the raw file's file descriptor, start position and the length in the HAP. 84 * 85 * @since 8 86 * @version 1.0 87 */ 88 typedef struct { 89 /** the raw file fd */ 90 int fd; 91 92 /** the offset from where the raw file starts in the HAP */ 93 long start; 94 95 /** the length of the raw file in the HAP. */ 96 long length; 97 } RawFileDescriptor; 98 99 /** 100 * @brief Represent the raw file descriptor's info. 101 * 102 * The RawFileDescriptor64 is an output parameter in the {@link OH_ResourceManager_GetRawFileDescriptor64}, 103 * and describes the raw file's file descriptor, start position and the length in the HAP. 104 * 105 * @since 11 106 * @version 1.0 107 */ 108 typedef struct { 109 /** the raw file fd */ 110 int fd; 111 112 /** the offset from where the raw file starts in the HAP */ 113 int64_t start; 114 115 /** the length of the raw file in the HAP. */ 116 int64_t length; 117 } RawFileDescriptor64; 118 119 /** 120 * @brief Reads a raw file. 121 * 122 * This function attempts to read data of <b>length</b> bytes from the current offset. 123 * 124 * @param rawFile Indicates the pointer to {@link RawFile}. 125 * @param buf Indicates the pointer to the buffer for receiving the data read. 126 * @param length Indicates the number of bytes to read. 127 * @return Returns the number of bytes read if any; returns <b>0</b> if the number reaches the end of file (EOF). 128 * @since 8 129 * @version 1.0 130 */ 131 int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, size_t length); 132 133 /** 134 * @brief Uses the 32-bit data type to seek a data read position based on the specified offset within a raw file. 135 * 136 * @param rawFile Indicates the pointer to {@link RawFile}. 137 * @param offset Indicates the specified offset. 138 * @param whence Indicates the new read position, which can be one of the following values: \n 139 * <b>0</b>: The new read position is set to <b>offset</b>. \n 140 * <b>1</b>: The read position is set to the current position plus <b>offset</b>. \n 141 * <b>2</b>: The read position is set to the end of file (EOF) plus <b>offset</b>. 142 * @return Returns <b>(int) 0</b> if the operation is successful; returns <b>(int) -1</b> if an error 143 * occurs. 144 * @since 8 145 * @version 1.0 146 */ 147 int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence); 148 149 /** 150 * @brief Obtains the raw file length represented by an long. 151 * 152 * @param rawFile Indicates the pointer to {@link RawFile}. 153 * @return Returns the total length of the raw file. 154 * @since 8 155 * @version 1.0 156 */ 157 long OH_ResourceManager_GetRawFileSize(RawFile *rawFile); 158 159 /** 160 * @brief Obtains the remaining raw file length represented by an long. 161 * 162 * @param rawFile Indicates the pointer to {@link RawFile}. 163 * @return Returns the remaining length of the raw file. 164 * @since 11 165 * @version 1.0 166 */ 167 long OH_ResourceManager_GetRawFileRemainingLength(const RawFile *rawFile); 168 169 /** 170 * @brief Closes an opened {@link RawFile} and releases all associated resources. 171 * 172 * 173 * 174 * @param rawFile Indicates the pointer to {@link RawFile}. 175 * @see OH_ResourceManager_OpenRawFile 176 * @since 8 177 * @version 1.0 178 */ 179 void OH_ResourceManager_CloseRawFile(RawFile *rawFile); 180 181 /** 182 * @brief Obtains the current offset of a raw file, represented by an long. 183 * 184 * The current offset of a raw file. 185 * 186 * @param rawFile Indicates the pointer to {@link RawFile}. 187 * @return Returns the current offset of a raw file. 188 * @since 8 189 * @version 1.0 190 */ 191 long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile); 192 193 /** 194 * @brief Opens the file descriptor of a raw file based on the long offset and file length. 195 * 196 * The opened raw file descriptor is used to read the raw file. 197 * 198 * @param rawFile Indicates the pointer to {@link RawFile}. 199 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP. 200 * @return Returns true: open the raw file descriptor successfully, false: the raw file is not allowed to access. 201 * @since 8 202 * @version 1.0 203 * @deprecated since 12 204 * @useinstead OH_ResourceManager_GetRawFileDescriptorData 205 */ 206 bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor); 207 208 /** 209 * @brief Obtains the file descriptor of a raw file based on the long offset and file length. 210 * 211 * The obtains raw file descriptor is used to read the raw file. 212 * 213 * @param rawFile Indicates the pointer to {@link RawFile}. 214 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP. 215 * @return Returns true: obtains the raw file descriptor successfully, false: the raw file is not allowed to access. 216 * @since 12 217 * @version 1.0 218 */ 219 bool OH_ResourceManager_GetRawFileDescriptorData(const RawFile *rawFile, RawFileDescriptor *descriptor); 220 221 /** 222 * @brief Closes the file descriptor of a raw file. 223 * 224 * The opened raw file descriptor must be released after used to avoid the file descriptor leak. 225 * 226 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP. 227 * @return Returns true: closes the raw file descriptor successfully, false: closes the raw file descriptor failed. 228 * @since 8 229 * @version 1.0 230 * @deprecated since 12 231 * @useinstead OH_ResourceManager_ReleaseRawFileDescriptorData 232 */ 233 bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor); 234 235 /** 236 * @brief Release the file descriptor of a raw file. 237 * 238 * The opened raw file descriptor must be released after used to avoid the file descriptor leak. 239 * 240 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP. 241 * @return Returns true: release the raw file descriptor successfully, false: release the raw file descriptor failed. 242 * @since 12 243 * @version 1.0 244 */ 245 bool OH_ResourceManager_ReleaseRawFileDescriptorData(const RawFileDescriptor *descriptor); 246 247 /** 248 * @brief Reads a raw file. 249 * 250 * This function attempts to read data of <b>length</b> bytes from the current offset. using a 64-bit 251 * 252 * @param rawFile Indicates the pointer to {@link RawFile64}. 253 * @param buf Indicates the pointer to the buffer for receiving the data read. 254 * @param length Indicates the number of bytes to read. 255 * @return Returns the number of bytes read if any; returns <b>0</b> if the number reaches the end of file (EOF). 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. 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. 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. 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