![]() |
Diffusion C API 6.12.0
|
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.
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. |
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.
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. |
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.
event | the event to be copied. |
void diffusion_time_series_event_free | ( | DIFFUSION_TIME_SERIES_EVENT_T * | event | ) |
Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_T
event | the DIFFUSION_TIME_SERIES_EVENT_T to be freed. |
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.
event | The time series 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.
event | The time series event |
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.
event | The time series event |
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.
event | The time series 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.
This should be freed with diffusion_value_free when no longer needed.
event | The time series 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_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
event_metadata | The event metadata to be copied. |
This should be freed with diffusion_time_series_event_metadata_free when no longer needed.
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
event_metadata | The DIFFUSION_TIME_SERIES_EVENT_METADATA_T to be freed. |
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.
event_metadata | The event metadata |
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.
event_metadata | The event metadata |
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.
event_metadata | The event metadata |
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.
event | The time series event |
value | The new value |
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);
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
range_query | The DIFFUSION_TIME_SERIES_RANGE_QUERY_T to be freed. |
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.
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. |
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.
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. |