An mbed wrapper around the helium-client to communicate with the Helium Atom

Embed: (wiki syntax)

« Back to documentation index

Config Class Reference

Config Class Reference

A Channel Configuration. More...

#include <Helium.h>

Public Member Functions

 Config (Channel *channel)
 Construct a Configuration.
int get (const char *key, int32_t *value, int32_t default_value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Get an integer configuration value.
int get (const char *key, float *value, float default_value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Get a float configuration value.
int get (const char *key, bool *value, bool default_value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Get a boolean configuration value.
int get (const char *key, char *value, size_t value_len, char *default_value, size_t default_value_len, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Get a string configuration value.
int get (const char *key, uint16_t *token)
 Send a request for a configuration value.
int poll_get_result (uint16_t token, const char *config_key, enum helium_config_type config_type, void *value, size_t value_len, void *default_value, size_t default_value_len, int8_t *result, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Poll the response of a configuration request.
int set (const char *key, float value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Set a float configuration value.
int set (const char *key, int32_t value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Set an integer configuration value.
int set (const char *key, bool value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Set a boolean configuration value.
int set (const char *key, const char *value, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Set a string configuration value.
int set_null (const char *key, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Set a null configuration value.
int set (const char *key, helium_config_type value_type, void *value, uint16_t *token)
 Send a request for setting a configuration value.
int poll_set_result (uint16_t token, int8_t *result, uint32_t retries=HELIUM_POLL_RETRIES_5S)
 Poll the response of a configuration set request.
bool is_stale ()
 Check whether configuration values are stale.

Detailed Description

A Channel Configuration.

Channels can have configuration data for the Helium Atom available. Depending on the IoT platform the configuration data is a representation of device configuration. Other terms used are device "twins" or "shadows".

To use a channel configuration construct it with a channel that supports configuration and use the get methods to retrieve configuration values from the IoT platform's device representation. Use the set methods to set values in the IoT platform's representation of the device.

Note that most IoT platforms represent sets and gets in different namespaces. The get methods represent the IoT platform's desired or expected namespace of the device, while the set methods are reflected in the actual, or current namespace of the device.

Definition at line 273 of file Helium.h.


Constructor & Destructor Documentation

Config ( Channel channel )

Construct a Configuration.

Parameters:
channelThe channel to get/set configuration with

Definition at line 186 of file Helium.cpp.


Member Function Documentation

int get ( const char *  key,
int32_t *  value,
int32_t  default_value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Get an integer configuration value.

Parameters:
keyThe configuration key to get
[out]valueThe target for the received value
default_valueThe default value in case of errors
retriesThe number of times to retry (optional)
Returns:
0 on success. If the result is > 0 the result code is one of the helium_status_ error codes. If the result is < 0 it is one of the config_poll_get_status error codes

Definition at line 292 of file Helium.h.

int get ( const char *  key,
float *  value,
float  default_value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Get a float configuration value.

Parameters:
keyThe configuration key to get
[out]valueThe target for the received value
default_valueThe default value in case of errors
retriesThe number of times to retry (optional)
Returns:
0 on success. If the result is > 0 the result code is one of the helium_status_ error codes. If the result is < 0 it is one of the config_poll_get_status error codes

Definition at line 316 of file Helium.h.

int get ( const char *  key,
char *  value,
size_t  value_len,
char *  default_value,
size_t  default_value_len,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Get a string configuration value.

Parameters:
keyThe configuration key to get
[out]valueThe target buffer for the received string
value_lenThe length of the available buffer space
default_valueThe default value to use if not found
default_value_lenThe length of the default_value buffer. Note: Ensure to include the trailing NULL in this length parameter
retriesThe number of times to retry (optional)
Returns:
0 on success. If the result is > 0 the result code is one of the helium_status_ error codes. If the result is < 0 it is one of the config_poll_get_status error codes

Definition at line 369 of file Helium.h.

int get ( const char *  key,
uint16_t *  token 
)

Send a request for a configuration value.

Getting a configuration value requires sending a request with the configuration key and then using the resulting token in a poll_get_result() call to wait for a response.

Parameters:
keyThe configuration key to get
[out]tokenThe token representing the response.
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 192 of file Helium.cpp.

int get ( const char *  key,
bool *  value,
bool  default_value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Get a boolean configuration value.

Parameters:
keyThe configuration key to get
[out]valueThe target for the received value
default_valueThe default value in case of errors
retriesThe number of times to retry (optional)
Returns:
0 on success. If the result is > 0 the result code is one of the helium_status_ error codes. If the result is < 0 it is one of the config_poll_get_status error codes

Definition at line 341 of file Helium.h.

bool is_stale (  )

Check whether configuration values are stale.

Checks whether there has been a system indication that configuration attributes may have gone stale.

When this returns true you should assume that any configuration values you have previously retrieved are no longer valid.

Returns:
true if previous configuration values are stale, false if not

Definition at line 386 of file Helium.cpp.

int poll_get_result ( uint16_t  token,
const char *  config_key,
enum helium_config_type  config_type,
void *  value,
size_t  value_len,
void *  default_value,
size_t  default_value_len,
int8_t *  result,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Poll the response of a configuration request.

Polls the given token and validates any response against the given configuration key and expected type. If these match the value is copied into the given value buffer.

Note: The short form methods for getting config values hide most of the complexity required to make a configuration get work.

Parameters:
tokenThe token returned from a previous get() request
config_keyThe configuration key to check for
config_typeThe configuration type to check for
[out]valueThe destination buffer to copy the result into
value_lenThe size of the given destination buffer
default_valueThe default value to use if not found
default_value_lenThe length of the default_value buffer.
retriesThe number of times to retry (optional)
[out]resultThe channel response code. 0 for no errors, non-0 otherwise
Returns:
0 on success. If the result is > 0 the result code is one of the helium_status_ error codes. If the result is < 0 it is one of the config_poll_get_status error codes

Definition at line 309 of file Helium.cpp.

int poll_set_result ( uint16_t  token,
int8_t *  result,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Poll the response of a configuration set request.

Polls the given token and returns the result code of the set request.

Note: The short form methods for getting config values hide most of the complexity required to make a configuration get work.

Parameters:
tokenThe token returned from a previous set() request
[out]resultA pointer to storage for the response code
retriesThe number of times to retry (optional)
Returns:
A helium_status result code for the actual communication part. If the result is helium_status_OK, the result code can be used to check if the set was successful. The result code will be 0 on success, and non-zero otherwise.

Definition at line 357 of file Helium.cpp.

int set ( const char *  key,
int32_t  value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Set an integer configuration value.

Parameters:
keyThe configuration key to set
valueThe value to set
retriesThe number of times to retry (optional)
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 453 of file Helium.h.

int set ( const char *  key,
const char *  value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Set a string configuration value.

Parameters:
keyThe configuration key to set
valueThe value to set
retriesThe number of times to retry (optional)
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 481 of file Helium.h.

int set ( const char *  key,
helium_config_type  value_type,
void *  value,
uint16_t *  token 
)

Send a request for setting a configuration value.

Setting a configuration value requires sending a request with the configuration key, the value type and the value and then using the resulting token in a poll_set_result() call to wait for a response.

Parameters:
keyThe configuration key to set
value_typeThe type of the configuration value to set
valueA pointer to the value that needs to be st
[out]tokenThe token representing the response.
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 343 of file Helium.cpp.

int set ( const char *  key,
float  value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Set a float configuration value.

Parameters:
keyThe configuration key to set
valueThe value to set
retriesThe number of times to retry (optional)
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 440 of file Helium.h.

int set ( const char *  key,
bool  value,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Set a boolean configuration value.

Parameters:
keyThe configuration key to set
valueThe value to set
retriesThe number of times to retry (optional)
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 468 of file Helium.h.

int set_null ( const char *  key,
uint32_t  retries = HELIUM_POLL_RETRIES_5S 
)

Set a null configuration value.

Parameters:
keyThe configuration key to set
retriesThe number of times to retry (optional)
Returns:
0 on success. One of the helium_status_ error codes otherwise.

Definition at line 495 of file Helium.h.