libdata-unified-status
1.1.1
|
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... | |
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).
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:
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.
See:
struct soh_store_t* soh_store_new | ( | void(*)(const char *message) | warning | ) |
Create a new persistent store.
warning | Optional warning function. May be 0. |
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.
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.
store | Persistent storage object. |
timestamp | Timestamp of latest status information. |
st | Status data. |
st_words | Length of status data, in units of 32-bit words. |
comp_buf | Output 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.
void soh_store_serialise | ( | const struct soh_store_t * | store, |
struct membuf_t * | buf | ||
) |
Serialise persistent store into unified status words.
store | Persistent storage object. |
buf | Buffer 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.