Internal

Below functions are only used internally by the library.

Defines

TS_RET_IDS: Internal return type flags for payload data Return type flag: IDs

TS_RET_NAMES: Return type flag: Names

TS_RET_VALUES: Return type flag: Values

TS_RET_PATHS: Return type flag: Paths

TS_RET_DISCOVERY: Return type flag: Discovery

RECORD_INDEX_NONE: Value to use for record index if no index was specified

Functions

int ts_txt_process(struct ts_context *ts): Prepares JSMN parser, performs initial check of payload data and calls get/fetch/patch functions.

int ts_bin_process(struct ts_context *ts): Performs initial check of payload data and calls get/fetch/patch functions.

int ts_txt_get(struct ts_context *ts, const struct ts_data_object *endpoint, uint32_t ret_type, int record_index)

GET request (text mode).

List child data objects (function called without content / parameters)

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the endpoint data object.
ret_type – Return type flags (IDs, names and/or values).
record_index – Record index extracted from path (only applicable for TS_T_RECORDS).

int ts_bin_get(struct ts_context *ts, const struct ts_data_object *endpoint, uint32_t ret_type, int record_index)

GET request (binary mode).

List child data objects (function called without content)

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the endpoint data object.
ret_type – Return type flags (IDs, names and/or values).
record_index – Record index (only applicable for TS_T_RECORDS).

int ts_txt_fetch(struct ts_context *ts, const struct ts_data_object *endpoint)

FETCH request (text mode).

Read data object values (function called with an array as argument)

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the endpoint data object.

int ts_bin_fetch(struct ts_context *ts, const struct ts_data_object *endpoint, uint32_t ret_type, unsigned int pos_payload)

FETCH request (binary mode).

Read data object values (function called with an array as argument)

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the endpoint data object or NULL for root and special endpoints 0x16 (“_ids”) and 0x17 (“_paths”) as they don’t actually exist in the database.
ret_type – Return type flags (IDs, names and/or values).
pos_payload – Position of payload in req buffer.

int ts_txt_patch(struct ts_context *ts, const struct ts_data_object *endpoint)

PATCH request (text mode).

Write data object values in text mode (function called with a map as argument)

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to the endpoint data object.

int ts_bin_patch(struct ts_context *ts, const struct ts_data_object *endpoint, unsigned int pos_payload, uint8_t auth_flags, uint16_t subsets, int record_index)

PATCH request (binary mode).

Write data object values in binary mode (function called with a map as payload)

If subset is specified, objects not found are silently ignored. Otherwise, a NOT_FOUND error is raised.

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to endpoint object or NULL to consider any object
pos_payload – Position of payload in req buffer
auth_flags – Bitset to specify authentication status for different roles
subsets – Bitset to specifiy data item subsets to be considered, 0 to ignore
record_index – Record index (only applicable for TS_T_RECORDS).

int ts_txt_create(struct ts_context *ts, const struct ts_data_object *endpoint)

POST request to append data.

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to subset object where a new value shall be created.

int ts_txt_delete(struct ts_context *ts, const struct ts_data_object *endpoint)

DELETE request to delete data from object.

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to subset object from which a value shall be deleted.

Returns:

Length of response message in buffer or 0 in case of error.

int ts_txt_exec(struct ts_context *ts, const struct ts_data_object *endpoint)

Execute command in text mode.

Function called with a single data object name as argument.

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to executable object which shall be called.

Returns:

Length of response message in buffer or 0 in case of error.

int ts_bin_exec(struct ts_context *ts, const struct ts_data_object *endpoint, unsigned int pos_payload)

Execute command in binary mode (function called with a single data object name/id as argument).

Parameters:

ts – Pointer to ThingSet context.
endpoint – Pointer to executable object which shall be called.
pos_payload – Position of payload in req buffer

Returns:

Length of response message in buffer or 0 in case of error.

int ts_txt_response(struct ts_context *ts, int code)

Fill the resp buffer with a JSON response status message.

Parameters:

ts – Pointer to ThingSet context.
code – Numeric status code.

Returns:

Length of status message in buffer or 0 in case of error.

int ts_bin_response(struct ts_context *ts, uint8_t code)

Fill the resp buffer with a CBOR response status message.

Parameters:

ts – Pointer to ThingSet context.
code – Numeric status code.

Returns:

Length of status message in buffer or 0 in case of error.

int ts_json_serialize_value(struct ts_context *ts, char *buf, size_t size, const struct ts_data_object *object)

Serialize a object value into a JSON string.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the JSON value should be stored.
size – Size of the buffer, i.e. maximum allowed length of the value.
object – Pointer to object which should be serialized.

Returns:

Length of data written to buffer or 0 in case of error.

int ts_json_serialize_name_value(struct ts_context *ts, char *buf, size_t size, const struct ts_data_object *object)

Serialize object name and value as JSON object.

Same as ts_json_serialize_value, just that the object name is also serialized.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the JSON value should be stored.
size – Size of the buffer, i.e. maximum allowed length of the value.
object – Pointer to object which should be serialized.

Returns:

Length of data written to buffer or 0 in case of error.

int ts_json_deserialize_value(struct ts_context *ts, char *buf, size_t len, jsmntype_t type, const struct ts_data_object *object)

Deserialize a object value from a JSON string.

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the position of the value in a buffer.
len – Length of value in the buffer.
type – Type of the JSMN token as identified by the parser.
object – Pointer to object where the deserialized value should be stored.

Returns:

Number of tokens processed (always 1) or 0 in case of error.

int ts_get_path(struct ts_context *ts, char *buf, size_t size, const struct ts_data_object *object)

Write the path of an object into a buffer.

This function supports a maximum depth of 2 only (e.g. Meas/rBat_V).

Parameters:

ts – Pointer to ThingSet context.
buf – Pointer to the buffer where the path should be stored.
size – Size of the buffer, i.e. maximum allowed length of the value.
object – Pointer to object which should be serialized.

Returns:

Length of the string written to the buffer or value <= 0 in case of error.

struct ts_data_object *ts_get_endpoint_by_path(struct ts_context *ts, const char *path, size_t len, int *index)

Get the endpoint object of a provided path.

Similar to ts_get_object_by_path, but considers the number at the end if requesting a record

Parameters:

ts – Pointer to ThingSet context.
path – Path with multiple object names separated by forward slash.
len – Length of the entire path
index – Pointer to a variable used to store the index of a record.

Returns:

Pointer to data object or NULL if object is not found

JSON (JSMN)

The JSON parser is using the JSMN library.

Warning

doxygenfile: Cannot find file “jsmn.h

CBOR

The internal CBOR parser is very light-weight and contains only the features required for the ThingSet library.

Defines

CBOR_TYPE_MASK: most-significant 3 bits

CBOR_INFO_MASK: least-significant 5 bits

CBOR_UINT: Major type 0: Unsigned integers

CBOR_NEGINT: Major type 1: Negative integers

CBOR_BYTES: Major type 2: Bytes (binary)

CBOR_TEXT: Major type 3: Text (UTF-8)

CBOR_ARRAY: Major type 4: Array

CBOR_MAP: Major type 5: Map / Object

CBOR_TAG: Major type 6: Tag (for extension)

CBOR_MISC: Major type 7: Simple values and float

CBOR_NUM_MAX: Maximum number that can be directly encoded

CBOR_UINT8_FOLLOWS: Length specifier uint8 (0x18)

CBOR_UINT16_FOLLOWS: Length specifier uint16 (0x19)

CBOR_UINT32_FOLLOWS: Length specifier uint32 (0x1a)

CBOR_UINT64_FOLLOWS: Length specifier uint64 (0x1b)

CBOR_VAR_FOLLOWS: Indefinite length specifier (0x1f)

CBOR_DATETIME_STRING_FOLLOWS: Datetime string

CBOR_DATETIME_EPOCH_FOLLOWS: Datetime epoch

CBOR_DECFRAC_ARRAY_FOLLOWS: Decimal fraction

CBOR_FALSE: Simple value: false

CBOR_TRUE: Simple value: true

CBOR_NULL: Simple value: null

CBOR_UNDEFINED: Simple value: undefined

CBOR_SIMPLE: Simple value: uint8 follows

CBOR_FLOAT16: Half-precision float follows

CBOR_FLOAT32: Single-precision float follows

CBOR_FLOAT64: Double-precision float follows

CBOR_BREAK: Simple value: break

Functions

int cbor_serialize_uint(uint8_t *data, uint32_t value, size_t max_len)

Serialize unsigned integer value

Parameters:

data – Buffer where CBOR data shall be stored
value – Variable containing value to be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_int(uint8_t *data, int32_t value, size_t max_len)

Serialize signed integer value

Parameters:

data – Buffer where CBOR data shall be stored
value – Variable containing value to be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_decfrac(uint8_t *data, int32_t mantissa, int16_t exponent, size_t max_len)

Serialize decimal fraction (e.g. 1234 * 10^3)

Parameters:

data – Buffer where CBOR data shall be stored
mantissa – Mantissa of the value to be serialized
exponent – Exponent of the value to be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_float(uint8_t *data, float value, size_t max_len)

Serialize 32-bit float

Parameters:

data – Buffer where CBOR data shall be stored
value – Variable containing value to be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_bool(uint8_t *data, bool value, size_t max_len)

Serialize boolean

Parameters:

data – Buffer where CBOR data shall be stored
value – Variable containing value to be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_string(uint8_t *data, const char *value, size_t max_len)

Serialize string

Parameters:

data – Buffer where CBOR data shall be stored
value – Pointer to string that should be be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_bytes(uint8_t *data, const uint8_t *bytes, size_t num_bytes, size_t max_len)

Serialize bytes

Parameters:

data – Buffer where CBOR data shall be stored
bytes – Pointer to string that should be be serialized
num_bytes – Number of bytes from the buffer to be serialized
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_array(uint8_t *data, size_t num_elements, size_t max_len)

Serialize the header (length field) of an array

Actual elements of the array have to be serialized afterwards

Parameters:

data – Buffer where CBOR data shall be stored
num_elements – Number of elements in the array
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

Number of bytes added to buffer or 0 in case of error

int cbor_serialize_map(uint8_t *data, size_t num_elements, size_t max_len)

Serialize the header (length field) of a map (equivalent to JSON object)

Actual elements of the map have to be serialized afterwards

Parameters:

data – Buffer where CBOR data shall be stored
num_elements – Number of elements in the array
max_len – Maximum remaining space in buffer (i.e. max length of serialized data)

Returns:

number of bytes added to buffer or 0 in case of error

int cbor_deserialize_uint64(const uint8_t *data, uint64_t *value)

Deserialization (CBOR data to C values) Deserialize 64-bit unsigned integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_int64(const uint8_t *data, int64_t *value)

Deserialize 64-bit signed integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_uint32(const uint8_t *data, uint32_t *value)

Deserialize 32-bit unsigned integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_int32(const uint8_t *data, int32_t *value)

Deserialize 32-bit signed integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_uint16(const uint8_t *data, uint16_t *value)

Deserialize 16-bit unsigned integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_int16(const uint8_t *data, int16_t *value)

Deserialize 16-bit signed integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_uint8(const uint8_t *data, uint8_t *value)

Deserialize 8-bit unsigned integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_int8(const uint8_t *data, int8_t *value)

Deserialize 8-bit signed integer

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_decfrac(const uint8_t *data, int32_t *mantissa, const int16_t exponent)

Deserialize decimal fraction type

The exponent is fixed, so the mantissa is multiplied to match the exponent

Parameters:

data – Buffer containing CBOR data with matching type
mantissa – Pointer to the variable where the mantissa should be stored
exponent – Exponent of internally used variable in C

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_float(const uint8_t *data, float *value)

Deserialize 32-bit float

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_bool(const uint8_t *data, bool *value)

Deserialize bool

Parameters:

data – Buffer containing CBOR data with matching type
value – Pointer to the variable where the value should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_deserialize_string(const uint8_t *data, char *str, uint16_t buf_size)

Deserialize string

Parameters:

data – Buffer containing CBOR data with matching type
str – Pointer to the buffer where the string should be stored
buf_size – Size of the string buffer including null-termination

Returns:

Number of bytes read from data buffer or 0 in case of error

int cbor_deserialize_string_zero_copy(const uint8_t *data, char **str_start, uint16_t *str_len)

Deserialize string with zero-copy

Parameters:

data – Buffer containing CBOR data with matching type
str_start – Pointer to store start of string
str_len – Pointer to store length of string in the buffer EXCLUDING null-termination

Returns:

Number of bytes read from data buffer or 0 in case of error

int cbor_deserialize_bytes(const uint8_t *data, uint8_t *bytes, uint16_t buf_size, uint16_t *num_bytes)

Deserialize bytes

Parameters:

data – Buffer containing CBOR data with matching type
bytes – Pointer to the buffer where the data should be stored
buf_size – Size of the buffer
num_bytes – Pointer to a variable to store the actual number of bytes written to buffer

Returns:

Number of bytes read from data buffer or 0 in case of error

int cbor_num_elements(const uint8_t *data, uint16_t *num_elements)

Determine the number of elements in a map or an array

Parameters:

data – Buffer containing CBOR data with matching type
num_elements – Pointer to the variable where the result should be stored

Returns:

Number of bytes read from buffer or 0 in case of error

int cbor_size(const uint8_t *data)

Determine the size of the cbor data item

Parameters:

data – Pointer for starting point of data item

Returns:

Size in bytes