1 /** 2 * @namespace biewlib 3 * @file biewlib/bbio.h 4 * @brief This file contains prototypes of BBIO technology functions. 5 * @version - 6 * @remark this source file is part of Binary vIEW project (BIEW). 7 * The Binary vIEW (BIEW) is copyright (C) 1995 Nickols_K. 8 * All rights reserved. This software is redistributable under the 9 * licence given in the file "Licence.en" ("Licence.ru" in russian 10 * translation) distributed in the BIEW archive. 11 * @note Requires POSIX compatible development system 12 * 13 * @author Nickols_K 14 * @since 1995 15 * @note Development, fixes and improvements 16 **/ 17 #ifndef __BBIO_H 18 #define __BBIO_H 1 19 20 #ifndef __BIEWLIB_H 21 #include "biewlib/biewlib.h" 22 #endif 23 /******************************************************************\ 24 * Buffered binary file streams input/output section * 25 * Helpful for read/write small size objects from/to file * 26 \******************************************************************/ 27 28 /** FORWARD: default (forward scan) 29 reposition of cache as 100% forward 30 from current file position */ 31 #define BIO_OPT_FORWARD 0x0000 32 #define BIO_OPT_DB BIO_OPT_FORWARD 33 /** RANDOM: middle scan 34 reposition of cache as 50% forward & 50% 35 backward from current file position */ 36 #define BIO_OPT_RANDOM 0x0001 37 /** BACKWARD: backward scan 38 reposition of cache as 100% backward 39 from current file position */ 40 #define BIO_OPT_BACKSCAN 0x0002 41 /** RANDOM FORWARD: reposition of cache as 90% forward 42 & 10% backward from current file position */ 43 #define BIO_OPT_RFORWARD 0x0003 44 /** RANDOM BACKWARD: reposition of cache as 10% forward 45 & 90% backward from current file position */ 46 #define BIO_OPT_RBACKSCAN 0x0004 47 #define BIO_OPT_DIRMASK 0x000F /**< direction mask */ 48 #define BIO_OPT_USEMMF 0xFFFF /**< Use mmf instead buffering i/o. This covers all optimizations */ 49 #define BIO_OPT_NOCACHE 0x8000 /**< disable cache */ 50 51 #define BIO_SEEK_SET SEEKF_START /**< specifies reference location from begin of file */ 52 #define BIO_SEEK_CUR SEEKF_CUR /**< specifies reference location from current position of file */ 53 #define BIO_SEEK_END SEEKF_END /**< specifies reference location from end of file */ 54 55 typedef void * BGLOBAL; /**< This is the data type used to represent buffered stream objects */ 56 57 /* 58 This struct is ordered as it documented in Athlon manual 59 Publication # 22007 Rev: D 60 */ 61 /** Virtual file buffer structure */ 62 typedef struct tagvfb 63 { 64 bhandle_t handle; /**< file handle */ 65 __filesize_t FBufStart; /**< logical position of mirror the buffer onto file */ 66 char * MBuffer; /**< NULL - not buffered i/o */ 67 unsigned MBufLen; /**< length data, actually contains in buffer */ 68 unsigned MBufSize; /**< real size of buffer */ 69 tBool updated; /**< True if buffer contains data, that not pesent in file */ 70 }vfb; 71 72 /** Memory mapped buffer structure */ 73 typedef struct tagmmb 74 { 75 mmfHandle mmf; /**< If OS support MMF contains handle of memory-mapped file */ 76 void * mmf_addr; /**< If OS support MMF contains base address of memory where file is mapped */ 77 }mmb; 78 79 typedef struct tagBFILE 80 { 81 __filesize_t FilePos; /**< current logical position in file */ 82 __filesize_t FLength; /**< real length of the file */ 83 char * FileName; /**< Real file name of opened file */ 84 unsigned openmode; /**< mode,that OsOpen this file */ 85 int optimize; /**< seek optimization */ 86 tBool is_mmf; /**< indicates that 'mmb' is used */ 87 tBool primary_mmf; /**< If this is set then we have not duplicated handle */ 88 union /**< cache subsystem */ 89 { 90 vfb vfb; /**< buffered file */ 91 mmb * mmb; /**< Pointer to memory mapped file. We must have pointer, but not object!!! It for bioDupEx */ 92 }b; 93 tBool is_eof; /**< Indicates EOF for buffering streams */ 94 }BFILE; 95 96 extern struct tagBFILE bNull; /**< Stream associated with STDERR */ 97 98 /** Opens existed file and buffered it 99 * @return handle of stream 100 * @param fname indicates name of file to be open 101 * @param openmode indicates opening mode flags - BIO_* 102 * @param buffSize indicates size of buffer. Value UINT_MAX indicates - buffering entire file. 103 * @note Returns bNull if opening is fail. 104 * @warning Carefully use parameter - buffSize. 105 * If you created new file with 0 bytes 106 * of length, and value of buffSize = 107 * UINT_MAX, then i/o will be unbuffered. 108 * It better to use values < UINT_MAX. 109 * Value UINT_MAX better to use for readonly 110 * operations for small files to load those into 111 * memory entire. 112 * @see bioClose 113 **/ 114 BGLOBAL __FASTCALL__ bioOpen(const char * fname,unsigned openmode,unsigned buffSize,unsigned optimization); 115 116 /** Changes size of opened file. 117 * @return True if operation was succesfully performed 118 * @param bioFile handle of opened stream 119 * @param newsize new size of file in bytes 120 * @warning If file is truncated, the data from 121 * the new end of file to the original 122 * end of the file are lost. 123 **/ 124 tBool __FASTCALL__ bioChSize(BGLOBAL bioFile,__filesize_t newsize); 125 126 /** Closes opened stream. 127 * @return True if operation was succesfully performed 128 * @param bioFile handle of opened stream 129 * @see bioOpen 130 **/ 131 tBool __FASTCALL__ bioClose(BGLOBAL bioFile); 132 133 /** Determines whether a opened stream has reached the End of File. 134 * @return True if EOF has reached 135 * @param bioFile handle of opened stream 136 **/ 137 tBool __FASTCALL__ bioEOF(BGLOBAL bioHandle); 138 139 /** Returns the length (in bytes) of file associated with opened stream. 140 * @return file length 141 * @param bioFile handle of opened stream 142 **/ 143 __filesize_t __FASTCALL__ bioFLength(BGLOBAL bioFile); 144 145 /** Flushes buffer onto disk. 146 * @return True if operation was succesfully performed 147 * @param bioFile handle of opened stream 148 * @note This operation performs automatically 149 * when bioClose is called and 150 * openmode == READWRITE || WRITE, or 151 * when bioSeek is called and logical 152 * file position is out of buffer. 153 * @see bioReRead 154 **/ 155 tBool __FASTCALL__ bioFlush(BGLOBAL bioFile); 156 157 /** Reads one byte from stream. 158 * @return Readed byte 159 * @param bioFile handle of opened stream 160 * @note Logical file position is 161 * incremented after operation. 162 * @see bioWriteByte bioReadWord bioReadDWord bioReadBuffer 163 **/ 164 tUInt8 __FASTCALL__ bioReadByte(BGLOBAL bioFile); 165 166 /** Reads two bytes from stream. 167 * @return Readed word 168 * @param bioFile handle of opened stream 169 * @note Logical file position is 170 * incremented after operation. 171 * @see bioWriteWord bioReadByte bioReadDWord bioReadBuffer 172 **/ 173 tUInt16 __FASTCALL__ bioReadWord(BGLOBAL bioFile); 174 175 /** Reads four bytes from stream. 176 * @return Readed double word 177 * @param bioFile handle of opened stream 178 * @note Logical file position is 179 * incremented after operation. 180 * @see bioWriteDWord bioReadByte bioReadWord bioReadBuffer 181 **/ 182 tUInt32 __FASTCALL__ bioReadDWord(BGLOBAL bioFile); 183 184 /** Reads 8 bytes from stream. 185 * @return Readed double word 186 * @param bioFile handle of opened stream 187 * @note Logical file position is 188 * incremented after operation. 189 * @see bioWriteDWord bioReadByte bioReadWord bioReadBuffer 190 **/ 191 tUInt64 __FASTCALL__ bioReadQWord(BGLOBAL bioFile); 192 193 /** Reads specified number of bytes from stream. 194 * @return True if operation was succesfully performed 195 * @param bioFile handle of opened stream 196 * @param buffer specifies buffer, where readed information will be stored 197 * @param cbBuffer specifies size of buffer 198 * @note Function increments logical file 199 * position by the number of bytes read. 200 * @see bioWriteBuffer bioReadByte bioReadWord bioReadByte 201 **/ 202 tBool __FASTCALL__ bioReadBuffer(BGLOBAL bioFile,void * buffer,unsigned cbBuffer); 203 204 /** Rereads opened file from disk. 205 * @return True if operation was succesfully performed 206 * @param bioFile handle of opened stream 207 * @see bioFlush 208 **/ 209 tBool __FASTCALL__ bioReRead(BGLOBAL bioFile); 210 211 /** Positions logical file pointer at the specified position. 212 * @return True if operation was succesfully performed 213 * @param bioFile handle of opened stream 214 * @param offset specifies new offset of file pointer 215 * @param origin specifies reference location from which offset will be computed 216 * @see bioTell BIO_SEEK_SET BIO_SEEK_CUR BIO_SEEK_END 217 **/ 218 tBool __FASTCALL__ bioSeek(BGLOBAL bioFile,__fileoff_t offset,int origin); 219 220 /** Returns current optimization of buffering. 221 * @return optimization (BIO_OPT_*) 222 * @param bioFile handle of opened stream 223 * @see bioSetOptimization 224 **/ 225 unsigned __FASTCALL__ bioGetOptimization(BGLOBAL bioFile); 226 227 /** Sets new optimization of buffering and returns previous. 228 * @return optimization (BIO_OPT_*) 229 * @param bioFile handle of opened stream 230 * @see bioGetOptimization 231 **/ 232 unsigned __FASTCALL__ bioSetOptimization(BGLOBAL bioFile,unsigned flags); 233 234 /** Returns logical file position of opened stream. 235 * @return offset from begin of file 236 * @param bioFile handle of opened stream 237 * @see bioSeek 238 **/ 239 __filesize_t __FASTCALL__ bioTell(BGLOBAL bioFile); 240 241 /** Writes one byte to stream. 242 * @return True if operation was succesfully performed 243 * @param bioFile handle of opened stream 244 * @param bVal Byte to be written 245 * @note Logical file position is 246 * incremented after operation. 247 * @see bioReadByte bioWriteWord bioWriteWord bioWriteBuffer 248 **/ 249 tBool __FASTCALL__ bioWriteByte(BGLOBAL bioFile,tUInt8 bVal); 250 251 /** Writes two bytes to stream. 252 * @return True if operation was succesfully performed 253 * @param bioFile handle of opened stream 254 * @param wVal Word to be written 255 * @note Logical file position is 256 * incremented after operation. 257 * @see bioReadWord bioWriteWord bioWriteWord bioWriteBuffer 258 **/ 259 tBool __FASTCALL__ bioWriteWord(BGLOBAL bioFile,tUInt16 wVal); 260 261 /** Writes four bytes to stream. 262 * @return True if operation was succesfully performed 263 * @param bioFile handle of opened stream 264 * @param dwVal Double word to be written 265 * @note Logical file position is 266 * incremented after operation. 267 * @see bioReadDWord bioWriteWord bioWriteWord bioWriteBuffer 268 **/ 269 tBool __FASTCALL__ bioWriteDWord(BGLOBAL bioFile,tUInt32 dwVal); 270 271 /** Writes 8 bytes to stream. 272 * @return True if operation was succesfully performed 273 * @param bioFile handle of opened stream 274 * @param dwVal Double word to be written 275 * @note Logical file position is 276 * incremented after operation. 277 * @see bioReadDWord bioWriteWord bioWriteWord bioWriteBuffer 278 **/ 279 tBool __FASTCALL__ bioWriteQWord(BGLOBAL bioFile,tUInt64 dwVal); 280 281 /** Writes specified number of bytes opened to stream. 282 * @return True if operation was succesfully performed 283 * @param bioFile handle of opened stream 284 * @param buffer specifies buffer to be written 285 * @param cbBuffer specifies size of buffer 286 * @note Function increments logical file 287 * position by the number of bytes writed. 288 * @see bioReadBuffer bioWriteWord bioWriteWord bioByte 289 **/ 290 tBool __FASTCALL__ bioWriteBuffer(BGLOBAL bioFile,const void * buffer,unsigned cbBuffer); 291 292 /** Returns name of file associated with opened stream. 293 * @return name of file 294 * @param bioFile handle of opened stream 295 **/ 296 char * __FASTCALL__ bioFileName(BGLOBAL bioFile); 297 298 /** Causes opened stream to be duplicated. 299 * @return handle of duplicted stream 300 * @param bioFile handle of opened stream 301 * @note function duplicates OS handle 302 * of stream and buffer with all 303 * characteristics. 304 * @see bioDupEx 305 **/ 306 BGLOBAL __FASTCALL__ bioDup(BGLOBAL bioFile); 307 308 /** Causes opened stream to be duplicated. 309 * @return handle of duplicted stream 310 * @param bioFile handle of opened stream 311 * @param buffSize specifies new size of buffer to be used with duplicated stream 312 * @note function duplicates OS handle 313 * of stream and buffer with all 314 * possible characteristics. 315 * @see bioDup 316 **/ 317 BGLOBAL __FASTCALL__ bioDupEx(BGLOBAL bioFile,unsigned buffSize); 318 319 /** Returns low-level OS handle of opened stream. 320 * @return OS handle of opened stream 321 * @param bioFile handle of opened stream 322 **/ 323 bhandle_t __FASTCALL__ bioHandle(BGLOBAL bioFile); 324 325 /** Returns pointer to buffer of opened stream. 326 * @return pointer to buffer 327 * @param bioFile handle of opened stream 328 * @note This function allowes direct 329 * access to file cache. 330 * @see bioBuffLen bioBuffPos 331 **/ 332 void * __FASTCALL__ bioBuffer(BGLOBAL bioFile); 333 334 /** Returns length of opened stream buffer. 335 * @return length of buffer 336 * @param bioFile handle of opened stream 337 * @note This function allowes direct 338 * access to file cache. 339 * @see bioBuff bioBuffPos 340 **/ 341 unsigned __FASTCALL__ bioBuffLen(BGLOBAL bioFile); 342 343 /** Returns logical buffer position. 344 * @return length of buffer 345 * @param bioFile handle of opened stream 346 * @note This function allowes direct 347 * access to file cache. 348 * @warning Logical buffer position is not 349 * logical file position. 350 * @see bioBuff bioBuffLen 351 **/ 352 unsigned __FASTCALL__ bioBuffPos(BGLOBAL bioFile); 353 354 #endif 355 356