1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup OSAL 11 * @{ 12 * 13 * @brief Defines the structures and interfaces for the Operating System Abstraction Layer (OSAL) module. 14 * 15 * The OSAL module OpenHarmony OS interface differences and provides unified OS interfaces externally, 16 * including the memory management, thread, mutex, spinlock, semaphore, timer, file, interrupt, time, 17 * atomic, firmware, and I/O operation modules. 18 * 19 * @since 1.0 20 * @version 1.0 21 */ 22 23 /** 24 * @file osal_file.h 25 * 26 * @brief Declares the file structures and interfaces. 27 * 28 * This file provides interfaces for opening, closing, reading, and writing a file, and setting the read/write offset. 29 * 30 * @since 1.0 31 * @version 1.0 32 */ 33 34 #ifndef OSAL_FILE_H 35 #define OSAL_FILE_H 36 37 #include "hdf_base.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif /* __cplusplus */ 42 43 /** 44 * @brief Opens a file in read-only mode. 45 */ 46 #define OSAL_O_RD_ONLY 0 47 /** 48 * @brief Opens a file in write-only mode. 49 */ 50 #define OSAL_O_WR_ONLY 1 51 /** 52 * @brief Opens a file in read and write mode. 53 */ 54 #define OSAL_O_RDWR 2 55 56 /** 57 * @brief Defines the read permission for the owner. 58 */ 59 #define OSAL_S_IREAD 00400 60 /** 61 * @brief Defines the write permission for the owner. 62 */ 63 #define OSAL_S_IWRITE 00200 64 /** 65 * @brief Defines the execution permission for the owner. 66 */ 67 #define OSAL_S_IEXEC 00100 68 69 /** 70 * @brief Defines the read permission for the group. 71 */ 72 #define OSAL_S_IRGRP 00040 73 /** 74 * @brief Defines the write permission for the group. 75 */ 76 #define OSAL_S_IWGRP 00020 77 /** 78 * @brief Defines the execution permission for the group. 79 */ 80 #define OSAL_S_IXGRP 00010 81 82 /** 83 * @brief Defines the read permission for others. 84 */ 85 #define OSAL_S_IROTH 00004 86 /** 87 * @brief Defines the write permission for others. 88 */ 89 #define OSAL_S_IWOTH 00002 90 /** 91 * @brief Defines the execution permission for others. 92 */ 93 #define OSAL_S_IXOTH 00001 94 95 /** 96 * @brief Defines the offset from the file header. 97 */ 98 #define OSAL_SEEK_SET 0 99 /** 100 * @brief Defines the offset from the current position. 101 */ 102 #define OSAL_SEEK_CUR 1 103 /** 104 * @brief Defines the offset from the end of the file. 105 */ 106 #define OSAL_SEEK_END 2 107 108 /** 109 * @brief Declares a file type. 110 */ 111 typedef struct { 112 void *realFile; /**< Pointer to a file object to access */ 113 } OsalFile; 114 115 /** 116 * @brief Opens a file. 117 * 118 * @param file Indicates the pointer to the file type {@link OsalFile}. 119 * @param path Indicates the pointer to the name of the file to open. 120 * @param flags Indicates the mode of opening the file. For details, see {@link OSAL_O_RD_ONLY}. 121 * @param rights Indicates the permissions required for opening the file. For details, see {@link OSAL_S_IREAD}. 122 * 123 * @return Returns a value listed below: \n 124 * HDF_STATUS | Description 125 * ----------------------| ----------------------- 126 * HDF_SUCCESS | The operation is successful. 127 * HDF_FAILURE | Failed to invoke the system function to open the file. 128 * HDF_ERR_INVALID_PARAM | Invalid parameter. 129 * 130 * @since 1.0 131 * @version 1.0 132 */ 133 int32_t OsalFileOpen(OsalFile *file, const char *path, int flags, uint32_t rights); 134 135 /** 136 * @brief Writes a file. 137 * 138 * @param file Indicates the pointer to the file type {@link OsalFile}. 139 * @param string Indicates the pointer to the content to write. 140 * @param length Indicates the length of the content to write. 141 * 142 * @return Returns a value listed below: \n 143 * ssize_t | Description 144 * -----------------------------------------| ----------------------- 145 * Greater than <b>0</b> | The length of the file content is successfully written. 146 * HDF_FAILURE {@link HDF_STATUS} | Failed to invoke the system function to write the file. 147 * HDF_ERR_INVALID_PARAM {@link HDF_STATUS} | Invalid parameter. 148 * 149 * @since 1.0 150 * @version 1.0 151 */ 152 ssize_t OsalFileWrite(OsalFile *file, const void *string, uint32_t length); 153 154 /** 155 * @brief Closes a file. 156 * 157 * @param file Indicates the pointer to the file type {@link OsalFile}. 158 * 159 * @since 1.0 160 * @version 1.0 161 */ 162 void OsalFileClose(OsalFile *file); 163 164 /** 165 * @brief Reads a file. 166 * 167 * @param file Indicates the pointer to the file type {@link OsalFile}. 168 * @param buf Indicates the pointer to the buffer for storing the content to read. 169 * @param length Indicates the length of the content to read. 170 * 171 * @return Returns a value listed below: \n 172 * ssize_t | Description 173 * -----------------------------------------| ----------------------- 174 * Greater than <b>0</b> | The length of the file content is successfully read. 175 * HDF_FAILURE {@link HDF_STATUS} | Failed to invoke the system function to read the file. 176 * HDF_ERR_INVALID_PARAM {@link HDF_STATUS} | Invalid parameter. 177 * 178 * @since 1.0 179 * @version 1.0 180 */ 181 ssize_t OsalFileRead(OsalFile *file, void *buf, uint32_t length); 182 183 /** 184 * @brief Sets the file read/write offset. 185 * 186 * @param file Indicates the pointer to the file type {@link OsalFile}. 187 * @param offset Indicates the offset to set. 188 * @param whence Indicates the position from which the offset is to set. For details, see {@link OSAL_SEEK_SET}. 189 * 190 * off_t | Description 191 * -----------------------------------------| ----------------------- 192 * Greater than <b>0</b> | The offset is set. 193 * HDF_FAILURE {@link HDF_STATUS} | Failed to invoke the system function to set the file offset. 194 * HDF_ERR_INVALID_PARAM {@link HDF_STATUS} | Invalid parameter. 195 * 196 * @since 1.0 197 * @version 1.0 198 */ 199 off_t OsalFileLseek(OsalFile *file, off_t offset, int32_t whence); 200 201 #ifdef __cplusplus 202 } 203 #endif /* __cplusplus */ 204 205 #endif /* OSAL_FILE_H */ 206 /** @} */ 207