CCSDS_istream.h File Reference

CCSDS input stream (reader) interface. More...

#include <QSD/CCSDS_telemetryPrint.h>

Classes
struct	_CCSDS_istreamCsb
	The stream's completion status block. This contains more detailed information about why processing was stopped. More...
Typedefs
typedef struct _CCSDS_istream	CCSDS_istream
	Typedef for struct _CCSDS_istream.
typedef enum _CCSDS_ISTREAM_SIV_S	CCSDS_ISTREAM_SIV_S
	Typedef for CCSDS_ISTREAM_SIV_S.
typedef enum _CCSDS_ISTREAM_SIV_V	CCSDS_ISTREAM_SIV_V
	Typedef for CCSDS_ISTREAM_SIV_V.
typedef enum _CCSDS_ISTREAM_SIV_M	CCSDS_ISTREAM_SIV_M
	Typedef for CCSDS_ISTREAM_SIV_M.
typedef enum _CCSDS_ISTREAM_PKT_STATE_K	CCSDS_ISTREAM_PKT_STATE_K
	Typedef for enum _CCSDS_ISTREAM_PKT_STATE_K.
typedef enum _CCSDS_ISTREAM_SIV_K	CCSDS_ISTREAM_SIV_K
	Typedef for enum _CCSDS_ISTREAM_SIV_K.
typedef enum _CCSDS_ISTREAM_PKT_CHECK_OPTS_M	CCSDS_ISTREAM_PKT_CHECK_OPTS_M
	Typedef for CCSDS_ISTREAM_PKT_CHECK_OPTS_M.
typedef int(*	CCSDS_istreamReader )(void *prm, void *buf, int nbytes, int pbytes)
	Routine to read the specified number of bytes from the input stream.
typedef int(*	CCSDS_istreamTeller )(void const *prm)
	Routine to give the current position in the stream. As an example, for files, this will do an ftell.
typedef int(*	CCSDS_istreamCloser )(void *prm)
	Routine to read the specified number of bytes from the input stream.
typedef int(*	CCSDS_istreamResolver )(void *ctx, CCSDS_telemetry const *pkt, CCSDS_apidDsc **dsc)
	User callback to CCSDS_istreamProcess that resolves an apid to its controlling APID descriptor.
typedef struct _CCSDS_istreamCsb	CCSDS_istreamCsb
	Typedef for struct _CCSDS_istreamCsb.
Enumerations
enum	_CCSDS_ISTREAM_SIV_S {   CCSDS_ISTREAM_SIV_S_SEQGAP = 16,   CCSDS_ISTREAM_SIV_S_PRV_FIRST = 1,   CCSDS_ISTREAM_SIV_S_PRV_LAST = 1,   CCSDS_ISTREAM_SIV_S_PRV = 2,   CCSDS_ISTREAM_SIV_S_CUR_FIRST = 1,   CCSDS_ISTREAM_SIV_S_CUR_LAST = 1,   CCSDS_ISTREAM_SIV_S_CUR = 2,   CCSDS_ISTREAM_SIV_S_RSVD_20 = 1,   CCSDS_ISTREAM_SIV_S_RSVD_21 = 1,   CCSDS_ISTREAM_SIV_S_RSVD_22 = 1,   CCSDS_ISTREAM_SIV_S_RSVD_23 = 1,   CCSDS_ISTREAM_SIV_S_ERR = 8,   CCSDS_ISTREAM_SIV_S_ERR_EOS = 1,   CCSDS_ISTREAM_SIV_S_ERR_RDHDR = 1,   CCSDS_ISTREAM_SIV_S_ERR_BADHDR = 1,   CCSDS_ISTREAM_SIV_S_ERR_SEQ = 1,   CCSDS_ISTREAM_SIV_S_ERR_SEQNUM = 1,   CCSDS_ISTREAM_SIV_S_ERR_RDDAT = 1,   CCSDS_ISTREAM_SIV_S_ERR_OVRRUN = 1,   CCSDS_ISTREAM_SIV_S_ERR_SUMMARY = 1 }
	State Information Vector, bit field sizes. More...
enum	_CCSDS_ISTREAM_SIV_V {   CCSDS_ISTREAM_SIV_V_SEQGAP = 0,   CCSDS_ISTREAM_SIV_V_PRV_FIRST = 16,   CCSDS_ISTREAM_SIV_V_PRV_LAST = 17,   CCSDS_ISTREAM_SIV_V_PRV = 16,   CCSDS_ISTREAM_SIV_V_CUR_FIRST = 18,   CCSDS_ISTREAM_SIV_V_CUR_LAST = 19,   CCSDS_ISTREAM_SIV_V_CUR = 18,   CCSDS_ISTREAM_SIV_V_RSVD_20 = 20,   CCSDS_ISTREAM_SIV_V_RSVD_21 = 21,   CCSDS_ISTREAM_SIV_V_RSVD_22 = 22,   CCSDS_ISTREAM_SIV_V_RSVD_23 = 23,   CCSDS_ISTREAM_SIV_V_ERR = 24,   CCSDS_ISTREAM_SIV_V_ERR_EOS = 24,   CCSDS_ISTREAM_SIV_V_ERR_RDHDR = 25,   CCSDS_ISTREAM_SIV_V_ERR_BADHDR = 26,   CCSDS_ISTREAM_SIV_V_ERR_SEQ = 27,   CCSDS_ISTREAM_SIV_V_ERR_SEQNUM = 28,   CCSDS_ISTREAM_SIV_V_ERR_RDDAT = 29,   CCSDS_ISTREAM_SIV_V_ERR_OVRRUN = 30,   CCSDS_ISTREAM_SIV_V_ERR_SUMMARY = 31 }
	State Information Vector, right justified bit field offsets. More...
enum	_CCSDS_ISTREAM_SIV_M {   CCSDS_ISTREAM_SIV_M_SEQGAP,   CCSDS_ISTREAM_SIV_M_PRV_FIRST,   CCSDS_ISTREAM_SIV_M_PRV_LAST,   CCSDS_ISTREAM_SIV_M_PRV,   CCSDS_ISTREAM_SIV_M_CUR_FIRST,   CCSDS_ISTREAM_SIV_M_CUR_LAST,   CCSDS_ISTREAM_SIV_M_CUR,   CCSDS_ISTREAM_SIV_M_RSVD_20,   CCSDS_ISTREAM_SIV_M_RSVD_21,   CCSDS_ISTREAM_SIV_M_RSVD_22,   CCSDS_ISTREAM_SIV_M_RSVD_23,   CCSDS_ISTREAM_SIV_M_ERR_EOS,   CCSDS_ISTREAM_SIV_M_ERR_RDHDR,   CCSDS_ISTREAM_SIV_M_ERR_BADHDR,   CCSDS_ISTREAM_SIV_M_ERR_SEQ,   CCSDS_ISTREAM_SIV_M_ERR_SEQNUM,   CCSDS_ISTREAM_SIV_M_ERR_RDDAT,   CCSDS_ISTREAM_SIV_M_ERR_OVRRUN,   CCSDS_ISTREAM_SIV_M_ERR_SUMMARY,   CCSDS_ISTREAM_SIV_M_ERR,   CCSDS_ISTREAM_SIV_M_ERR_SYNCH }
	State Information Vector, in place mask. More...
enum	_CCSDS_ISTREAM_PKT_STATE_K {   CCSDS_ISTREAM_PKT_STATE_K_MID = 0,   CCSDS_ISTREAM_PKT_STATE_K_FIRST = 1,   CCSDS_ISTREAM_PKT_STATE_K_LAST = 2,   CCSDS_ISTREAM_PKT_STATE_K_ONLY = 3 }
	Enumerates the values of a packet's state. More...
enum	_CCSDS_ISTREAM_SIV_K {   CCSDS_ISTREAM_SIV_K_PRV_ONLY,   CCSDS_ISTREAM_SIV_K_PRV_FIRST,   CCSDS_ISTREAM_SIV_K_PRV_MID,   CCSDS_ISTREAM_SIV_K_PRV_LAST,   CCSDS_ISTREAM_SIV_K_CUR_ONLY,   CCSDS_ISTREAM_SIV_K_CUR_FIRST,   CCSDS_ISTREAM_SIV_K_CUR_MID,   CCSDS_ISTREAM_SIV_K_CUR_LAST }
	Enumerates the values of in place fields of the SIV word. These are all convenience symbols, all being derived from previously defined symbols. More...
enum	_CCSDS_ISTREAM_PKT_CHECK_OPTS_M {   CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NORESYNCH = 1 << 0,   CCSDS_ISTREAM_PKT_CHECK_OPTS_M_PRINT_HDR = 1 << 4,   CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SYNCH_ERR = 1 << 8,   CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SIV_ERR = 1 << 9 }
	Options, in the form of bit masks, for the precanned CCSDS_istream packet checker routine. More...
enum	_CCSDS_ISTREAM_RESOLVER_STATUS_K {   CCSDS_ISTREAM_RESOLVER_STATUS_K_SUCCESS = 0,   CCSDS_ISTREAM_RESOLVER_STATUS_K_IGNORE = 1,   CCSDS_ISTREAM_RESOLVER_STATUS_K_NOTFOUND = 2,   CCSDS_ISTREAM_RESOLVER_STATUS_K_STOP = 3 }
	Permitted return values of the CCSDS APID resolver routine. More...
enum	_CCSDS_ISTREAM_STATUS_K {   CCSDS_ISTREAM_STATUS_K_IO_READ_ERROR = -5,   CCSDS_ISTREAM_STATUS_K_PACKET_ERROR = -4,   CCSDS_ISTREAM_STATUS_K_IO_SKIP_ERROR = -3,   CCSDS_ISTREAM_STATUS_K_VERIFY_ERROR = -2,   CCSDS_ISTREAM_STATUS_K_IO_HEADER_ERROR = -1,   CCSDS_ISTREAM_STATUS_K_EOS = 0,   CCSDS_ISTREAM_STATUS_K_RESOLVER_STOP = 1,   CCSDS_ISTREAM_STATUS_K_CHECKER_STOP = 2,   CCSDS_ISTREAM_STATUS_K_PROCESSOR_STOP = 3 }
	Enumerates the return status codes. More...
Functions
int	CCSDS_istreamSizeof (void)
	Returns the size, in bytes, of a CCSDS_istream structure.
CCSDS_istream *	CCSDS_istreamNew (void)
	Convenience function to allocate and initialize a CCSDS_istream control structure.
int	CCSDS_istreamConstruct (CCSDS_istream *istream)
	Constructs (initializes) a previously uninitialized CCSDS_istream control structure.
int	CCSDS_istreamConnect (CCSDS_istream *istream, void *prm, CCSDS_istreamReader read, CCSDS_istreamCloser close, CCSDS_istreamTeller tell)
	Connects a read mechanism with the specified stream.
int	CCSDS_istreamDatAdvance (CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Advances past the current CCSDS data payload with reading the data into the buffer. All integrity checks are preformed. This in contrast with calling CCSDS_istreamDatRead with a NULL descriptor.
int	CCSDS_istreamHdrRead (CCSDS_istream *istream, CCSDS_telemetry *packet)
	Reads the CCSDS header.
int	CCSDS_istreamDatRead (CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Reads the current CCSDS data payload into the buffer specified by dsc.
int	CCSDS_istreamPktCheck (unsigned int opts, CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Precanned CCSDS_istreamProcess callback routine to check the integrity of a CCSDS packet.
int	CCSDS_istreamPktResynch (CCSDS_istream *istream, CCSDS_telemetry const *packet, CCSDS_apidDsc *dsc)
	Routine to recover from an APID sequence number or sequence state (first, middle, last) packet error. It can be used part of the CCSDS_istreamProcess packer checker routine.
int	CCSDS_istreamFileOpen (CCSDS_istream *istream, char const *filename, unsigned int options, unsigned char *buf, unsigned int buf_size)
	Convenience function to construct a CCSDS_istream to read from the specified named file filename.
unsigned int	CCSDS_istreamTell (CCSDS_istream const *istream)
	Returns the current byte offset into the stream.
int	CCSDS_istreamProcess (CCSDS_istream *stream, CCSDS_istreamCsb *csb, CCSDS_istreamResolver resolve_rtn, void *resolve_ctx)
	Processes a stream of CCSDS packets. The packets may be from multiple APIDs.
int	CCSDS_istreamClose (CCSDS_istream *istream)
	Closes the input stream associated with istream.
int	CCSDS_istreamDestroy (CCSDS_istream *istream)
	Destroys (i.e. returns the resources) associated with the stream.
void	CCSDS_istreamHdrPrint (CCSDS_telemetry const *packet)
	Prints a one-line summary of the CCSDS_istream header.
static __inline int	CCSDS_istreamSivConstruct (void)
	Initializes the State Information Vector to a known and beign state.
static __inline int	CCSDS_istreamSivCurFlags (int siv)
	Returns the flags associated with the current packet packet.
static __inline int	CCSDS_istreamSivPrvFlags (int siv)
	Returns the flags associated with the last previously read packet.
static __inline int	CCSDS_istreamSivIsError (int siv)
	Returns non-zero if State Information Vector, siv, is in error.
static __inline int	CCSDS_istreamSivIsResynchable (int siv)
	Returns non-zero if State Information Vector, siv, has a recoverable synchronization error.
static __inline int	CCSDS_istreamSivIsFirst (int siv)
	Returns non-zero if the current packet is the first packet, either alone or in a sequence.
static __inline int	CCSDS_istreamSivIsLast (int siv)
	Returns non-zero if the current packet is the last packet, either alone or in a sequence.
static __inline int	CCSDS_istreamSivIsMid (int siv)
	Returns non-zero if the current packet is the middle packet in a sequence.
static __inline int	CCSDS_istreamSivIsOnly (int siv)
	Returns non-zero if the current packet is the only packet, i.e. bare packet, not a member of a sequence.
static __inline int	CCSDS_istreamSivIoUpdate (int siv, unsigned int status)
	Updates the SIV according to the IO status.
static __inline int	CCSDS_istreamSivFlagsUpdate (int siv, unsigned int flags)
	Updates the sequencing state of the SIV.
Variables
enum _CCSDS_ISTREAM_RESOLVER_STATUS_K	CCSDS_ISTREAM_RESOLVER_STATUS_K
	Typedef for enum _CCSDS_ISTREAM_RESOLVER_STATUS_K.
enum _CCSDS_ISTREAM_STATUS_K	CCSDS_ISTREAM_STATUS_K
	Typedef enum _CCSDS_ISTREAM_STATUS_K.

---

Detailed Description

CCSDS input stream (reader) interface.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: CCSDS_istream.h,v 1.8 2011/03/26 21:06:58 russell Exp $

---

Typedef Documentation

CCSDS_ISTREAM_PKT_CHECK_OPTS_M

Typedef for CCSDS_ISTREAM_PKT_CHECK_OPTS_M.

These are the options for the precanned CCSDS_istreamPktCheck routine. To preserve the goal of making the suggested default options a value of 0, some of these options are somewhat awkwardly stated in the negative sense.

CCSDS_ISTREAM_PKT_STATE_K

Typedef for enum _CCSDS_ISTREAM_PKT_STATE_K.

A packet's state is determined by the values of 2 bits, with bit 0 representing the 'is first packet' and bit 1 representing 'is last packet' Under these definitions

• State = 0, neither first or last packet -> MIDDLE packet
• State = 1, packet is first, but not last packet -> FIRST in a sequence
• State = 2, packet is last, buf not first packet -> LAST in a sequence
• State = 3, packet is both the first and last -> ONLY packet

int(* CCSDS_istreamCloser)(void *prm)

Routine to read the specified number of bytes from the input stream.

Parameters:

prm

User specified parameter

int(* CCSDS_istreamReader)(void *prm, void *buf, int nbytes, int pbytes)

Routine to read the specified number of bytes from the input stream.

Return values:

	0,All	is well
	-1,EOF,this	should only occur when the file read is being done from CCSDS_istreamHdrRead.
	>0,Any	error other error. These should never occur.

Parameters:

	prm	User specified parameter
	buf	The destination buffer
	nbytes	The number of bytes to read
	pbytes	The number of pad bytes to skip at the end. This number is guaranteed to be no larger than 16 bytes.

int(* CCSDS_istreamResolver)(void *ctx, CCSDS_telemetry const *pkt, CCSDS_apidDsc **dsc)

User callback to CCSDS_istreamProcess that resolves an apid to its controlling APID descriptor.

Returns:

One of the enum _CCSDS_ISTREAM_RESOLVER_STATUS

Parameters:

	ctx	Context parameter
	pkt	The CCSDS telemetry packet (only the header)
	dsc	Returned as a pointer to the apid descriptor

The primary responsibility of this routine is to resolve the APID contained within the CCSDS telemetry packet to an APID descriptor. However, this routine may also be used for other purposes. For example,

• To print the telemetry packet header
• once resolved to an APID, to check the sequencing. If, the sequencing was found to be in error, it could be reset or the routine could return a stop processing status.

int(* CCSDS_istreamTeller)(void const *prm)

Routine to give the current position in the stream. As an example, for files, this will do an ftell.

Returns:

The current position in the stream.

Parameters:

prm

User specified parameter

---

Enumeration Type Documentation

enum _CCSDS_ISTREAM_PKT_CHECK_OPTS_M

Options, in the form of bit masks, for the precanned CCSDS_istream packet checker routine.

See also:

CCSDS_istreamPacketCheck

Enumerator:

CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NORESYNCH	Inhibit standard recover from synchronization errors
CCSDS_ISTREAM_PKT_CHECK_OPTS_M_PRINT_HDR	Print the CCSDS packet header information
CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SYNCH_ERR	Print the synchronization errors and resynchronization status
CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SIV_ERR	Print the state information errors as strings. This is only printed if there are still errors after any potential resynchronization attempt

enum _CCSDS_ISTREAM_PKT_STATE_K

Enumerates the values of a packet's state.

Enumerator:

CCSDS_ISTREAM_PKT_STATE_K_MID	Packet is the middle packet in a sequence
CCSDS_ISTREAM_PKT_STATE_K_FIRST	Packet is the first packet in a sequence
CCSDS_ISTREAM_PKT_STATE_K_LAST	Packet is the last packet in a sequence
CCSDS_ISTREAM_PKT_STATE_K_ONLY	Packet is the first packet in a sequence

enum _CCSDS_ISTREAM_RESOLVER_STATUS_K

Permitted return values of the CCSDS APID resolver routine.

Enumerator:

CCSDS_ISTREAM_RESOLVER_STATUS_K_SUCCESS	Descriptor found
CCSDS_ISTREAM_RESOLVER_STATUS_K_IGNORE	Descriptor found, but do not read the data
CCSDS_ISTREAM_RESOLVER_STATUS_K_NOTFOUND	Descriptor not found, but continue
CCSDS_ISTREAM_RESOLVER_STATUS_K_STOP	Stop processing

enum _CCSDS_ISTREAM_SIV_K

Enumerates the values of in place fields of the SIV word. These are all convenience symbols, all being derived from previously defined symbols.

Enumerator:

CCSDS_ISTREAM_SIV_K_PRV_ONLY	In place value of the previous state is ONLY packet
CCSDS_ISTREAM_SIV_K_PRV_FIRST	In place value of the previous state is FIRST packet
CCSDS_ISTREAM_SIV_K_PRV_MID	In place value of the previous state is MIDDLE packet
CCSDS_ISTREAM_SIV_K_PRV_LAST	In place value of the previous state is LAST packet
CCSDS_ISTREAM_SIV_K_CUR_ONLY	In place value of the current state is ONLY packet
CCSDS_ISTREAM_SIV_K_CUR_FIRST	In place value of the current state is FIRST packet
CCSDS_ISTREAM_SIV_K_CUR_MID	In place value of the current state is MIDDLE packet
CCSDS_ISTREAM_SIV_K_CUR_LAST	In place value of the current state is LAST packet

enum _CCSDS_ISTREAM_SIV_M

State Information Vector, in place mask.

Enumerator:

CCSDS_ISTREAM_SIV_M_SEQGAP	The gap between successive sequence numbers + 1, that is CURRENT_SEQUENCE_NUMBER - PREVIOUS_SEQUENCE_NUMBER + 1 If all is right, this number should be 0
CCSDS_ISTREAM_SIV_M_PRV_FIRST	Previous packet is the first, either alone or in a sequence
CCSDS_ISTREAM_SIV_M_PRV_LAST	Previous packet is the last, either alone or in a sequence
CCSDS_ISTREAM_SIV_M_PRV	Convenience symbol to for the state of the previous packet
CCSDS_ISTREAM_SIV_M_CUR_FIRST	Previous packet is the first, either alone or in a sequence
CCSDS_ISTREAM_SIV_M_CUR_LAST	Previous packet is the last, either alone of in a sequence
CCSDS_ISTREAM_SIV_M_CUR	Convenience symbol to for the state of the current packet
CCSDS_ISTREAM_SIV_M_RSVD_20	Reserved
CCSDS_ISTREAM_SIV_M_RSVD_21	Reserved
CCSDS_ISTREAM_SIV_M_RSVD_22	Reserved
CCSDS_ISTREAM_SIV_M_RSVD_23	Reserved
CCSDS_ISTREAM_SIV_M_ERR_EOS	End of stream prematurely reached
CCSDS_ISTREAM_SIV_M_ERR_RDHDR	Error is getting the header
CCSDS_ISTREAM_SIV_M_ERR_BADHDR	Error, header is not properly formatted, essentially an error reported by CCSDS_pktHdr
CCSDS_ISTREAM_SIV_M_ERR_SEQ	Sequence error on the last packet
CCSDS_ISTREAM_SIV_M_ERR_SEQNUM	Sequence number error on the last packet
CCSDS_ISTREAM_SIV_M_ERR_RDDAT	Error is reading the data
CCSDS_ISTREAM_SIV_M_ERR_OVRRUN	Data packet was to large to fit in user provided buffer
CCSDS_ISTREAM_SIV_M_ERR_SUMMARY	Error Summary bit
CCSDS_ISTREAM_SIV_M_ERR	Any error
CCSDS_ISTREAM_SIV_M_ERR_SYNCH	Preread error, these indicate errors that the user may wish to try to recover from by resynching the packet stream

enum _CCSDS_ISTREAM_SIV_S

State Information Vector, bit field sizes.

Enumerator:

CCSDS_ISTREAM_SIV_S_SEQGAP	The gap between successive sequence numbers + 1, that is CURRENT_SEQUENCE_NUMBER - PREVIOUS_SEQUENCE_NUMBER + 1 If all is right, this number should be 0
CCSDS_ISTREAM_SIV_S_PRV_FIRST	Previous packet is the first, either alone or in a sequence
CCSDS_ISTREAM_SIV_S_PRV_LAST	Previous packet is the last, either alone or in a sequence
CCSDS_ISTREAM_SIV_S_PRV	Convenience symbol for the previous packet's state
CCSDS_ISTREAM_SIV_S_CUR_FIRST	Current packet is the first, either alone or in a sequence
CCSDS_ISTREAM_SIV_S_CUR_LAST	Current packet is the last, either alone or in a sequence
CCSDS_ISTREAM_SIV_S_CUR	Convenience symbol for the current packet's state
CCSDS_ISTREAM_SIV_S_RSVD_20	Reserved
CCSDS_ISTREAM_SIV_S_RSVD_21	Reserved
CCSDS_ISTREAM_SIV_S_RSVD_22	Reserved
CCSDS_ISTREAM_SIV_S_RSVD_23	Reserved
CCSDS_ISTREAM_SIV_S_ERR	Size of the error field, in bits
CCSDS_ISTREAM_SIV_S_ERR_EOS	End of stream reached prematurely
CCSDS_ISTREAM_SIV_S_ERR_RDHDR	Error is getting the header
CCSDS_ISTREAM_SIV_S_ERR_BADHDR	Error, header is not properly formatted, essentially an error reported by CCSDS_pktHdr
CCSDS_ISTREAM_SIV_S_ERR_SEQ	Sequence error on the last packet
CCSDS_ISTREAM_SIV_S_ERR_SEQNUM	Sequence number error on the last packet
CCSDS_ISTREAM_SIV_S_ERR_RDDAT	Error is reading or advancing the data
CCSDS_ISTREAM_SIV_S_ERR_OVRRUN	Data packet was to large to fit in user provided buffer
CCSDS_ISTREAM_SIV_S_ERR_SUMMARY	Error Summary bit

enum _CCSDS_ISTREAM_SIV_V

State Information Vector, right justified bit field offsets.

Enumerator:

CCSDS_ISTREAM_SIV_V_SEQGAP	The gap between successive sequence numbers + 1, that is CURRENT_SEQUENCE_NUMBER - PREVIOUS_SEQUENCE_NUMBER + 1 If all is right, this number should be 0
CCSDS_ISTREAM_SIV_V_PRV_FIRST	Previous packet is the first, either alone or in a sequence
CCSDS_ISTREAM_SIV_V_PRV_LAST	Previous packet is the last, either alone or in a sequence
CCSDS_ISTREAM_SIV_V_PRV	Convenience symbol for the previous packet's state
CCSDS_ISTREAM_SIV_V_CUR_FIRST	Current packet is the first, either alone or in a sequence
CCSDS_ISTREAM_SIV_V_CUR_LAST	Previous packet is the last, either alone or in a sequence
CCSDS_ISTREAM_SIV_V_CUR	Convenience symbol for the current packet's state
CCSDS_ISTREAM_SIV_V_RSVD_20	Reserved
CCSDS_ISTREAM_SIV_V_RSVD_21	Reserved
CCSDS_ISTREAM_SIV_V_RSVD_22	Reserved
CCSDS_ISTREAM_SIV_V_RSVD_23	Reserved
CCSDS_ISTREAM_SIV_V_ERR	Begining of the ERR field
CCSDS_ISTREAM_SIV_V_ERR_EOS	End of stream reached
CCSDS_ISTREAM_SIV_V_ERR_RDHDR	Error is getting the header
CCSDS_ISTREAM_SIV_V_ERR_BADHDR	Error, header is not properly formatted, essentially an error reported by CCSDS_pktHdr
CCSDS_ISTREAM_SIV_V_ERR_SEQ	Sequence error on the last packet
CCSDS_ISTREAM_SIV_V_ERR_SEQNUM	Sequence number error on the last packet
CCSDS_ISTREAM_SIV_V_ERR_RDDAT	Error is reading the data
CCSDS_ISTREAM_SIV_V_ERR_OVRRUN	Data packet was to large to fit in user provided buffer
CCSDS_ISTREAM_SIV_V_ERR_SUMMARY	Error Summary bit

enum _CCSDS_ISTREAM_STATUS_K

Enumerates the return status codes.

Enumerator:

CCSDS_ISTREAM_STATUS_K_IO_READ_ERROR	IO error encountered during reading of the packet data
CCSDS_ISTREAM_STATUS_K_PACKET_ERROR	Packet error, check siv
CCSDS_ISTREAM_STATUS_K_IO_SKIP_ERROR	IO error encountered during skipping of packet data
CCSDS_ISTREAM_STATUS_K_VERIFY_ERROR	Packet header verification error
CCSDS_ISTREAM_STATUS_K_IO_HEADER_ERROR	IO error encountered during reading of the packet header
CCSDS_ISTREAM_STATUS_K_EOS	End of stream encountered. Technically the user should scan all descriptors, checking that none are expecting another packet
CCSDS_ISTREAM_STATUS_K_RESOLVER_STOP	APID resolver callback routine requested the processing to stop
CCSDS_ISTREAM_STATUS_K_CHECKER_STOP	Packet checker callback routine requested the processing to stop
CCSDS_ISTREAM_STATUS_K_PROCESSOR_STOP	Payload processor routine requested the processing to stop

---

Function Documentation

int CCSDS_istreamClose

(

CCSDS_istream *

istream

)

Closes the input stream associated with istream.

Returns:

Status

Parameters:

istream

The stream to close

Note:

This does not free/destroy the istream control structure, it merely closes the physical stream associated with it.

References _CCSDS_istreamInput::close, _CCSDS_istream::input, and _CCSDS_istreamInput::prm.

int CCSDS_istreamConnect	(	CCSDS_istream *	istream,
		void *	prm,
		CCSDS_istreamReader	read,
		CCSDS_istreamCloser	close,
		CCSDS_istreamTeller	tell
	)

Connects a read mechanism with the specified stream.

Return values:

0,Always

Parameters:

	istream	The target CCSDS_istream
	prm	Arbitrary user context parameter passed to the read routine
	read	The routine used to read from the underlying physical data stream
	close	The routine used to close the underlying physical stream
	tell	The routine used to get the current position in the stream.

References _CCSDS_istreamInput::close, _CCSDS_istream::input, _CCSDS_istreamInput::read, and _CCSDS_istreamInput::tell.

int CCSDS_istreamConstruct

(

CCSDS_istream *

istream

)

Constructs (initializes) a previously uninitialized CCSDS_istream control structure.

Return values:

	==0,Successful
	!=0,Failure	(currently the routine always succeeds

Parameters:

istream

The CCSDS_istream structure to construct (initialize)

References construct().

int CCSDS_istreamDatAdvance	(	CCSDS_istream *	istream,
		CCSDS_telemetry const *	packet,
		CCSDS_apidDsc *	dsc
	)

Advances past the current CCSDS data payload with reading the data into the buffer. All integrity checks are preformed. This in contrast with calling CCSDS_istreamDatRead with a NULL descriptor.

Returns:

If descriptor is non-NULL, then the State Information Vector. This is a heavily bit-encoded 32-bit word, see CCSDS_ISTREAM_SIV_M, for example for the meanings of these bits. Consult the dsc->status word for more information

If descriptor is NULL, then the code from the reader (most likely a UNIX errno).

Parameters:

	istream	The target CCSDS_istream structure
	packet	The packet header associated with the data about to be read
	dsc	The target APIDs descriptor, this may be NULL, in which case the data bytes are just skipped, with no checking, In this case the routine behaves identically to CCSDS_istreamDatRead with the same arguments.

References CCSDS__telemetrySequenceFlags(), CCSDS__telemetrySequenceNumber(), CCSDS__telemetrySsrLength(), CCSDS_istreamSivFlagsUpdate(), CCSDS_istreamSivIoUpdate(), CCSDS_istreamSivIsError(), check_sequencing(), form_transition(), _CCSDS_istream::input, _CCSDS_istreamInput::prm, _CCSDS_istreamInput::read, _CCSDS_apidDsc::seq, _CCSDS_apidDsc::siv, and _CCSDS_apidDsc::status.

Referenced by CCSDS_istreamPktResynch(), and CCSDS_istreamProcess().

int CCSDS_istreamDatRead	(	CCSDS_istream *	istream,
		CCSDS_telemetry const *	packet,
		CCSDS_apidDsc *	dsc
	)

Reads the current CCSDS data payload into the buffer specified by dsc.

Returns:

If descriptor is non-NULL, then the State Information Vector. This is a heavily bit-encoded 32-bit word, see CCSDS_ISTREAM_SIV_M, for example for the meanings of these bits. Consult the dsc->status word for more information

If descriptor is NULL, then the code from the reader (most likely a UNIX errno).

Parameters:

	istream	The target CCSDS_istream structure
	packet	The packet header associated with the data about to be read
	dsc	The target APIDs descriptor

If there was insufficient space in the descriptor's read buffer to perform the read, no bytes are read, but rather, the return value is set to indicate insufficient space and the descriptor's status word (dsc->status) is set to the number of bytes needed. The user may increase the descriptors read buffer side and then recall this routine.

References _CCSDS_apidDsc::bridge, _CCSDS_apidDsc::buf, CCSDS__telemetrySequenceFlags(), CCSDS__telemetrySequenceNumber(), CCSDS__telemetrySsrLength(), CCSDS__telemetrySsrPad(), CCSDS_APIDDSC_BRIDGE_K_PAD, CCSDS_APIDDSC_BRIDGE_K_PAYLOAD, CCSDS_ISTREAM_PKT_STATE_K_FIRST, CCSDS_ISTREAM_SIV_M_ERR_OVRRUN, CCSDS_ISTREAM_SIV_M_ERR_SUMMARY, CCSDS_istreamSivFlagsUpdate(), CCSDS_istreamSivIoUpdate(), CCSDS_istreamSivIsError(), check_sequencing(), _CCSDS_apidDsc::cur, form_transition(), _CCSDS_istream::input, _CCSDS_apidDsc::max, _CCSDS_telemetry::payload, _CCSDS_istreamInput::prm, _CCSDS_istreamInput::read, _CCSDS_apidDsc::seq, _CCSDS_apidDsc::siv, and _CCSDS_apidDsc::status.

Referenced by CCSDS_istreamPktResynch(), and CCSDS_istreamProcess().

int CCSDS_istreamDestroy

(

CCSDS_istream *

istream

)

Destroys (i.e. returns the resources) associated with the stream.

Returns:

Status

Parameters:

istream

The stream to destroy.

References _CCSDS_istream::free.

int CCSDS_istreamFileOpen	(	CCSDS_istream *	istream,
		char const *	filename,
		unsigned int	options,
		unsigned char *	buf,
		unsigned int	buf_size
	)

Convenience function to construct a CCSDS_istream to read from the specified named file filename.

Returns:

0, If successful

-1, If could not allocate a new stream (i.e. out of memory)

-2, If the file does not exist

Parameters:

	istream	The target CCSDS_istream
	filename	The name of the file to open
	options	Bit list of options, currently unused, specify as 0
	buf	Optional parameter specifying the FILE's input read buffer
	buf_size	Optional parameter specifying the size of buf

References CCSDS_istreamNew(), _CCSDS_istreamInput::close, file_read(), _CCSDS_istream::input, _CCSDS_istreamInput::prm, _CCSDS_istreamInput::read, and _CCSDS_istreamInput::tell.

void CCSDS_istreamHdrPrint

(

CCSDS_telemetry const *

packet

)

Prints a one-line summary of the CCSDS_istream header.

Parameters:

packet

The packet header to print

References CCSDS__telemetrySequenceFlags(), CCSDS_TELEMETRY_PRINT_OPTS_M_ALL, CCSDS_TELEMETRY_PRINT_OPTS_M_HEADER, and CCSDS_telemetryPrint().

int CCSDS_istreamHdrRead	(	CCSDS_istream *	istream,
		CCSDS_telemetry *	packet
	)

Reads the CCSDS header.

Return values:

	0,Success
	-1,End	Of Stream
	Anything	else, error number (errno)

Parameters:

	istream	The target CCSDS_istream
	packet	The destination CCSDS telemetry packet header

After reading the header and checking to see if the read is successful, the user should call CCSDS_telemetryVerify to verify that the header is okay. This provides some protection, although not a lot because the internal consistency checks to do the verification of telemetry are not that strong, something like 4 bits. See CCSDS__telemetryVerify for an explanation.

Note:

The odd 16-bit word after the normal 7 x 16bit word CCSDS header is also read by this routine. Technically this is not correct. It is not until the apid is read does one really know if this word belongs with the header or the data. However, the only time one can get into trouble is if this word does not exist at all. In this case, two bad things can happen 1. The word does not even exist in the input stream. This means one has over-read by 2 bytes, which will falsely cause an EOF. This is not too bad because it can be checked if need be. 2. The word belongs to the next CCSDS packet. In this case, the order needs to be 'put' back into the IO stream so the next packet can find it. This can be done, but it is ugly. (More reasonable is that when CCSDS_istreamDatRead or CCSDS_istreamHdrRead attempts to move past the data, it will discover that the remaining data is -2. It could then 'stash' these 2 bytes away so that CCSDS_istreamHdr could check on the next read to see if the exist, and if so, 'read' them first, then the rest of the header.

However the tactic taken here is to bury one's head in the sand and ignore the issue. The LAT currently has no packets that are dataless. If the need arises, the out list above in (2) will be taken.

References CCSDS__telemetrySsrSwapb(), _CCSDS_istream::input, _CCSDS_istreamInput::prm, and _CCSDS_istreamInput::read.

Referenced by CCSDS_istreamProcess().

CCSDS_istream * CCSDS_istreamNew

(

void

)

Convenience function to allocate and initialize a CCSDS_istream control structure.

Returns:

Pointer to the allocated CCSDS_istream control structure

References construct().

Referenced by CCSDS_istreamFileOpen().

int CCSDS_istreamPktCheck	(	unsigned int	opts,
		CCSDS_istream *	istream,
		CCSDS_telemetry const *	pkt,
		CCSDS_apidDsc *	dsc
	)

Precanned CCSDS_istreamProcess callback routine to check the integrity of a CCSDS packet.

Return values:

	==	0, meaning to continue
	!=	0, stop (it actually returns the erroring siv, but the public interface to the checker routine is simply 0 for success and non-zero for error.

Parameters:

opts

A bit mask of options,

See also:

CCSDS_ISTREAM_PKT_CHECK_OPTS_M

Parameters:

	istream	The CCSDS_istream handle
	pkt	The CCSDS packet to check
	dsc	The descriptor for this APID stream.

The user of the CCSDS_istreamProcess framework may use this routine as his APID specific packet checker or as a template to writing his own. This routine, with the opts argument set to a value of 0, will be used if the user does not provide one.

References CCSDS__telemetryApid(), CCSDS__telemetrySequenceFlags(), CCSDS__telemetrySequenceNumber(), CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SIV_ERR, CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NOPRINT_SYNCH_ERR, CCSDS_ISTREAM_PKT_CHECK_OPTS_M_NORESYNCH, CCSDS_ISTREAM_PKT_CHECK_OPTS_M_PRINT_HDR, CCSDS_ISTREAM_SIV_M_CUR_FIRST, CCSDS_ISTREAM_SIV_M_PRV_LAST, CCSDS_istreamPktResynch(), CCSDS_istreamSivCurFlags(), CCSDS_istreamSivIsError(), CCSDS_istreamSivIsResynchable(), CCSDS_TELEMETRY_PRINT_OPTS_M_ALL, CCSDS_TELEMETRY_PRINT_OPTS_M_HEADER, CCSDS_telemetryPrint(), report_siv_error(), _CCSDS_apidDsc::seq, and _CCSDS_apidDsc::siv.

Referenced by CCSDS_istreamProcess().

int CCSDS_istreamPktResynch	(	CCSDS_istream *	istream,
		CCSDS_telemetry const *	packet,
		CCSDS_apidDsc *	dsc
	)

Routine to recover from an APID sequence number or sequence state (first, middle, last) packet error. It can be used part of the CCSDS_istreamProcess packer checker routine.

Returns:

The updated siv.

Parameters:

	istream	The CCSDS istream handle
	packet	The telemety packet. Only the header need be present
	dsc	The APID stream descriptor

References CCSDS__telemetrySequenceFlags(), CCSDS_apidDscReset(), CCSDS_istreamDatAdvance(), CCSDS_istreamDatRead(), CCSDS_istreamSivIoUpdate(), CCSDS_istreamSivIsResynchable(), CCSDS_sequenceFlagsIsFirst(), _CCSDS_apidDsc::siv, and _CCSDS_apidDsc::status.

Referenced by CCSDS_istreamPktCheck().

int CCSDS_istreamProcess	(	CCSDS_istream *	stream,
		CCSDS_istreamCsb *	csb,
		CCSDS_istreamResolver	resolve_rtn,
		void *	resolve_ctx
	)

Processes a stream of CCSDS packets. The packets may be from multiple APIDs.

Returns:

See the enumeration CCSDS_ISTREAM_STATUS_K

Parameters:

	stream	The stream of CCSDS packets
	csb	The completion status block. This contains details about the processing. In particular, it contains the returned status value of the routine that stopped the processing and, if applicable, the apid descriptor that was active when the processing was stopped.
	resolve_rtn	Routine to resolve the APID to an APID descriptor. If NULL, only packet level processing can be done
	resolve_ctx	Context parameter for the resolve_rtn

This routine can be used for a variety of purposes through the use of the various callback routines.

Use Case 1 - Basic Packet Integrity check

Have the resolve routine return a descriptor for every that has no checker or processing routine. Set the return value to CCSDS_ISTREAM_RESOLVE_STATUS_K_IGNORE. Since no data is being read, the descriptor does not need to provide a buffer.

Use Case 2 - More Involve Packet Integrity

Have the resolve routine return a descriptor for every that has a checker but no processing routine. Set the return value to CCSDS_ISTREAM_RESOLVE_STATUS_K_FOUND.

Use Case 3 - Packet Assembler

Have the resolve routine return a descriptor for every that has no checker but does have processing routine whose only function is to return a non-zero value indicating to stop processing. Control will be returned to the caller with a status of CCSDS_ISTREAM_STATUS_K_PROCESS_STOP. The descriptor of the assembled packet will be in the CCSDSS_istreamCsb (completion status block).

Use Case 4 - Packet Processor

References CCSDS__telemetryVerify(), CCSDS_APIDDSC_POPTS_M_SWAP, CCSDS_apidDscPktBeg(), CCSDS_apidDscPktLen(), CCSDS_apidDscSwap32(), CCSDS_ISTREAM_RESOLVER_STATUS_K_IGNORE, CCSDS_ISTREAM_RESOLVER_STATUS_K_NOTFOUND, CCSDS_ISTREAM_STATUS_K_CHECKER_STOP, CCSDS_ISTREAM_STATUS_K_EOS, CCSDS_ISTREAM_STATUS_K_IO_HEADER_ERROR, CCSDS_ISTREAM_STATUS_K_IO_SKIP_ERROR, CCSDS_ISTREAM_STATUS_K_PROCESSOR_STOP, CCSDS_ISTREAM_STATUS_K_RESOLVER_STOP, CCSDS_ISTREAM_STATUS_K_VERIFY_ERROR, CCSDS_istreamDatAdvance(), CCSDS_istreamDatRead(), CCSDS_istreamHdrRead(), CCSDS_istreamPktCheck(), CCSDS_istreamSivIsLast(), _CCSDS_apidHandlers::checker_ctx, _CCSDS_apidHandlers::checker_rtn, _CCSDS_istreamCsb::dsc, _CCSDS_apidDsc::handler, _CCSDS_istreamCsb::pkt, _CCSDS_istream::pkt, _CCSDS_apidDsc::popts, _CCSDS_apidHandlers::processor_ctx, _CCSDS_apidHandlers::processor_rtn, _CCSDS_apidDsc::siv, and _CCSDS_istreamCsb::status.

static __inline int CCSDS_istreamSivConstruct

(

void

)

[static]

Initializes the State Information Vector to a known and beign state.

Returns:

The initialized value

References CCSDS_ISTREAM_SIV_K_CUR_ONLY, and CCSDS_ISTREAM_SIV_K_PRV_ONLY.

Referenced by CCSDS_apidDscConstruct(), and CCSDS_apidDscReset().

static __inline int CCSDS_istreamSivCurFlags

(

int

siv

)

[static]

Returns the flags associated with the current packet packet.

Returns:

The 2 bit flags of the current packet

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_M_CUR, and CCSDS_ISTREAM_SIV_V_CUR.

Referenced by CCSDS_istreamPktCheck().

static __inline int CCSDS_istreamSivFlagsUpdate	(	int	siv,
		unsigned int	flags
	)			[static]

Updates the sequencing state of the SIV.

Returns:

The updated SIV

Parameters:

	siv	The current SIV
	flags	The new sequence flags

References CCSDS_ISTREAM_SIV_M_CUR, CCSDS_ISTREAM_SIV_M_PRV, and CCSDS_ISTREAM_SIV_V_PRV.

Referenced by CCSDS_istreamDatAdvance(), and CCSDS_istreamDatRead().

static __inline int CCSDS_istreamSivIoUpdate	(	int	siv,
		unsigned int	status
	)			[static]

Updates the SIV according to the IO status.

Returns:

The updated SIV

Parameters:

	siv	The current SIV
	status	The io status

References CCSDS_ISTREAM_SIV_M_ERR_EOS, CCSDS_ISTREAM_SIV_M_ERR_RDDAT, and CCSDS_ISTREAM_SIV_M_ERR_SUMMARY.

Referenced by CCSDS_istreamDatAdvance(), CCSDS_istreamDatRead(), and CCSDS_istreamPktResynch().

static __inline int CCSDS_istreamSivIsError

(

int

siv

)

[static]

Returns non-zero if State Information Vector, siv, is in error.

Return values:

	=0	Is not in error
	!=0	Is in error

Parameters:

siv

The state information vector

Referenced by CCSDS_istreamDatAdvance(), CCSDS_istreamDatRead(), and CCSDS_istreamPktCheck().

static __inline int CCSDS_istreamSivIsFirst

(

int

siv

)

[static]

Returns non-zero if the current packet is the first packet, either alone or in a sequence.

Return values:

	=0	Is not the first packet, either alone or in a sequence
	!=0	Is the first packet, either alone or in a sequence

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_M_CUR_FIRST.

static __inline int CCSDS_istreamSivIsLast

(

int

siv

)

[static]

Returns non-zero if the current packet is the last packet, either alone or in a sequence.

Return values:

	=0	Is not the last packet, either alone or in a sequence
	!=0	Is the last packet, either alone or in a sequence

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_M_CUR_LAST.

Referenced by CCSDS_istreamProcess().

static __inline int CCSDS_istreamSivIsMid

(

int

siv

)

[static]

Returns non-zero if the current packet is the middle packet in a sequence.

Return values:

	=0	Is not the last packet in a sequence
	!=0	Is the last packet in a sequence

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_K_CUR_MID, and CCSDS_ISTREAM_SIV_M_CUR.

static __inline int CCSDS_istreamSivIsOnly

(

int

siv

)

[static]

Returns non-zero if the current packet is the only packet, i.e. bare packet, not a member of a sequence.

Return values:

	=0	Is not the only packet
	!=0	Is the only packet

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_K_CUR_ONLY, and CCSDS_ISTREAM_SIV_M_CUR.

static __inline int CCSDS_istreamSivIsResynchable

(

int

siv

)

[static]

Returns non-zero if State Information Vector, siv, has a recoverable synchronization error.

Return values:

	=0	Packet stream cannot be resynchronized
	!=0	Resynchronization may be attempted, although there is no guarantee of success

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_M_ERR_SYNCH.

Referenced by CCSDS_istreamPktCheck(), and CCSDS_istreamPktResynch().

static __inline int CCSDS_istreamSivPrvFlags

(

int

siv

)

[static]

Returns the flags associated with the last previously read packet.

Returns:

The 2 bit flags of the last previously read packet

Parameters:

siv

The state information vector

References CCSDS_ISTREAM_SIV_M_PRV, and CCSDS_ISTREAM_SIV_V_PRV.

int CCSDS_istreamSizeof

(

void

)

Returns the size, in bytes, of a CCSDS_istream structure.

Returns:

The size, in bytes, of a CCSDS_istream structure

unsigned int CCSDS_istreamTell

(

CCSDS_istream const *

istream

)

Returns the current byte offset into the stream.

Returns:

The current byte offset into the stream, i.e. the read pointer

Parameters:

istream

The target CCSDS_istream

References _CCSDS_istream::input, _CCSDS_istreamInput::prm, and _CCSDS_istreamInput::tell.

---

Variable Documentation

CCSDS_ISTREAM_STATUS_K

Typedef enum _CCSDS_ISTREAM_STATUS_K.

The codes are organized so that < 0 End of stream or internal errors, either IO errors or the CCSDS packets are mal-formed or sequenced. > 0 User requested stops = 0 Continue, processing so far has been successfully completed but user requested control be returned to calling program. After completing what every processing, the user should recall the processing routine.