QSE_dgmDvr.h File Reference

Interface to the generic event datagram routines. This is meant to relieve the user of common chores associated with handling event datagrams, such as skipping events. More...

#include <QSE/QSE_update.h>
#include <LSF/LSF_scan.h>
#include <PBI/PTR.h>

Classes

struct _QSE_dgmDvrStatsGbl

Global counts of datagrams, contributions and records. More...

struct _QSE_dgmDvrStatsDgm

Statistics of this datagram, contributions and records. More...

struct _QSE_dgmDvrStatsCtb

Statistics of this contribution, records. More...

struct _QSE_dgmDvrStats

Statistics at the global, datagram, contribution and record level. More...

Typedefs

typedef struct _QSE_dgmDvrStatsGbl QSE_dgmDvrStatsGbl

Typedef for struct QSE_dgmDvrStatsGbl.

typedef struct _QSE_dgmDvrStatsDgm QSE_dgmDvrStatsDgm

Typedef for struct QSE_printCtxStatsDgm.

typedef struct _QSE_dgmDvrStatsCtb QSE_dgmDvrStatsCtb

Typedef for struct QSE_dgmDvrStatsCtb.

typedef struct _QSE_dgmDvrStats QSE_dgmDvrStats

Typedef for struct _QSE_dgmDvrStats.

typedef unsigned int(* QSE_dgmDvrDgm )(void *context, const LSF_datagram *dgm, void *prm)

Callback signature for user provided datagram handler.

typedef unsigned int(* QSE_dgmDvrCtb )(void *context, const LSF_contribution *ctb, void *prm)

Callback signature for user provided context handler.

typedef unsigned int(* QSE_dgmDvrRec )(void *context, const LSF_record *rec, void *prm)

Callback signature for user provided record handler.

typedef enum _QSE_DGMDVR_FATE_K QSE_DGMDVR_FATE_K

Typedef for enum _QSE_DGMDVR_FATE_K.

typedef enum _QSE_DGMDVR_PRM_K QSE_DGMDVR_PRM_K

Enumerations

enum _QSE_DGMDVR_FATE_K {
  QSE_DGMDVR_FATE_K_PROCESS = 0,
  QSE_DGMDVR_FATE_K_CONTINUE = 0,
  QSE_DGMDVR_FATE_K_STOP = 1,
  QSE_DGMDVR_FATE_K_NEXT_DATAGRAM = 2,
  QSE_DGMDVR_FATE_K_NEXT_CONTRIBUTION = 3
}

Fate returned by the print driver callback routine to determine whether more events are processed or not. More...

enum _QSE_DGMDVR_PRM_K {
  QSE_DGMDVR_PRM_K_END = 0,
  QSE_DGMDVR_PRM_K_ECOUNT = 1,
  QSE_DGMDVR_PRM_K_ESKIP = 2,
  QSE_DGMDVR_PRM_K_PCOUNT = 3,
  QSE_DGMDVR_PRM_K_PSKIP = 4
}

Enumerates the print driver options. More...

Functions

unsigned int QSE_dgmDvrSizeof (const unsigned int *cfg)

Returns the size, in bytes of a QSE_dgmDvr structure.

QSE_dgmDvr * QSE_dgmDvrConstruct (QSE_dgmDvr *dvr, const unsigned int *dvr_cfg, QSE_updateAtDatagram update_dgm, QSE_updateAtContribution update_ctb, QSE_updateAtRecord update_rec, void *update_ctx, QSE_dgmDvrDgm handle_dgm, QSE_dgmDvrCtb handle_ctb, QSE_dgmDvrRec handle_rec, void *handle_ctx)

Constructs/initializes the datagram context control block.

LSF_scanContributionHandler QSE_dgmDvrDatagram (QSE_dgmDvr *dvr, const LSF_datagram *datagram)

Handles each datagram.

int QSE_dgmDvrProcess (QSE_dgmDvr *dvr, const LSF_datagram *dgms, int dgms_len)

Convenience routine for the CCSDS_istreamProcess routine.

void QSE_dgmDvrDestruct (QSE_dgmDvr *dvr)

Frees the QSE datagram driver context.

const QSE_dgmDvrStats * QSE_dgmDvrStatsLocate (QSE_dgmDvr *dvr)

Retrieves a pointer to the statistics.

void QSE_dgmDvrStatsClear (QSE_dgmDvr *dvr)

Clears the datagram driver statistics.

static __inline unsigned int * QSE__dgmDvrCfgEventSkip (unsigned int *cfg, int nskip)

Adds a configuration parameter used to specify that nskip events be skipped before sending the user's event handler its first event.

static __inline unsigned int * QSE__dgmDvrCfgEventCount (unsigned int *cfg, int nprocess)

Adds a configuration parameter used to specify that the datagram driver will limit the number of events sent to the user's event handler to nprocess.

static __inline unsigned int * QSE__dgmDvrCfgEventSkipShr (unsigned int *cfg, int *pskip)

Adds a configuration parameter used to specify that nskip events be skipped before sending the user's event handler its first event.

static __inline unsigned int * QSE__dgmDvrCfgEventCountShr (unsigned int *cfg, int *pprocess)

Adds a configuration parameter used to specify that the datagram driver will limit the number of events sent to the user's event handler to nprocess.

static __inline unsigned int * QSE__dgmDvrCfgTerminate (unsigned int *cfg)

Terminates a configuration list.

static __inline unsigned int * QSE__dgmDvrCfgStorePtr (unsigned int *cfg, int type, void *ptr)

Store the pointer in the configuration array.

Detailed Description

Interface to the generic event datagram routines. This is meant to relieve the user of common chores associated with handling event datagrams, such as skipping events.

Author:: JJRussell - russell@slac.stanford.edu


   CVS $Id: QSE_dgmDvr.h,v 1.3 2011/03/27 01:45:43 russell Exp $

Typedef Documentation

unsigned int(* QSE_dgmDvrCtb)(void *context, const LSF_contribution *ctb, void *prm)

Callback signature for user provided context handler.

Return values:

	QSE_DGMDVR_FATE_K_QUIT
	QSE_DGMDVR_FATE_K_CONTINUE

Parameters:

	context	The update context
	ctb	The datagram contribution
	prm	User provided parameter, used to dynamically select decoding options.

unsigned int(* QSE_dgmDvrDgm)(void *context, const LSF_datagram *dgm, void *prm)

Callback signature for user provided datagram handler.

Return values:

	QSE_DGMDVR_FATE_K_QUIT
	QSE_DGMDVR_FATE_K_CONTINUE

Parameters:

	context	The update context
	dgm	The datagram
	prm	User provided parameter

unsigned int(* QSE_dgmDvrRec)(void *context, const LSF_record *record, void *prm)

Callback signature for user provided record handler.

Return values:

	QSE_DGMDVR_FATE_K_QUIT
	QSE_DGMDVR_FATE_K_CONTINUE

Parameters:

	context	The update context
	record	The event record to decode
	prm	User provided parameter, used to dynamically select decoding options.

Enumeration Type Documentation

enum _QSE_DGMDVR_FATE_K

Fate returned by the print driver callback routine to determine whether more events are processed or not.

Enumerator:

QSE_DGMDVR_FATE_K_PROCESS	Process the contents of the current object. If the object is a datagram, then process the contributions. If the object is a contribution, then process the records
QSE_DGMDVR_FATE_K_CONTINUE	Continue the processing of the records in a contribution
QSE_DGMDVR_FATE_K_STOP	Stop all processing
QSE_DGMDVR_FATE_K_NEXT_DATAGRAM	Advances to the next datagram. If the object is a datagram, then skip the processing of the contributions and, by implication, any records within those contributions If the object is a contribution, then skip the processing of the records in that contribution and any remaining contributions in the current datagram If the object is a record, then skip the processing of any remaining records in the contribution and any remaining contribution in the current datagram
QSE_DGMDVR_FATE_K_NEXT_CONTRIBUTION	Advances to the next contribution If the object is a contribution, then skip the processing of any records records in the current contribution If the object is a record, then skip the processing of any remaining records records in the current contribution

enum _QSE_DGMDVR_PRM_K

Enumerates the print driver options.

Typedef for enum _QSE_DGMDVR_PRM_K.

The is used to construct the variable list of print driver configuration parameters.

Enumerator:

QSE_DGMDVR_PRM_K_END	End of list
QSE_DGMDVR_PRM_K_ECOUNT	Count of events to process
QSE_DGMDVR_PRM_K_ESKIP	Number of events to process
QSE_DGMDVR_PRM_K_PCOUNT	Establishes a pointer to the count of events to process
QSE_DGMDVR_PRM_K_PSKIP	Establishes a pointer to the count of events to skip

Function Documentation

static __inline unsigned int * QSE__dgmDvrCfgEventCount	(	unsigned int *	cfg,
		int	nprocess
	)			`[static]`

Adds a configuration parameter used to specify that the datagram driver will limit the number of events sent to the user's event handler to nprocess.

See also:: QSE__dgmDvrCfgEventCountShr

Returns:: Pointer to the next location to be filled in the configuration list.

Parameters:

	cfg	Pointer to the next location to be filled in the configuration stream.
	nprocess	The number of events to process.

The process count used when specified by this routine will apply to each QSE_dgmDvr stream individually. That is if one has two datagram streams within a single source (say one from EPU 0 and one from EPU 1) each stream will be delivered nprocess events then stop. If one wishes the process count to be applied to combined streams, use QSE__dgmDvrCfgEventCountShr, which allows one to share the process count across streams.

References QSE_DGMDVR_PRM_K_ECOUNT.

static __inline unsigned int * QSE__dgmDvrCfgEventCountShr	(	unsigned int *	cfg,
		int *	pprocess
	)			`[static]`

Adds a configuration parameter used to specify that the datagram driver will limit the number of events sent to the user's event handler to nprocess.

See also:: QSE__dgmDvrCfgEventCount.

Returns:: Pointer to the next location to be filled in the configuration list.

Parameters:

	cfg	Pointer to the next location to be filled in the configuration stream.
	pprocess	Pointer to a location that contains the number of events to process.

The process count used when specified by this routine will applied collectively to all QSE_dgmDvr streams sharing ppprocess. That is if one has two datagram streams within a single source (say one from EPU 0 and one from EPU 1) the user routine will only be called back a total of nprocess times. If one wishes the process count to be applied to individual streams, use QSE__dgmDvrCfgEventCount. count across streams.

References QSE__dgmDvrCfgStorePtr(), and QSE_DGMDVR_PRM_K_PCOUNT.

static __inline unsigned int * QSE__dgmDvrCfgEventSkip	(	unsigned int *	cfg,
		int	nskip
	)			`[static]`

Adds a configuration parameter used to specify that nskip events be skipped before sending the user's event handler its first event.

See also:: QSE__dgmDvrCfgEventSkipShr.

Returns:: Pointer to the next location to be filled in the configuration stream.

Parameters:

	cfg	Pointer to the next location to be filled in the configuration list.
	nskip	The number of events to skip.

The skip count used when specified by this routine will apply to each QSE_dgmDvr stream individually. That is if one has two datagram streams within a single source (say one from EPU 0 and one from EPU 1) each stream will deliver their first event after the skip count has been exhausted. If one wishes the skip count to be applied to combined streams, use QSE__dgmDvrCfgEventSkipShr, which allows one to share a skip count across streams.

References QSE_DGMDVR_PRM_K_ESKIP.

static __inline unsigned int * QSE__dgmDvrCfgEventSkipShr	(	unsigned int *	cfg,
		int *	pskip
	)			`[static]`

Adds a configuration parameter used to specify that nskip events be skipped before sending the user's event handler its first event.

See also:: QSE__dgmDvrCfgEventSkip.

Returns:: Pointer to the next location to be filled in the configuration list.

Parameters:

	cfg	Pointer to the next location to be filled in the configuration stream.
	pskip	Pointer to a location that contains the number of events to skip.

The skip count used when specified by this routine will apply collectively to all QSE_dgmDvr streams sharing pskip. That is, if one has two datagram streams within a single source (say one from EPU 0 and one from EPU 1) the first event delivered will be only after nskip events from all datagram streams sharing this configuration have been encountered. If one wishes the skip count to be applied to individual streams, use QSE__dgmDvrCfgEventSkip.

References QSE__dgmDvrCfgStorePtr(), and QSE_DGMDVR_PRM_K_PSKIP.

static __inline unsigned int * QSE__dgmDvrCfgStorePtr	(	unsigned int *	cfg,
		int	type,
		void *	ptr
	)			`[static]`

Store the pointer in the configuration array.

Parameters:

`[out]`	cfg	Pointer to the configuation array to fill
`[in]`	type	The name of the pointer being stored
`[in]`	ptr	The pointer to store

This routine absorbs the difference between the 32/64-bit machines

Referenced by QSE__dgmDvrCfgEventCountShr(), and QSE__dgmDvrCfgEventSkipShr().

static __inline unsigned int * QSE__dgmDvrCfgTerminate ( unsigned int * cfg ) [static]

Terminates a configuration list.

Returns:: Pointer to the next location to be filled in the configuration stream. Since this is really the end of the configuration lins this is generally not all that useful.

Parameters:

cfg

The configuration list to terminate.

References QSE_DGMDVR_PRM_K_END.

QSE_dgmDvr* QSE_dgmDvrConstruct	(	QSE_dgmDvr *	dvr,
		const unsigned int *	dvr_cfg,
		QSE_updateAtDatagram	update_dgm,
		QSE_updateAtContribution	update_ctb,
		QSE_updateAtRecord	update_rec,
		void *	update_ctx,
		QSE_dgmDvrDgm	handle_dgm,
		QSE_dgmDvrCtb	handle_ctb,
		QSE_dgmDvrRec	handle_rec,
		void *	handle_ctx
	)

Constructs/initializes the datagram context control block.

Returns:: Pointer to the construct datagram driver context

Parameters:

	dvr	The datagram context to construct/initialize, if this is NULL, a QSE_dgmDvr context will be allocated using malloc.
	dvr_cfg	The driver configuration parameters, may be NULL
	update_dgm	The QSEP/QSEC update at datagram routine
	update_ctb	The QSEP/QSEC update at contribution routine
	update_rec	The QSEP/QSEC update at record routine
	update_ctx	The update routines' context parameter
	handle_dgm	The user routine to handle a datagram
	handle_ctb	The user routine to handle a contribution
	handle_rec	The user routine to handle a record
	handle_ctx	The user handler routines' context parameter

References _QSE_dgmDvr::free, _QSE_dgmDvr::handle_ctb, handle_ctb_noop(), _QSE_dgmDvr::handle_ctx, _QSE_dgmDvr::handle_dgm, handle_dgm_noop(), _QSE_dgmDvr::handle_rec, handle_rec_noop(), load_ptr(), _QSE_dgmDvr::nctb, _QSE_dgmDvr::nprocess, _QSE_dgmDvr::nskip, _QSE_dgmDvr::pprocess, _QSE_dgmDvr::pskip, QSE_DGMDVR_PRM_K_ECOUNT, QSE_DGMDVR_PRM_K_END, QSE_DGMDVR_PRM_K_ESKIP, QSE_DGMDVR_PRM_K_PCOUNT, QSE_DGMDVR_PRM_K_PSKIP, _QSE_dgmDvr::stats, _QSE_dgmDvr::update_ctb, _QSE_dgmDvr::update_ctx, _QSE_dgmDvr::update_dgm, and _QSE_dgmDvr::update_rec.

LSF_scanContributionHandler QSE_dgmDvrDatagram	(	QSE_dgmDvr *	dvr,
		const LSF_datagram *	dgm
	)

Handles each datagram.

Return values:

The

contribution level handler (routine + parameter)

Parameters:

	dvr	Datagram driver context parameter
	dgm	The datagram to print

References _QSE_dgmDvrStatsDgm::ctbs, _QSE_dgmDvrStats::dgm, _QSE_dgmDvrStatsGbl::dgms, evt_contribution_handler(), _QSE_dgmDvrStats::gbl, _QSE_dgmDvr::handle_ctx, _QSE_dgmDvr::handle_dgm, _QSE_dgmDvr::nctb, _QSE_dgmDvr::nskip, _QSE_dgmDvr::pskip, QSE_DGMDVR_FATE_K_NEXT_DATAGRAM, QSE_DGMDVR_FATE_K_PROCESS, QSE_DGMDVR_FATE_K_STOP, QSE_dgmEventSkip(), _QSE_dgmDvrStatsDgm::recs, _QSE_dgmDvr::stats, _QSE_dgmDvr::update_ctx, and _QSE_dgmDvr::update_dgm.

Referenced by QSE_dgmDvrProcess().

void QSE_dgmDvrDestruct ( QSE_dgmDvr * dvr )

Frees the QSE datagram driver context.

Parameters:

dvr

The datagram context to destruct

References _QSE_dgmDvr::free.

int QSE_dgmDvrProcess	(	QSE_dgmDvr *	dvr,
		const LSF_datagram *	dgms,
		int	dgms_len
	)

Convenience routine for the CCSDS_istreamProcess routine.

Return values:

	==	0 Continue
	!=	0 Stop

Parameters:

	dvr	The driver context parameter
	dgms	The datagrams to handle
	dgms_len	The length of the datagram

References QSE_dgmDvrDatagram().

unsigned int QSE_dgmDvrSizeof ( const unsigned int * cfg )

Returns the size, in bytes of a QSE_dgmDvr structure.

Returns:: The size, in bytes of a QSE_dgmDvr structure

Parameters:

cfg

The datagram configuration list. This is a variable length list containing various configuration parameters. See the QSE__dgmDvrCfg routines for what can be specified and how to build this list.

void QSE_dgmDvrStatsClear ( QSE_dgmDvr * dvr )

Clears the datagram driver statistics.

Parameters:

dvr

Datagram driver context parameter

References _QSE_dgmDvr::stats.

const QSE_dgmDvrStats* QSE_dgmDvrStatsLocate ( QSE_dgmDvr * dvr )

Retrieves a pointer to the statistics.

Returns:: A readonly pointer to the statistics

Parameters:

dvr

Datagram driver context parameter

References _QSE_dgmDvr::stats.


Classes
struct	_QSE_dgmDvrStatsGbl
	Global counts of datagrams, contributions and records. More...
struct	_QSE_dgmDvrStatsDgm
	Statistics of this datagram, contributions and records. More...
struct	_QSE_dgmDvrStatsCtb
	Statistics of this contribution, records. More...
struct	_QSE_dgmDvrStats
	Statistics at the global, datagram, contribution and record level. More...
Typedefs
typedef struct _QSE_dgmDvrStatsGbl	QSE_dgmDvrStatsGbl
	Typedef for struct QSE_dgmDvrStatsGbl.
typedef struct _QSE_dgmDvrStatsDgm	QSE_dgmDvrStatsDgm
	Typedef for struct QSE_printCtxStatsDgm.
typedef struct _QSE_dgmDvrStatsCtb	QSE_dgmDvrStatsCtb
	Typedef for struct QSE_dgmDvrStatsCtb.
typedef struct _QSE_dgmDvrStats	QSE_dgmDvrStats
	Typedef for struct _QSE_dgmDvrStats.
typedef unsigned int(*	QSE_dgmDvrDgm )(void context, const LSF_datagram dgm, void *prm)
	Callback signature for user provided datagram handler.
typedef unsigned int(*	QSE_dgmDvrCtb )(void context, const LSF_contribution ctb, void *prm)
	Callback signature for user provided context handler.
typedef unsigned int(*	QSE_dgmDvrRec )(void context, const LSF_record rec, void *prm)
	Callback signature for user provided record handler.
typedef enum _QSE_DGMDVR_FATE_K	QSE_DGMDVR_FATE_K
	Typedef for enum _QSE_DGMDVR_FATE_K.
typedef enum _QSE_DGMDVR_PRM_K	QSE_DGMDVR_PRM_K
Enumerations
enum	_QSE_DGMDVR_FATE_K { QSE_DGMDVR_FATE_K_PROCESS = 0, QSE_DGMDVR_FATE_K_CONTINUE = 0, QSE_DGMDVR_FATE_K_STOP = 1, QSE_DGMDVR_FATE_K_NEXT_DATAGRAM = 2, QSE_DGMDVR_FATE_K_NEXT_CONTRIBUTION = 3 }
	Fate returned by the print driver callback routine to determine whether more events are processed or not. More...
enum	_QSE_DGMDVR_PRM_K { QSE_DGMDVR_PRM_K_END = 0, QSE_DGMDVR_PRM_K_ECOUNT = 1, QSE_DGMDVR_PRM_K_ESKIP = 2, QSE_DGMDVR_PRM_K_PCOUNT = 3, QSE_DGMDVR_PRM_K_PSKIP = 4 }
	Enumerates the print driver options. More...
Functions
unsigned int	QSE_dgmDvrSizeof (const unsigned int *cfg)
	Returns the size, in bytes of a QSE_dgmDvr structure.
QSE_dgmDvr *	QSE_dgmDvrConstruct (QSE_dgmDvr dvr, const unsigned int dvr_cfg, QSE_updateAtDatagram update_dgm, QSE_updateAtContribution update_ctb, QSE_updateAtRecord update_rec, void update_ctx, QSE_dgmDvrDgm handle_dgm, QSE_dgmDvrCtb handle_ctb, QSE_dgmDvrRec handle_rec, void handle_ctx)
	Constructs/initializes the datagram context control block.
LSF_scanContributionHandler	QSE_dgmDvrDatagram (QSE_dgmDvr dvr, const LSF_datagram datagram)
	Handles each datagram.
int	QSE_dgmDvrProcess (QSE_dgmDvr dvr, const LSF_datagram dgms, int dgms_len)
	Convenience routine for the CCSDS_istreamProcess routine.
void	QSE_dgmDvrDestruct (QSE_dgmDvr *dvr)
	Frees the QSE datagram driver context.
const QSE_dgmDvrStats *	QSE_dgmDvrStatsLocate (QSE_dgmDvr *dvr)
	Retrieves a pointer to the statistics.
void	QSE_dgmDvrStatsClear (QSE_dgmDvr *dvr)
	Clears the datagram driver statistics.
static __inline unsigned int *	QSE__dgmDvrCfgEventSkip (unsigned int *cfg, int nskip)
	Adds a configuration parameter used to specify that nskip events be skipped before sending the user's event handler its first event.
static __inline unsigned int *	QSE__dgmDvrCfgEventCount (unsigned int *cfg, int nprocess)
	Adds a configuration parameter used to specify that the datagram driver will limit the number of events sent to the user's event handler to nprocess.
static __inline unsigned int *	QSE__dgmDvrCfgEventSkipShr (unsigned int cfg, int pskip)
	Adds a configuration parameter used to specify that nskip events be skipped before sending the user's event handler its first event.
static __inline unsigned int *	QSE__dgmDvrCfgEventCountShr (unsigned int cfg, int pprocess)
	Adds a configuration parameter used to specify that the datagram driver will limit the number of events sent to the user's event handler to nprocess.
static __inline unsigned int *	QSE__dgmDvrCfgTerminate (unsigned int *cfg)
	Terminates a configuration list.
static __inline unsigned int *	QSE__dgmDvrCfgStorePtr (unsigned int cfg, int type, void ptr)
	Store the pointer in the configuration array.