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