1 #pragma once 2 #ifndef IW_FILE_H 3 #define IW_FILE_H 4 5 /************************************************************************************************** 6 * IOWOW library 7 * 8 * MIT License 9 * 10 * Copyright (c) 2012-2022 Softmotions Ltd <info@softmotions.com> 11 * 12 * Permission is hereby granted, free of charge, to any person obtaining a copy 13 * of this software and associated documentation files (the "Software"), to deal 14 * in the Software without restriction, including without limitation the rights 15 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 16 * copies of the Software, and to permit persons to whom the Software is 17 * furnished to do so, subject to the following conditions: 18 * 19 * The above copyright notice and this permission notice shall be included in all 20 * copies or substantial portions of the Software. 21 * 22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 25 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 27 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 28 * SOFTWARE. 29 *************************************************************************************************/ 30 31 /** 32 * @file 33 * @brief Simple read-write file abstraction implementation. 34 * @author Anton Adamansky (adamansky@softmotions.com) 35 * 36 * @note Before using API of this module you should call 37 * `iw_init(void)` iowow module initialization routine. 38 * 39 * File operations implemented as function pointers contained in `IWFS_FILE` `C` 40 * structure. 41 * The `iwfs_file_open(IWFS_FILE *f, const IWFS_FILE_OPTS *opts)` opens file and 42 * initializes a given `IWFS_FILE` structure. 43 * 44 * <strong>Common use case:</strong>. 45 * @code {.c} 46 * 47 * #include <iowow/iwfile.h> 48 * 49 * iw_init(); //Initialize iowoow library 50 * 51 * IWFS_FILE f; 52 * IWFS_FILE_OPTS opts = { //File options 53 * .path = "file path", 54 * ... 55 * }; 56 * iwrc rc = iwfs_file_open(&f, &opts); 57 * if (!rc) { 58 * .. //read/write operations 59 * rc = f.close(&f); 60 * } 61 * @endcode 62 */ 63 64 #include "iowow.h" 65 #include "iwlog.h" 66 #include "iwp.h" 67 #include "iwdlsnr.h" 68 69 IW_EXTERN_C_START 70 71 /** File open mode */ 72 typedef uint8_t iwfs_omode; 73 /** Open file as a reader.*/ 74 #define IWFS_OREAD ((iwfs_omode) 0x01U) 75 /** Open file as a writer. */ 76 #define IWFS_OWRITE ((iwfs_omode) 0x02U) 77 /** If file is missing it will be created on open. */ 78 #define IWFS_OCREATE ((iwfs_omode) 0x04U) 79 /** Truncate file on open. */ 80 #define IWFS_OTRUNC ((iwfs_omode) 0x08U) 81 /** Unlink(delete) file on close */ 82 #define IWFS_OUNLINK ((iwfs_omode) 0x10U) 83 /** Temp file will be created, in this case specified file name will act as temp file name prefix */ 84 #define IWFS_OTMP ((iwfs_omode) 0x20U) 85 86 /** Status of an open file operation */ 87 typedef uint8_t iwfs_openstatus; 88 /** Open failed. */ 89 #define IWFS_OPEN_FAIL ((iwfs_openstatus) 0x00U) 90 /** Open success, new file've been created. */ 91 #define IWFS_OPEN_NEW ((iwfs_openstatus) 0x01U) 92 /** Open success, existing file've been opened. */ 93 #define IWFS_OPEN_EXISTING ((iwfs_openstatus) 0x02U) 94 95 /** Sync file data options */ 96 typedef uint8_t iwfs_sync_flags; 97 #define IWFS_SYNCDEFAULT ((iwfs_sync_flags) 0x00U) 98 #define IWFS_FDATASYNC ((iwfs_sync_flags) 0x01U) 99 100 #define IWFS_DEFAULT_OMODE (IWFS_OCREATE) 101 #define IWFS_DEFAULT_LOCKMODE (IWP_NOLOCK) 102 #define IWFS_DEFAULT_FILEMODE \ 103 00666 /**< Default permission of created files */ 104 105 /** 106 * @brief `IWFS_FILE` file options. 107 * @see iwrc iwfs_file_open(IWFS_FILE *f, const IWFS_FILE_OPTS *opts) 108 */ 109 typedef struct { 110 const char *path; /**< Required file path. */ 111 iwfs_omode omode; /**< File open mode. */ 112 iwp_lockmode lock_mode; /**< File locking mode. */ 113 /**< Specifies the permissions to use in case a new file is created, 114 `int open(const char *pathname, int flags, mode_t mode)` */ 115 int filemode; 116 IWDLSNR *dlsnr; /**< Optional data listener */ 117 } IWFS_FILE_OPTS; 118 119 /** 120 * @brief `IWFS_FILE` file state info. 121 * @see IWFS_FILE::state 122 */ 123 typedef struct { 124 int is_open; /**< `1` if file in open state */ 125 iwfs_openstatus ostatus; /**< File open status. */ 126 IWFS_FILE_OPTS opts; /**< File open options. */ 127 HANDLE fh; /**< File handle */ 128 } IWFS_FILE_STATE; 129 130 /** 131 * @struct IWFS_FILE 132 * @brief Simple file implementation. 133 */ 134 typedef struct IWFS_FILE { 135 void *impl; /**< Implementation specific data */ 136 137 /** 138 * @brief Write @a buf bytes into the file 139 * 140 * @param f `struct IWFS_FILE` pointer 141 * @param off Offset from start of the file where bytes will write. 142 * @param buf Buffer to write. 143 * @param siz Number of bytes to write. 144 * @param [out] sp Number of bytes actually written 145 * @return `0` on success or error code. 146 */ 147 iwrc (*write)(struct IWFS_FILE *f, off_t off, const void *buf, size_t siz, size_t *sp); 148 149 /** 150 * @brief Read @a siz bytes into @a buf at the specified offset @a off 151 * 152 * @param f `struct IWFS_FILE` pointer. 153 * @param off Offset from start of the file. 154 * @param buf Buffer to read into. 155 * @param siz Number of bytes to read. 156 * @param [out] sp Number of bytes actually read. 157 * @return `0` on success or error code. 158 */ 159 iwrc (*read)(struct IWFS_FILE *f, off_t off, void *buf, size_t siz, size_t *sp); 160 161 /** 162 * @brief Closes this file. 163 * @return `0` on success or error code. 164 */ 165 iwrc (*close)(struct IWFS_FILE *f); 166 167 /** 168 * @brief Sync file data with fs. 169 * @param f `struct IWFS_FILE` pointer. 170 * @param opts File sync options. 171 */ 172 iwrc (*sync)(struct IWFS_FILE *f, iwfs_sync_flags flags); 173 174 /** 175 * @brief Return current file state. 176 * @param f `struct IWFS_FILE` pointer. 177 * @param [out] state File state placeholder. 178 * @return `0` on success or error code. 179 * 180 * @see struct IWFS_FILE_STATE 181 */ 182 iwrc (*state)(struct IWFS_FILE *f, IWFS_FILE_STATE *state); 183 184 /** 185 * @brief Copy data within a file 186 * @param f `struct IWFS_FILE` pointer. 187 * @param off Data offset 188 * @param siz Data size 189 * @param noff New data offset 190 */ 191 iwrc (*copy)(struct IWFS_FILE *f, off_t off, size_t siz, off_t noff); 192 } IWFS_FILE; 193 194 /** 195 * @brief Open file and initialize a given @a f structure. 196 * 197 * <strong>File open options:</strong> 198 * @code {.c} 199 * opts = { 200 * .path = "file path", //File path. This options value is requied. 201 * .omode = ..., //File open mode. 202 * // Default: `IWFS_DEFAULT_OMODE` 203 * .lock_mode = ..., //File locking mode acquired by process opened this file. 204 * // Default: `IWP_NOLOCK` 205 * .filemode = .. //Specifies the permissions to use in case a new file is created. 206 * // Default: `00644` 207 * } 208 * @endcode 209 * 210 * @param f `struct IWFS_FILE` pointer. 211 * @param opts [in] File open options 212 * @return `0` on success or error code. 213 * @relatesalso IWFS_FILE 214 */ 215 IW_EXPORT WUR iwrc iwfs_file_open(IWFS_FILE *f, const IWFS_FILE_OPTS *opts); 216 217 /** 218 * @brief Init `iwfile` submodule. 219 */ 220 IW_EXPORT WUR iwrc iwfs_file_init(void); 221 222 IW_EXTERN_C_END 223 #endif 224