Structures and funtions to support extra headers. More...

Data Structures
struct	MSEHEventDetection
	Container for event detection parameters for use in extra headers. More...

struct	MSEHCalibration
	Container for calibration parameters for use in extra headers. More...

struct	MSEHTimingException
	Container for timing exception parameters for use in extra headers. More...

struct	MSEHRecenter
	Container for recenter parameters for use in extra headers. More...

Macros
#define	mseh_get(msr, ptr, valueptr, type, maxlength) mseh_get_ptr_r (msr, ptr, valueptr, type, maxlength, NULL)
	A simple wrapper to access any type of extra header.

#define	mseh_get_number(msr, ptr, valueptr) mseh_get_ptr_r (msr, ptr, valueptr, 'n', 0, NULL)
	A simple wrapper to access a number type extra header.

#define	mseh_get_int64(msr, ptr, valueptr) mseh_get_ptr_r (msr, ptr, valueptr, 'i', 0, NULL)
	A simple wrapper to access a number type extra header.

#define	mseh_get_string(msr, ptr, buffer, maxlength) mseh_get_ptr_r (msr, ptr, buffer, 's', maxlength, NULL)
	A simple wrapper to access a string type extra header.

#define	mseh_get_boolean(msr, ptr, valueptr) mseh_get_ptr_r (msr, ptr, valueptr, 'b', 0, NULL)
	A simple wrapper to access a boolean type extra header.

#define	mseh_exists(msr, ptr) (!mseh_get_ptr_r (msr, ptr, NULL, 0, 0, NULL))
	A simple wrapper to test existence of an extra header.

#define	mseh_set(msr, ptr, valueptr, type) mseh_set_ptr_r (msr, ptr, valueptr, type, NULL)
	A simple wrapper to set any type of extra header.

#define	mseh_set_number(msr, ptr, valueptr) mseh_set_ptr_r (msr, ptr, valueptr, 'n', NULL)
	A simple wrapper to set a number type extra header.

#define	mseh_set_int64(msr, ptr, valueptr) mseh_set_ptr_r (msr, ptr, valueptr, 'i', NULL)
	A simple wrapper to set a number type extra header.

#define	mseh_set_string(msr, ptr, valueptr) mseh_set_ptr_r (msr, ptr, valueptr, 's', NULL)
	A simple wrapper to set a string type extra header.

#define	mseh_set_boolean(msr, ptr, valueptr) mseh_set_ptr_r (msr, ptr, valueptr, 'b', NULL)
	A simple wrapper to set a boolean type extra header.

Typedefs
typedef struct LM_PARSED_JSON_s	LM_PARSED_JSON
	Internal structure for holding parsed JSON extra headers.

Functions
int	mseh_get_ptr_r (const MS3Record msr, const char ptr, void value, char type, uint32_t maxlength, LM_PARSED_JSON *parsestate)
	Search for and return an extra header value.

int	mseh_set_ptr_r (MS3Record msr, const char ptr, void value, char type, LM_PARSED_JSON *parsestate)
	Set the value of extra header values.

int	mseh_add_event_detection_r (MS3Record msr, const char ptr, MSEHEventDetection eventdetection, LM_PARSED_JSON *parsestate)
	Add event detection to the extra headers of the given record.

int	mseh_add_calibration_r (MS3Record msr, const char ptr, MSEHCalibration calibration, LM_PARSED_JSON *parsestate)
	Add calibration to the extra headers of the given record.

int	mseh_add_timing_exception_r (MS3Record msr, const char ptr, MSEHTimingException exception, LM_PARSED_JSON *parsestate)
	Add timing exception to the extra headers of the given record.

int	mseh_add_recenter_r (MS3Record msr, const char ptr, MSEHRecenter recenter, LM_PARSED_JSON *parsestate)
	Add recenter event to the extra headers of the given record.

int	mseh_serialize (MS3Record msr, LM_PARSED_JSON *parsestate)
	Generate extra headers string (serialize) from internal state.

void	mseh_free_parsestate (LM_PARSED_JSON **parsestate)
	Free internally parsed (deserialized) JSON data.

int	mseh_replace (MS3Record msr, char jsonstring)
	Replace extra headers with supplied JSON.

int	mseh_print (const MS3Record *msr, int indent)
	Print the extra header structure for the specified MS3Record.

Detailed Description

Structures and funtions to support extra headers.

Extra headers are stored as JSON within a data record header using an anonymous, root object as a container for all extra headers. For a full description consult the format specification.

The library functions supporting extra headers allow specific header identification using JSON Pointer identification. In this notation each path element is an object until the final element which is a key to specified header value.

For example, a path specified as:

"/objectA/objectB/header"

would correspond to the single JSON value in:

{
   "objectA": {
     "objectB": {
       "header":VALUE
      }
   }
}

Data Structure Documentation

◆ MSEHEventDetection

struct MSEHEventDetection

Container for event detection parameters for use in extra headers.

Actual values are optional, with special values indicating an unset state.

See also: mseh_add_event_detection_r

Data Fields
char	type[30]	Detector type (e.g. "MURDOCK"), zero length = not included
char	detector[30]	Detector name, zero length = not included
double	signalamplitude	SignalAmplitude, 0.0 = not included
double	signalperiod	Signal period, 0.0 = not included
double	backgroundestimate	Background estimate, 0.0 = not included
char	wave[30]	Detection wave (e.g. "DILATATION"), zero length = not included
char	units[30]	Units of amplitude and background estimate (e.g. "COUNTS"), zero length = not included
nstime_t	onsettime	Onset time, NSTUNSET = not included
uint8_t	medsnr[6]	Signal to noise ratio for Murdock event detection, all zeros = not included
int	medlookback	Murdock event detection lookback value, -1 = not included
int	medpickalgorithm	Murdock event detection pick algoritm, -1 = not included
struct MSEHEventDetection *	next	Pointer to next, NULL if none

◆ MSEHCalibration

struct MSEHCalibration

Container for calibration parameters for use in extra headers.

Actual values are optional, with special values indicating an unset state.

See also: mseh_add_calibration

Data Fields
char	type[30]	Calibration type (e.g. "STEP", "SINE", "PSEUDORANDOM"), zero length = not included
nstime_t	begintime	Begin time, NSTUNSET = not included
nstime_t	endtime	End time, NSTUNSET = not included
int	steps	Number of step calibrations, -1 = not included
int	firstpulsepositive	Boolean, step cal. first pulse, -1 = not included
int	alternatesign	Boolean, step cal. alt. sign, -1 = not included
char	trigger[30]	Trigger, e.g. AUTOMATIC or MANUAL, zero length = not included
int	continued	Boolean, continued from prev. record, -1 = not included
double	amplitude	Amp. of calibration signal, 0.0 = not included
char	inputunits[30]	Units of input (e.g. volts, amps), zero length = not included
char	amplituderange[30]	E.g PEAKTOPTEAK, ZEROTOPEAK, RMS, RANDOM, zero length = not included
double	duration	Duration in seconds, 0.0 = not included
double	sineperiod	Period of sine, 0.0 = not included
double	stepbetween	Interval bewteen steps, 0.0 = not included
char	inputchannel[30]	Channel of input, zero length = not included
double	refamplitude	Reference amplitude, 0.0 = not included
char	coupling[30]	Coupling, e.g. Resistive, Capacitive, zero length = not included
char	rolloff[30]	Rolloff of filters, zero length = not included
char	noise[30]	Noise for PR cals, e.g. White or Red, zero length = not included
struct MSEHCalibration *	next	Pointer to next, NULL if none

◆ MSEHTimingException

struct MSEHTimingException

Container for timing exception parameters for use in extra headers.

Actual values are optional, with special values indicating an unset state.

See also: mseh_add_timing_exception

Data Fields
nstime_t	time	Time of exception, NSTUNSET = not included
float	vcocorrection	VCO correction, from 0 to 100%, <0 = not included
int	usec	[DEPRECATED] microsecond time offset, 0 = not included
int	receptionquality	Reception quality, 0 to 100% clock accurracy, <0 = not included
uint32_t	count	The count thereof, 0 = not included
char	type[16]	E.g. "MISSING" or "UNEXPECTED", zero length = not included
char	clockstatus[128]	Description of clock-specific parameters, zero length = not included

◆ MSEHRecenter

struct MSEHRecenter

Container for recenter parameters for use in extra headers.

Actual values are optional, with special values indicating an unset state.

See also: mseh_add_recenter

Data Fields
char	type[30]	Recenter type (e.g. "MASS", "GIMBAL"), zero length = not included
nstime_t	begintime	Begin time, NSTUNSET = not included
nstime_t	endtime	Estimated end time, NSTUNSET = not included
char	trigger[30]	Trigger, e.g. AUTOMATIC or MANUAL, zero length = not included

Typedef Documentation

◆ LM_PARSED_JSON

typedef struct LM_PARSED_JSON_s LM_PARSED_JSON

Internal structure for holding parsed JSON extra headers.

See also: mseh_get_ptr_r(); mseh_set_ptr_r()

Function Documentation

◆ mseh_get_ptr_r()

int mseh_get_ptr_r	(	const MS3Record *	msr,
		const char *	ptr,
		void *	value,
		char	type,
		uint32_t	maxlength,
		LM_PARSED_JSON **	parsestate )

extern

Search for and return an extra header value.

The extra header value is specified as a JSON Pointer (RFC 6901), e.g. '/objectA/objectB/header'.

This routine can get used to test for the existence of a value without returning the value by setting value to NULL.

If the target item is found (and value parameter is set) the value will be copied into the memory specified by value. The type value specifies the data type expected.

If a parsestate pointer is supplied, the parsed (deserialized) JSON data are stored here. This value may be used in subsequent calls to avoid re-parsing the JSON. The data must be freed with mseh_free_parsestate() when done reading the JSON. If this value is NULL the parse state will be created and destroyed on each call.

Parameters

[in]	msr	Parsed miniSEED record to search
[in]	ptr	Header value desired, as JSON Pointer
[out]	value	Buffer for value, of type `type`
[in]	type	Type of value expected, one of: `'n'` - value is type double `'i'` - value is type int64_t `'s'` - value is type char* (maximum length is: `maxlength` - 1) `'b'` - value of type int (boolean value of 0 or 1)
[in]	maxlength	Maximum length of string value
[in]	parsestate	Parsed state for multiple operations, can be NULL

Return values

0	on success
1	when the value was not found
2	when the value is of a different type

Returns: A (negative) libmseed error code on error

MessageOnError - this function logs a message on error

See also: mseh_free_parsestate()

◆ mseh_set_ptr_r()

int mseh_set_ptr_r	(	MS3Record *	msr,
		const char *	ptr,
		void *	value,
		char	type,
		LM_PARSED_JSON **	parsestate )

extern

Set the value of extra header values.

The extra header value is specified as a JSON Pointer (RFC 6901), e.g. '/objectA/objectB/header'.

For most value types, if the ptr or final header values do not exist they will be created. If the header value exists it will be replaced. When the value type is 'M', for Merge Patch (RFC 7386), the location indicated by ptr must exist.

The type value specifies the data type expected for value.

If a parsestate pointer is supplied, the parsed (deserialized) JSON data are stored here. This value may be used in subsequent calls to avoid re-parsing the JSON. When done setting headers using this functionality the following must be done:

call mseh_serialize() to create the JSON headers before writing the record
free the parsestate data with mseh_free_parsestate() If this value is NULL the parse state will be created and destroyed on each call.

Parameters

[in]	msr	Parsed miniSEED record to modify
[in]	ptr	Header value to set as JSON Pointer, or JSON Merge Patch
[in]	value	Buffer for value, of type `type`
[in]	type	Type of value expected, one of: `'n'` - value is type double `'i'` - value is type int64_t `'s'` - value is type char* `'b'` - value is type int (boolean value of 0 or 1) `'M'` - value is type char* and a Merge Patch to apply at ptr `'V'` - value is type yyjson_mut_val* to set/replace (internal use) `'A'` - value is type yyjson_mut_val* to append to array (internal use)
[in]	parsestate	Parsed state for multiple operations, can be NULL

Return values

0	on success, otherwise a (negative) libmseed error code.

MessageOnError - this function logs a message on error

See also: mseh_free_parsestate(); mseh_serialize()

◆ mseh_add_event_detection_r()

int mseh_add_event_detection_r	(	MS3Record *	msr,
		const char *	ptr,
		MSEHEventDetection *	eventdetection,
		LM_PARSED_JSON **	parsestate )

extern

Add event detection to the extra headers of the given record.

If ptr is NULL, the default is '/FDSN/Event/Detection'.

Parameters

[in]	msr	Parsed miniSEED record to query
[in]	ptr	Header value desired, specified in dot notation
[in]	eventdetection	Structure with event detection values
[in]	parsestate	Parsed state for multiple operations, can be NULL

Returns: 0 on success, otherwise a (negative) libmseed error code.

MessageOnError - this function logs a message on error

◆ mseh_add_calibration_r()

int mseh_add_calibration_r	(	MS3Record *	msr,
		const char *	ptr,
		MSEHCalibration *	calibration,
		LM_PARSED_JSON **	parsestate )

extern

Add calibration to the extra headers of the given record.

If ptr is NULL, the default is '/FDSN/Calibration/Sequence'.

Parameters

[in]	msr	Parsed miniSEED record to query
[in]	ptr	Header value desired, specified in dot notation
[in]	calibration	Structure with calibration values
[in]	parsestate	Parsed state for multiple operations, can be NULL

Returns: 0 on success, otherwise a (negative) libmseed error code.

MessageOnError - this function logs a message on error

◆ mseh_add_timing_exception_r()

int mseh_add_timing_exception_r	(	MS3Record *	msr,
		const char *	ptr,
		MSEHTimingException *	exception,
		LM_PARSED_JSON **	parsestate )

extern

Add timing exception to the extra headers of the given record.

If ptr is NULL, the default is '/FDSN/Time/Exception'.

Parameters

[in]	msr	Parsed miniSEED record to query
[in]	ptr	Header value desired, specified in dot notation
[in]	exception	Structure with timing exception values
[in]	parsestate	Parsed state for multiple operations, can be NULL

Returns: 0 on success, otherwise a (negative) libmseed error code.

MessageOnError - this function logs a message on error

◆ mseh_add_recenter_r()

int mseh_add_recenter_r	(	MS3Record *	msr,
		const char *	ptr,
		MSEHRecenter *	recenter,
		LM_PARSED_JSON **	parsestate )

extern

Add recenter event to the extra headers of the given record.

If ptr is NULL, the default is '/FDSN/Recenter/Sequence'.

Parameters

[in]	msr	Parsed miniSEED record to query
[in]	ptr	Header value desired, specified in dot notation
[in]	recenter	Structure with recenter values
[in]	parsestate	Parsed state for multiple operations, can be NULL

Returns: 0 on success, otherwise a (negative) libmseed error code.

MessageOnError - this function logs a message on error

◆ mseh_serialize()

int mseh_serialize	(	MS3Record *	msr,
		LM_PARSED_JSON **	parsestate )

extern

Generate extra headers string (serialize) from internal state.

Generate the extra headers JSON string from the internal parse state created by mseh_set_ptr_r().

Parameters

[in]	msr	MS3Record to generate extra headers for
[in]	parsestate	Internal parsed state associated with msr

Returns: Length of extra headers on success, otherwise a (negative) libmseed error code

See also: mseh_set_ptr_r()

◆ mseh_free_parsestate()

void mseh_free_parsestate ( LM_PARSED_JSON ** parsestate )

extern

Free internally parsed (deserialized) JSON data.

Free the memory associated with JSON data parsed by mseh_get_ptr_r() or mseh_set_ptr_r(), specifically the data at the parsestate pointer.

Parameters

[in] parsestate Internal parsed state associated with msr

See also: mseh_get_ptr_r(); mseh_set_ptr_r()

◆ mseh_replace()

int mseh_replace	(	MS3Record *	msr,
		char *	jsonstring )

extern

Replace extra headers with supplied JSON.

Parse the supplied JSON string, re-serialize into compact form, and replace the extra headers of msr with the result.

To remove all of the extra headers, set jsonstring to NULL.

This function cannot be used in combination with the routines that use a parsed state, i.e. mseh_get_ptr_r() and mseh_set_ptr_r().

Parameters

[in]	msr	MS3Record to generate extra headers for
[in]	jsonstring	JSON replacment for extra headers of msr

Returns: Length of extra headers on success, otherwise a (negative) libmseed error code

◆ mseh_print()

int mseh_print	(	const MS3Record *	msr,
		int	indent )

extern

Print the extra header structure for the specified MS3Record.

Output is printed in a pretty, formatted form for readability and the anonymous, root object container (the outer {}) is not printed.

Parameters

[in]	msr	MS3Record with extra headers to pring
[in]	indent	Number of spaces to indent output

Returns: 0 on success and a (negative) libmseed error code on error.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ MSEHEventDetection

◆ MSEHCalibration

◆ MSEHTimingException

◆ MSEHRecenter

Typedef Documentation

◆ LM_PARSED_JSON

Function Documentation

◆ mseh_get_ptr_r()

◆ mseh_set_ptr_r()

◆ mseh_add_event_detection_r()

◆ mseh_add_calibration_r()

◆ mseh_add_timing_exception_r()

◆ mseh_add_recenter_r()

◆ mseh_serialize()

◆ mseh_free_parsestate()

◆ mseh_replace()

◆ mseh_print()