libdata-unified-status  1.1.1
Functions
Persistent storage

Functions

struct soh_store_t * soh_store_new (void(*warning)(const char *message))
 Create a new persistent store. More...
 
void soh_store_free (struct soh_store_t *store)
 Free a persistent store object.
 
void soh_store_update (struct soh_store_t *store, const struct iso8601_date *timestamp, const char *st, int st_words, struct membuf_t *comp_buf)
 Update a persistent store object. More...
 
void soh_store_serialise (const struct soh_store_t *store, struct membuf_t *buf)
 Serialise persistent store into unified status words. More...
 

Detailed Description

A set of routines to maintain state-of-health information at a high level useful for data processing. State of health information is held in a struct soh_store_t object, which holds one object of each type that the library can parse. Blocks of unified status information are passed to soh_store_update(), along with the generation timestamp. This information is used to update the store, if relevant (i.e. if the timestamp is later).

Compression

Initial unified status support in Guralp Systems digitising equipment causes the emission of one unified status packet per second. This is somewhat excessive for slow-changing data and can lead to large bandwidth requirements when using fixed-size chunks to transfer data (i.e. Scream). It is envisaged that future firmware updates may use a "compression" algorithm to only transmit significant data. Such an algorithm is implemented by soh_store_update(). Effectively, only significant changes are transmitted. Changes are significant if:

Per-channel information

Some status information (Channel status) is channel-specific. The persistent storage object is also intended for channel-specific applications. An application must ensure that only the relevant per-channel status words are passed to soh_store_update().

When storing channel-specific information, the instrument number and component fields will be stored but their meaning is never examined by this code. Thus if three per-channel updates from a triaxial instrument were provided to the update function, whichever came last would be used (subject to the compression rules above). This is clearly not the desirable behaviour, so the status must be split before being provided to the update function.

Retrieving stored values

See:

Function Documentation

◆ soh_store_new()

struct soh_store_t* soh_store_new ( void(*)(const char *message)  warning)

Create a new persistent store.

Parameters
warningOptional warning function. May be 0.
Returns
Pointer to newly-allocated status storage object.

Allocates and initialises a new persistent status storage object. If desired, a warning function may be passed as warning. This function will be called with a human-readable error message if a tag cannot be parsed. If not provided, warnings are ignored.

◆ soh_store_update()

void soh_store_update ( struct soh_store_t *  store,
const struct iso8601_date *  timestamp,
const char *  st,
int  st_words,
struct membuf_t *  comp_buf 
)

Update a persistent store object.

Parameters
storePersistent storage object.
timestampTimestamp of latest status information.
stStatus data.
st_wordsLength of status data, in units of 32-bit words.
comp_bufOutput buffer into which compressed status is written. May be 0.

Uses the information in st to update the persistent store object store. The update will only occur if timestamp is later than the last-received data in store (earlier timestamps are ignored), and if the update is significant (see Compression).

If desired, a pointer to a memory buffer may be passed in comp_buf. If passed, then any update after the compression process (i.e. any change to the store object) will be serialised, in unified status words, and appended to comp_buf. This mode of operation allows the persistent store to be used as a compressing filter.

Warning
See section Per-channel information.

◆ soh_store_serialise()

void soh_store_serialise ( const struct soh_store_t *  store,
struct membuf_t *  buf 
)

Serialise persistent store into unified status words.

Parameters
storePersistent storage object.
bufBuffer to write status into.

This function will serialise the status information in store and append unified status words onto buf. If store was never updated, no information will be written. Otherwise, all the latest information will be written.