Working with time series topics.

Functions
long	diffusion_time_series_event_metadata_get_sequence (const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *event_metadata)
	Return the sequence number identifying this event within its time series.
long	diffusion_time_series_event_metadata_get_timestamp (const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *event_metadata)
	Return the event timestamp.
char *	diffusion_time_series_event_metadata_get_author (const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *event_metadata)
	Returns a memory allocated string of the server-authenticated identity of the session that created the event.
DIFFUSION_TIME_SERIES_EVENT_METADATA_T *	diffusion_time_series_event_metadata_dup (const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *event_metadata)
	Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_EVENT_METADATA_T
void	diffusion_time_series_event_metadata_free (DIFFUSION_TIME_SERIES_EVENT_METADATA_T *event_metadata)
	Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_METADATA_T
long	diffusion_time_series_event_get_sequence (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	Return the sequence number identifying this event within its time series.
long	diffusion_time_series_event_get_timestamp (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	Return the event timestamp.
char *	diffusion_time_series_event_get_author (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	Returns a memory allocated string of the server-authenticated identity of the session that created the event.
DIFFUSION_VALUE_T *	diffusion_time_series_event_get_value (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	Returns a memory allocated DIFFUSION_VALUE_T, the time series event's value.
DIFFUSION_TIME_SERIES_EVENT_METADATA_T *	diffusion_time_series_event_get_original_event (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	If this is an edit event, returns the metadata of the original event that this event replaces; otherwise returns this event.
int	diffusion_time_series_event_is_edit_event (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	Return whether this is an edit event.
DIFFUSION_TIME_SERIES_EVENT_T *	diffusion_time_series_event_with_value (const DIFFUSION_TIME_SERIES_EVENT_T *event, const BUF_T *value)
	Clone this event with a different value.
bool	read_diffusion_time_series_event (const DIFFUSION_VALUE_T *value, DIFFUSION_TIME_SERIES_EVENT_T **event, DIFFUSION_API_ERROR *error)
	Get the DIFFUSION_TIME_SERIES_EVENT_T update value.
DIFFUSION_TIME_SERIES_EVENT_T *	diffusion_time_series_event_dup (const DIFFUSION_TIME_SERIES_EVENT_T *event)
	Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_EVENT_T.
void	diffusion_time_series_event_free (DIFFUSION_TIME_SERIES_EVENT_T *event)
	Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_T
bool	diffusion_time_series_append (SESSION_T *session, const DIFFUSION_TIME_SERIES_APPEND_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Update a time series topic by appending a new value.
bool	diffusion_time_series_timestamp_append (SESSION_T *session, const DIFFUSION_TIME_SERIES_TIMESTAMP_APPEND_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Update a time series topic by appending a new value with a supplied timestamp.
bool	diffusion_time_series_edit (SESSION_T *session, const DIFFUSION_TIME_SERIES_EDIT_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Update a time series topic by appending a new value that overrides the value of an existing event.
DIFFUSION_TIME_SERIES_RANGE_QUERY_T *	diffusion_time_series_range_query (void)
	Return a default range query that performs a value range query of an entire time series.
void	diffusion_time_series_range_query_free (DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query)
	Free a memory allocated DIFFUSION_TIME_SERIES_RANGE_QUERY_T

Detailed Description

Function Documentation

diffusion_time_series_append()

bool diffusion_time_series_append	(	SESSION_T *	session,
		const DIFFUSION_TIME_SERIES_APPEND_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Update a time series topic by appending a new value.

The server will add an event to the end of the time series based on the supplied value, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_time_series_append request and notification callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

diffusion_time_series_edit()

bool diffusion_time_series_edit	(	SESSION_T *	session,
		const DIFFUSION_TIME_SERIES_EDIT_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Update a time series topic by appending a new value that overrides the value of an existing event.

The existing event is identified by its sequence number and must be an original event.

The server will add an edit event to the end of the time series based on the supplied value, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_time_series_edit request and notification callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

diffusion_time_series_event_dup()

DIFFUSION_TIME_SERIES_EVENT_T * diffusion_time_series_event_dup

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_EVENT_T.

diffusion_time_series_event_free should be called on this pointer when no longer needed.

Parameters

event

the event to be copied.

Returns

a copy of a DIFFUSION_TIME_SERIES_EVENT_T. NULL, if event is NULL.

diffusion_time_series_event_free()

void diffusion_time_series_event_free

(

DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_T

Parameters

event

the DIFFUSION_TIME_SERIES_EVENT_T to be freed.

diffusion_time_series_event_get_author()

char * diffusion_time_series_event_get_author

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Returns a memory allocated string of the server-authenticated identity of the session that created the event.

This should be freed with free when no longer needed.

Parameters

event

The time series event

Returns

the principal that created the event, or ANONYMOUS if the session that created the event was not authenticated. If event is NULL, NULL will be returned.

diffusion_time_series_event_get_original_event()

DIFFUSION_TIME_SERIES_EVENT_METADATA_T * diffusion_time_series_event_get_original_event

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

If this is an edit event, returns the metadata of the original event that this event replaces; otherwise returns this event.

The result is always the metadata of an original event, never that of an edit event.

Parameters

event

The time series event

Returns

if the returned metadata is equal to event metadata, this is not an edit event; otherwise, the sequence number of the event replaced by this edit event. If event is NULL, NULL will be returned

diffusion_time_series_event_get_sequence()

long diffusion_time_series_event_get_sequence

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Return the sequence number identifying this event within its time series.

Assigned by the server when the event is created.

Sequence numbers are unique within a time series. Each event appended to a time series is assigned a sequence number that is is equal to the sequence number of the preceding event plus one.

Parameters

event

The time series event

Returns

the sequence number. If event is NULL, -1 is returned.

diffusion_time_series_event_get_timestamp()

long diffusion_time_series_event_get_timestamp

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Return the event timestamp.

Assigned by the server when the event is created.

Events do not have unique timestamps. Events with different sequence numbers may have the same timestamp.

Subsequent events in a time series usually have timestamps that are greater or equal to the timestamps of earlier events, but this is not guaranteed due to changes to the time source used by the server.

Parameters

event

The time series event

Returns

the difference, measured in milliseconds, between the time the server added the event to the time series and midnight, January 1, 1970 UTC. If event is NULL, -1 is returned.

diffusion_time_series_event_get_value()

DIFFUSION_VALUE_T * diffusion_time_series_event_get_value

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Returns a memory allocated DIFFUSION_VALUE_T, the time series event's value.

This should be freed with diffusion_value_free when no longer needed.

Parameters

event

The time series event

Returns

the time series event's value. If event is NULL, NULL will be returned.

diffusion_time_series_event_is_edit_event()

int diffusion_time_series_event_is_edit_event

(

const DIFFUSION_TIME_SERIES_EVENT_T *

event

)

Return whether this is an edit event.

Returns

1 if this is an edit event, otherwise, 0 is returned showing that this is an original event. If event is NULL, -1 is returned.

diffusion_time_series_event_metadata_dup()

DIFFUSION_TIME_SERIES_EVENT_METADATA_T * diffusion_time_series_event_metadata_dup

(

const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *

event_metadata

)

Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_EVENT_METADATA_T

Parameters

event_metadata

The event metadata to be copied.

This should be freed with diffusion_time_series_event_metadata_free when no longer needed.

Returns

a copy of a DIFFUSION_TIME_SERIES_EVENT_METADATA_T. NULL, if event_metadata is NULL.

diffusion_time_series_event_metadata_free()

void diffusion_time_series_event_metadata_free

(

DIFFUSION_TIME_SERIES_EVENT_METADATA_T *

event_metadata

)

Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_METADATA_T

Parameters

event_metadata

The DIFFUSION_TIME_SERIES_EVENT_METADATA_T to be freed.

diffusion_time_series_event_metadata_get_author()

char * diffusion_time_series_event_metadata_get_author

(

const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *

event_metadata

)

Returns a memory allocated string of the server-authenticated identity of the session that created the event.

Parameters

event_metadata

The event metadata

Returns

the principal that created the event, or ANONYMOUS if the session that created the event was not authenticated. If event_metadata is NULL, NULL will be returned.

diffusion_time_series_event_metadata_get_sequence()

long diffusion_time_series_event_metadata_get_sequence

(

const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *

event_metadata

)

Return the sequence number identifying this event within its time series.

Assigned by the server when the event is created.

Sequence numbers are unique within a time series. Each event appended to a time series is assigned a sequence number that is is equal to the sequence number of the preceding event plus one.

Parameters

event_metadata

The event metadata

Returns

the sequence number. If event_metadata is NULL, -1 is returned.

diffusion_time_series_event_metadata_get_timestamp()

long diffusion_time_series_event_metadata_get_timestamp

(

const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *

event_metadata

)

Return the event timestamp.

Assigned by the server when the event is created.

Events do not have unique timestamps. Events with different sequence numbers may have the same timestamp.

Subsequent events in a time series usually have timestamps that are greater or equal to the timestamps of earlier events, but this is not guaranteed due to changes to the time source used by the server.

Parameters

event_metadata

The event metadata

Returns

the difference, measured in milliseconds, between the time the server added the event to the time series and midnight, January 1, 1970 UTC. If event_metadata is NULL, -1 is returned.

diffusion_time_series_event_with_value()

DIFFUSION_TIME_SERIES_EVENT_T * diffusion_time_series_event_with_value	(	const DIFFUSION_TIME_SERIES_EVENT_T *	event,
		const BUF_T *	value
	)

Clone this event with a different value.

This method is useful when further transformation of the received value is needed, but the application wishes to preserve other event attributes. For example, if a String value is received which the session wishes to interpret as JSON, it can do the following.

DIFFUSION_VALUE_T *value = diffusion_time_series_event_get_value(event);
char *result;
read_diffusion_string_value(result, NULL);

BUF_T *json_value = buf_create();
write_diffusion_json_value(result, json_value);

DIFFUSION_TIME_SERIES_EVENT_T *event_json = diffusion_time_series_event_with_value(event, json_value);

All attributes other than the value will be copied from this event. The result will only equal this event if newValue equals this event's value.

Parameters

event	The time series event
value	The new value

Returns

a copy of this event with a different value. If event or value is NULL, NULL will be returned.

diffusion_time_series_range_query()

DIFFUSION_TIME_SERIES_RANGE_QUERY_T * diffusion_time_series_range_query

(

void

)

Return a default range query that performs a value range query of an entire time series.

Further queries with different parameters can be configured using the DIFFUSION_TIME_SERIES_RANGE_QUERY_T functions (located in range-query.h).

The result provides raw CBOR encoded bytes values, making it compatible with any event data type supported by time series topics. A query with a more specific value type can be configured using diffusion_time_series_range_query_as.

A DIFFUSION_TIME_SERIES_RANGE_QUERY_T equal to the one returned by this method can be created from an arbitrary range query as follows.

DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query = diffusion_time_series_range_query();
diffusion_time_series_range_query_for_values(range_query, NULL);
diffusion_time_series_range_query_from_start(range_query, NULL);
diffusion_time_series_range_query_until_last(range_query, 0, NULL);
diffusion_time_series_range_query_limit(range_query, LONG_MAX, NULL);
diffusion_time_series_range_query_as(range_query, NULL, NULL);

Returns

a DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the default settings

diffusion_time_series_range_query_free()

void diffusion_time_series_range_query_free

(

DIFFUSION_TIME_SERIES_RANGE_QUERY_T *

range_query

)

Free a memory allocated DIFFUSION_TIME_SERIES_RANGE_QUERY_T

Parameters

range_query

The DIFFUSION_TIME_SERIES_RANGE_QUERY_T to be freed.

diffusion_time_series_timestamp_append()

bool diffusion_time_series_timestamp_append	(	SESSION_T *	session,
		const DIFFUSION_TIME_SERIES_TIMESTAMP_APPEND_PARAMS_T	params,
		DIFFUSION_API_ERROR *	api_error
	)

Update a time series topic by appending a new value with a supplied timestamp.

The server will add an event to the end of the time series based on the supplied value and timestam, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Parameters

session	The current session. If NULL, this function returns immediately.
params	Parameters defining the diffusion_time_series_timestamp_append request and notification callbacks.
api_error	Populated on API error. Can be NULL.

Returns

true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.

read_diffusion_time_series_event()

bool read_diffusion_time_series_event	(	const DIFFUSION_VALUE_T *	value,
		DIFFUSION_TIME_SERIES_EVENT_T **	event,
		DIFFUSION_API_ERROR *	error
	)

Get the DIFFUSION_TIME_SERIES_EVENT_T update value.

Parameters

value	Value to read from.
event	Pointer to a pointer where the time series event data will be stored
error	Populated if an error occurs. Can be NULL.

Returns

true if the value is successfully read and the event pointer value is set to a pointer containing the string data. False otherwise.