Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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. More...
 
long diffusion_time_series_event_metadata_get_timestamp (const DIFFUSION_TIME_SERIES_EVENT_METADATA_T *event_metadata)
 Return the event timestamp. More...
 
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. More...
 
DIFFUSION_TIME_SERIES_EVENT_METADATA_Tdiffusion_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 More...
 
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 More...
 
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. More...
 
long diffusion_time_series_event_get_timestamp (const DIFFUSION_TIME_SERIES_EVENT_T *event)
 Return the event timestamp. More...
 
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. More...
 
DIFFUSION_VALUE_Tdiffusion_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. More...
 
DIFFUSION_TIME_SERIES_EVENT_METADATA_Tdiffusion_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. More...
 
int diffusion_time_series_event_is_edit_event (const DIFFUSION_TIME_SERIES_EVENT_T *event)
 Return whether this is an edit event. More...
 
DIFFUSION_TIME_SERIES_EVENT_Tdiffusion_time_series_event_with_value (const DIFFUSION_TIME_SERIES_EVENT_T *event, const BUF_T *value)
 Clone this event with a different value. More...
 
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. More...
 
DIFFUSION_TIME_SERIES_EVENT_Tdiffusion_time_series_event_dup (const DIFFUSION_TIME_SERIES_EVENT_T *event)
 Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_EVENT_T More...
 
void diffusion_time_series_event_free (DIFFUSION_TIME_SERIES_EVENT_T *event)
 Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_T More...
 
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. More...
 
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. More...
 
DIFFUSION_TIME_SERIES_RANGE_QUERY_Tdiffusion_time_series_range_query (void)
 Return a default range query that performs a value range query of an entire time series. More...
 
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 More...
 

Detailed Description

Function Documentation

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
sessionThe current session. If NULL, this function returns immediately.
paramsParameters defining the diffusion_time_series_append request and notification callbacks.
api_errorPopulated 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.
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
sessionThe current session. If NULL, this function returns immediately.
paramsParameters defining the diffusion_time_series_edit request and notification callbacks.
api_errorPopulated 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_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

Parameters
eventthe event to be copied.
Returns
a copy of a DIFFUSION_TIME_SERIES_EVENT_T. NULL, if event is NULL.
void diffusion_time_series_event_free ( DIFFUSION_TIME_SERIES_EVENT_T event)

Free a memory allocated DIFFUSION_TIME_SERIES_EVENT_T

Parameters
eventthe 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.

Parameters
eventThe 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_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
eventThe 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
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
eventThe time series event
Returns
the sequence number. If event is NULL, -1 is returned.
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
eventThe 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_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
eventThe time series event
Returns
the time series event's value. If event is NULL, NULL will be returned.
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_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_metadataThe event metadata to be copied.
Returns
a copy of a DIFFUSION_TIME_SERIES_EVENT_METADATA_T. NULL, if event_metadata is NULL.
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_metadataThe 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.

Parameters
event_metadataThe 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.
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_metadataThe event metadata
Returns
the sequence number. If event_metadata is NULL, -1 is returned.
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_metadataThe 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_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
eventThe time series event
valueThe 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_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
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
event_metadataThe DIFFUSION_TIME_SERIES_RANGE_QUERY_T to be freed.
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
valueValue to read from.
eventPointer to a pointer where the time series event data will be stored
errorPopulated 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.