1 /* 2 * Copyright (c) 2022 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 <string> 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 struct RawFile; 48 49 /** 50 * @brief Provides access to a raw file. 51 * 52 * 53 * 54 * @since 8 55 * @version 1.0 56 */ 57 typedef struct RawFile RawFile; 58 59 /** 60 * @brief Represent the raw file descriptor's info. 61 * 62 * The RawFileDescriptor is an output parameter in the {@link OH_ResourceManager_GetRawFileDescriptor}, 63 * and describes the raw file's file descriptor, start position and the length in the HAP. 64 * 65 * @since 8 66 * @version 1.0 67 */ 68 typedef struct { 69 /** the raw file fd */ 70 int fd; 71 72 /** the offset from where the raw file starts in the HAP */ 73 long start; 74 75 /** the length of the raw file in the HAP. */ 76 long length; 77 } RawFileDescriptor; 78 79 /** 80 * @brief Reads a raw file. 81 * 82 * This function attempts to read data of <b>length</b> bytes from the current offset. 83 * 84 * @param rawFile Indicates the pointer to {@link RawFile}. 85 * @param buf Indicates the pointer to the buffer for receiving the data read. 86 * @param length Indicates the number of bytes to read. 87 * @return Returns the number of bytes read if any; returns <b>0</b> if the number reaches the end of file (EOF). 88 * @since 8 89 * @version 1.0 90 */ 91 int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, size_t length); 92 93 /** 94 * @brief Uses the 32-bit data type to seek a data read/write position based on the specified offset within a raw file. 95 * 96 * @param rawFile Indicates the pointer to {@link RawFile}. 97 * @param offset Indicates the specified offset. 98 * @param whence Indicates the new read/write position, which can be one of the following values: \n 99 * <b>0</b>: The new read/write position is set to <b>offset</b>. \n 100 * <b>1</b>: The read/write position is set to the current position plus <b>offset</b>. \n 101 * <b>2</b>: The read/write position is set to the end of file (EOF) plus <b>offset</b>. 102 * @return Returns the new read/write position if the operation is successful; returns <b>(long) -1</b> if an error 103 * occurs. 104 * @since 8 105 * @version 1.0 106 */ 107 int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence); 108 109 /** 110 * @brief Obtains the raw file length represented by an int32_t. 111 * 112 * @param rawFile Indicates the pointer to {@link RawFile}. 113 * @return Returns the total length of the raw file. 114 * @since 8 115 * @version 1.0 116 */ 117 long OH_ResourceManager_GetRawFileSize(RawFile *rawFile); 118 119 /** 120 * @brief Closes an opened {@link RawFile} and releases all associated resources. 121 * 122 * 123 * 124 * @param rawFile Indicates the pointer to {@link RawFile}. 125 * @see OH_ResourceManager_OpenRawFile 126 * @since 8 127 * @version 1.0 128 */ 129 void OH_ResourceManager_CloseRawFile(RawFile *rawFile); 130 131 /** 132 * @brief Obtains the current offset of a raw file, represented by an int32_t. 133 * 134 * The current offset of a raw file. 135 * 136 * @param rawFile Indicates the pointer to {@link RawFile}. 137 * @return Returns the current offset of a raw file. 138 * @since 8 139 * @version 1.0 140 */ 141 long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile); 142 143 /** 144 * @brief Opens the file descriptor of a raw file based on the int32_t offset and file length. 145 * 146 * The opened raw file descriptor is used to read the raw file. 147 * 148 * @param rawFile Indicates the pointer to {@link RawFile}. 149 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP. 150 * @return Returns true: open the raw file descriptor successfully, false: the raw file is not allowed to access. 151 * @since 8 152 * @version 1.0 153 */ 154 bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor); 155 156 /** 157 * @brief Closes the file descriptor of a raw file. 158 * 159 * The opened raw file descriptor must be released after used to avoid the file descriptor leak. 160 * 161 * @param descriptor Indicates the raw file's file descriptor, start position and the length in the HAP. 162 * @return Returns true: closes the raw file descriptor successfully, false: closes the raw file descriptor failed. 163 * @since 8 164 * @version 1.0 165 */ 166 bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor); 167 168 #ifdef __cplusplus 169 }; 170 #endif 171 172 /** @} */ 173 #endif // GLOBAL_RAW_FILE_H 174