versadac  1
versadac - Scalable Recorder Firmware
am_historystream.h
1 /*****************************************************************************
2 FILE : am_historystream.h
3 VERSION : $Id: am_historystream.h 4938 2006-10-10 14:20:18Z martinto $
4 AUTHOR : Sandra Herring
5 SYSTEM : GNU C++ for Power PC
6 DESCRIPTION : Utility functions for reading in a binary archive (UHH) file.
7 *****************************************************************************/
8 
9 #if !defined(__AM_HISTORYSTREAM_H)
10 #define __AM_HISTORYSTREAM_H
11 
12 #include "stdtypes.h"
13 #include <stdio.h>
14 
15 
16 
17 // *********************************************************************
18 //
19 // Archive File Stream
20 //
21 // *********************************************************************
22 
24 {
25  public:
26  static const sint32 READ_OK;
27  static const sint32 HISTORY_EOF;
28  static const sint32 CHECKSUM_ERR;
29  static const sint32 FORMAT_ERR;
30  static const sint32 OUTPUT_ERR;
31  static const sint32 OUTPUT_FULL_ERR;
32  static const sint32 OUT_OF_MEMORY;
33  static const sint32 CANCELLED;
34 
35 /*---------------------------------------------------------------------------
36 FUNCTION : AM_HistoryStream C O N S T R U C T O R
37 DESCRIPTION :
38 ARGUMENTS : Archive file input stream.
39 RETURN : N/A
40 NOTES :
41 ---------------------------------------------------------------------------*/
42  AM_HistoryStream( FILE * fp );
43 
44 /*---------------------------------------------------------------------------
45 FUNCTION : AM_HistoryStream getUHHSequenceNumber
46 DESCRIPTION : Gets the UHH sequence number previously set by setUHHSequenceNumber
47  or 0 if not set.
48 ARGUMENTS : none.
49 RETURN : sequence number
50 NOTES :
51 ---------------------------------------------------------------------------*/
52  uint8 getUHHSequenceNumber();
53 
54 /*---------------------------------------------------------------------------
55 FUNCTION : AM_HistoryStream getChecksum
56 DESCRIPTION : Returns the calculated checksum for the current point in the input.
57 ARGUMENTS : none.
58 RETURN : Stream checksum
59 NOTES :
60 ---------------------------------------------------------------------------*/
61  uint16 getChecksum();
62 
63 /*---------------------------------------------------------------------------
64 FUNCTION : AM_HistoryStream isBigEndian
65 DESCRIPTION : service to get the platform numeric endian-ness
66 ARGUMENTS : None.
67 RETURN : TRUE if big endian.
68 NOTES :
69 ---------------------------------------------------------------------------*/
70  bool isBigEndian();
71 
72 /*---------------------------------------------------------------------------
73 FUNCTION : AM_HistoryStream numericRead
74 DESCRIPTION : A set of functions for reading binary values into integral
75  and floating types
76  The values of all bytes read in are added to the stream checksum.
77 ARGUMENTS : value - reference to variable to receive value.
78 RETURN : None
79 NOTES : Bytes will be reordered if necessary.
80  Note that sint8 and uint8 are actually char types.
81 ---------------------------------------------------------------------------*/
82  sint32 numericRead ( double& value );
83  sint32 numericRead ( float& value );
84  sint32 numericRead ( sint8& value );
85  sint32 numericRead ( sint16& value );
86  sint32 numericRead ( sint32& value );
87  sint32 numericRead ( uint8& value );
88  sint32 numericRead ( uint16& value );
89  sint32 numericRead ( uint32& value );
90 
91 /*---------------------------------------------------------------------------
92 FUNCTION : AM_HistoryStream putback
93 DESCRIPTION : service put an item back into the stream. Note that this may
94  be an int > 0xff as it may be a metabyte value.
95 ARGUMENTS : metabyte value
96 RETURN : none
97 NOTES :
98 ---------------------------------------------------------------------------*/
99  void putback( uint16 metabyte );
100 
101 /*---------------------------------------------------------------------------
102 FUNCTION : AM_HistoryStream read
103 DESCRIPTION : Method to read in specified number of bytes.
104  The value of all bytes read in are added to the stream checksum.
105 ARGUMENTS : none.
106 RETURN :
107 NOTES : Must not be used if a control metabyte is expected. If one is
108  found then UHH_FORMAT_ERR will be returned.
109 ---------------------------------------------------------------------------*/
110  sint32 read( uint8 *location, uint16 count );
111 
112 /*---------------------------------------------------------------------------
113 FUNCTION : AM_HistoryStream readMetabyte
114 DESCRIPTION : reads a char or, possibly a pair of chars and returns
115  the byte or metabyte value
116 ARGUMENTS :
117 RETURN : Metabyte value
118 NOTES : This will be a value > ff for control values
119 ---------------------------------------------------------------------------*/
120  sint32 readMetabyte();
121 
122 /*---------------------------------------------------------------------------
123 FUNCTION : AM_HistoryStream readUintf
124 DESCRIPTION : reads a variable length integer from uhh format file
125 ARGUMENTS :
126 RETURN : Metabyte value
127 NOTES :
128 ---------------------------------------------------------------------------*/
129  sint32 readUintf( uint32 &dest );
130 
131 /*------------------------------------------------------------------------------
132 FUNCTION : AM_HistoryStream readFloat64n
133 DESCRIPTION :
134 ARGUMENTS : stream : pointer to open archive file stream.
135 RETURN : TRUE if data read in successfully, otherwise FALSE.
136 NOTES :
137 ------------------------------------------------------------------------------*/
138  sint32 readFloat64n( double * pDouble,
139  uint8 numBytes );
140 
141 /*------------------------------------------------------------------------------
142 FUNCTION : AM_HistoryStream readFloat32n
143 DESCRIPTION :
144 ARGUMENTS : stream : pointer to open archive file stream.
145 RETURN : TRUE if data read in successfully, otherwise FALSE.
146 NOTES :
147 ------------------------------------------------------------------------------*/
148  sint32 readFloat32n( float * pFloat,
149  uint8 numBytes );
150 
151 /*---------------------------------------------------------------------------
152 FUNCTION : AM_HistoryStream seedChecksum
153 DESCRIPTION : service to reset the 16-bit checksum accumulator
154 ARGUMENTS : None.
155 RETURN : None.
156 NOTES :
157 ---------------------------------------------------------------------------*/
158  void seedChecksum();
159 
160 /*------------------------------------------------------------------------------
161 FUNCTION : AM_HistoryStream setFp
162 DESCRIPTION : service to attach to an input stream.
163 ARGUMENTS : stream handle.
164 RETURN : None.
165 NOTES :
166 ------------------------------------------------------------------------------*/
167  void setFp( FILE * fp );
168 
169 /*---------------------------------------------------------------------------
170 FUNCTION : AM_HistoryStream setUHHSequenceNumber
171 DESCRIPTION : Sets the UHH sequence number
172 ARGUMENTS : sequence number.
173 RETURN :
174 NOTES :
175 ---------------------------------------------------------------------------*/
176  void setUHHSequenceNumber( uint8 UHHSequenceNumber );
177 
178 /*---------------------------------------------------------------------------
179 FUNCTION : AM_HistoryStream setChecksum
180 DESCRIPTION : Overrides the calculated checksum for the current point in the input.
181 ARGUMENTS : New checksum.
182 RETURN : None.
183 NOTES : Used when the caller wants to return to an earlier file position.
184 ---------------------------------------------------------------------------*/
185  void setChecksum( uint16 checksum );
186 
187 /*---------------------------------------------------------------------------
188 FUNCTION : AM_HistoryStream stringRead
189 DESCRIPTION : Function for reading null terminated string in binary mode
190  The values of all bytes read in are added to the stream checksum.
191 ARGUMENTS : stringPtr - pointer to location to receive string.
192  count - max number of chars including null
193 RETURN : None
194 NOTES : If count is reached without a null then the last char of the
195  string is set to a null and the stream state is set to bad.
196 ---------------------------------------------------------------------------*/
197  sint32 stringRead( char *stringPtr, uint16 count );
198 
199 /*---------------------------------------------------------------------------
200 FUNCTION : AM_HistoryStream stringReadUnicode
201 DESCRIPTION : Function for reading null terminated unicode string
202  The values of all bytes read in are added to the stream checksum.
203 ARGUMENTS : stringPtr - pointer to location to receive string.
204  count - max number of chars including null - ie size of buffer in words
205  pActual - optional, pointer to where to put number of characters
206  read from stream.
207 RETURN : None
208 NOTES : If count is reached without a null then the last char of the
209  string is set to a null and the stream state is set to bad.
210 ---------------------------------------------------------------------------*/
211  sint32 stringReadUnicode( char *stringPtr, uint16 count, uint16 *pActual = NULL );
212 
213 /*---------------------------------------------------------------------------
214 FUNCTION : AM_HistoryStream readTicks
215 DESCRIPTION : Function for reading in a variable length tick value
216 ARGUMENTS : pdVal - pointer to return value
217 RETURN : read status
218 NOTES :
219 ---------------------------------------------------------------------------*/
220  sint32 readTicks( double &value );
221 
222 /*---------------------------------------------------------------------------
223 FUNCTION : AM_HistoryStream verifyChecksum
224 DESCRIPTION : service to read the checksum from the stream and check that it
225  is correct
226 ARGUMENTS : none.
227 RETURN : TRUE if verifies ok, else false
228 NOTES :
229 ---------------------------------------------------------------------------*/
230  sint32 verifyChecksum();
231 
232 /*---------------------------------------------------------------------------
233 FUNCTION : AM_HistoryStream tell
234 DESCRIPTION : service to provide the current offset into the file
235 ARGUMENTS : none.
236 RETURN : offset
237 NOTES :
238 ---------------------------------------------------------------------------*/
239  long tell();
240 
241 /*---------------------------------------------------------------------------
242 FUNCTION : AM_HistoryStream seek
243 DESCRIPTION : service to set the current offset into the file
244 ARGUMENTS : position desired.
245 RETURN : None.
246 NOTES :
247 ---------------------------------------------------------------------------*/
248  sint32 seek( uint32 pos )
249  { m_bPutback = FALSE; return fseek(m_fp, pos, SEEK_SET); }
250 
251  private:
252  uint16 csumForMetabyte( uint16 metabyte );
253  sint32 readAndOrder( uint8 *location, uint16 count );
254 
255  FILE * m_fp;
256  uint16 m_putbackBuffer;
257  uint16 m_csum;
258  uint8 m_UHHSequenceNumber; // sequence number from uhh file start record, or 0
259  sint8 m_Translation;
260  bool m_bPutback; // indicates metabyte in putback buffer
261  bool m_bBigEndian; // Endian-ness
262 
263 }; // class AM_HistoryStream
264 
265 
266 // ***********************************************
267 // inline services for class AM_HistoryStream
268 // ***********************************************
269 
270 /*---------------------------------------------------------------------------
271 FUNCTION : AM_HistoryStream getUHHSequenceNumber
272 DESCRIPTION : Gets the UHH sequence number previously set by setUHHSequenceNumber
273  or 0 if not set.
274 ARGUMENTS : none.
275 RETURN : sequence number
276 NOTES :
277 ---------------------------------------------------------------------------*/
278 inline uint8 AM_HistoryStream::getUHHSequenceNumber()
279 {
280  return m_UHHSequenceNumber;
281 }
282 
283 /*---------------------------------------------------------------------------
284 FUNCTION : AM_HistoryStream getChecksum
285 DESCRIPTION : Returns the calculated checksum for the current point in the input.
286 ARGUMENTS : none.
287 RETURN : Stream checksum
288 NOTES :
289 ---------------------------------------------------------------------------*/
290 inline uint16 AM_HistoryStream::getChecksum()
291 {
292  return m_csum;
293 }
294 
295 /*---------------------------------------------------------------------------
296 FUNCTION : AM_HistoryStream isBigEndian
297 DESCRIPTION : service to get the platform numeric endian-ness
298 ARGUMENTS : None.
299 RETURN : TRUE if big endian.
300 NOTES :
301 ---------------------------------------------------------------------------*/
302 inline bool AM_HistoryStream::isBigEndian()
303 {
304  return m_bBigEndian;
305 }
306 
307 /*---------------------------------------------------------------------------
308 FUNCTION : AM_HistoryStream seedChecksum
309 DESCRIPTION : service to reset the 16-bit checksum accumulator
310 ARGUMENTS : checksum seed value
311 RETURN : none.
312 NOTES :
313 ---------------------------------------------------------------------------*/
314 inline void AM_HistoryStream::seedChecksum()
315 {
316  // note that seed for uhh files is actually 43, this is coped with in verifyChecksum
317  m_csum = 42;
318 }
319 
320 /*---------------------------------------------------------------------------
321 FUNCTION : AM_HistoryStream setUHHSequenceNumber
322 DESCRIPTION : Sets the UHH sequence number
323 ARGUMENTS : sequence number.
324 RETURN :
325 NOTES :
326 ---------------------------------------------------------------------------*/
327 inline void AM_HistoryStream::setUHHSequenceNumber( uint8 UHHSequenceNumber )
328 {
329  m_UHHSequenceNumber = UHHSequenceNumber;
330 }
331 
332 /*---------------------------------------------------------------------------
333 FUNCTION : AM_HistoryStream setChecksum
334 DESCRIPTION : Overrides the calculated checksum for the current point in the input.
335 ARGUMENTS : New checksum.
336 RETURN : None.
337 NOTES : Used when the caller wants to return to an earlier file position.
338 ---------------------------------------------------------------------------*/
339 inline void AM_HistoryStream::setChecksum( uint16 checksum )
340 {
341  m_csum = checksum;
342 }
343 
344 /*------------------------------------------------------------------------------
345 FUNCTION : AM_HistoryStream setFp
346 DESCRIPTION : service to attach to an input stream.
347 ARGUMENTS : stream handle.
348 RETURN : None.
349 NOTES :
350 ------------------------------------------------------------------------------*/
351 inline void AM_HistoryStream::setFp( FILE * fp )
352 {
353  m_fp = fp;
354 }
355 
356 #endif // __AM_HISTORYSTREAM_H conditional
357 
Definition: am_historystream.h:23