Config

Table of Contents

• Allocation
• Read and Parse Configuration
• Gateway ID
• Advertise Period
• Retry Configuration
• Default Client ID
• Keep Alive Period for Publish Only Clients
• Limit Messages for Sleeping Clients
• Predefined Topics
• Authentication Information
• Topic ID Allocation Range
• Broker Address and Port
• Custom Configuration Values

The Config object is responsible to provide a common way to parse the configuration file and provide a convenient interface to retrieve any configuration values, which can later be applied to the Gateway and/or Session objects. The format of the configuration file is described in the example config file provided with the project.

Allocation

When using C++ interface, just instantiate object of cc_mqttsn_gateway::Config class. The destruction of the object will clean up all acquired resources.

cc_mqttsn_gateway::Config config;

When using C interface, the allocation is performed using cc_mqttsn_gw_config_alloc()

CC_MqttsnConfigHandle handle = cc_mqttsn_gw_config_alloc();

and de-allocation is performed using cc_mqttsn_gw_config_free() functions.

cc_mqttsn_gw_config_free(handle);

Read and Parse Configuration

The gateway application may have multiple configuration options. These options and their parameters may be listed in a special configuration file. The expected format of the file is as following:

• The comment starts with '#' symbol and ends with new line chracter. The comments are ignored when parsing the file
• The configuration option contains with key and value pair. The first word (until the first white space character) in the configuration line is considered to be a key, all the rest (until the end of the line) is considered to be a value.

The Config object assigns various default values to all the configuration options when constructed. It may be requested to read and parse the configuration file. In this case, the Config object will update the configuration values, recorded in its internal state, with new values read from file. If some option does not appear to be listed in the file, the default value will be reported when inquired.

C++ interface allows usage any of standard input streams:

std::ifstream stream("/path/to/config/file");
config.read(stream);

C interface also allows either reading from file:

cc_mqttsn_gw_config_read(handle, "/path/to/config/file");

or parsing the string, if configuration file contents have been read from file into a buffer earlier:

char buf[4096] = {0};
... /* read data from buf into buf, put \0 at the end */
cc_mqttsn_gw_config_parse(handle, buf);

Gateway ID

Both Gateway (see Gateway ID) and Session (see Gateway ID) objects require knowledge of gateway numeric ID to be able to properly report it to the client(s).

C++ interface:

std::uint8_t id = config.gatewayId();

C interface:

unsigned char id = cc_mqttsn_gw_config_id(handle);

Advertise Period

The Gateway object sends ADVERTISE message periodically. It needs to be configured with propere period value (see Advertise Period). Use the following interface to retrieve this value from the Config object.

C++ interface:

std::uint16_t period = config.advertisePeriod();

C interface:

unsigned short period = cc_mqttsn_gw_config_advertise_period(handle);

Retry Configuration

The Session object can be configured with period between its retry attempts as well as number of such attempts (see Retry Attempts). Use the following interface of the Config object to retreive these values:

C++ interface:

unsigned period = config.retryPeriod();
unsigned attempts = config.retryCount();

C interface:

unsigned period = cc_mqttsn_gw_config_retry_period(handle);
unsigned attempts = cc_mqttsn_gw_config_retry_count(handle);

Default Client ID

Can be used in Session object configuration (see Default Client ID).

C++ interface:

const std::string& clientId = config.defaultClientId();

C interface:

const char* clientId = cc_mqttsn_gw_config_default_client_id(handle);

Keep Alive Period for Publish Only Clients

Can be used in Session object configuration (see Publish Only Client).

C++ interface:

std::uint16_t keepAlivePeriod = config.pubOnlyKeepAlive();

C interface:

unsigned short keepAlivePeriod = cc_mqttsn_gw_config_pub_only_keep_alive(handle);

Limit Messages for Sleeping Clients

Can be used in Session object configuration (see Sleeping Client).

C++ interface:

std::size_t limit = config.sleepingClientMsgLimit();

C interface:

unsigned limit = cc_mqttsn_gw_config_sleeping_client_msg_limit(handle);

Predefined Topics

The Session object can be configured with number of predefined topics (see Predefined Topics). Retrieve this information from the Config object using the following API.

C++ interface:

const cc_mqttsn_gateway::Config::PredefinedTopicsList& list = config.predefinedTopics();
... // iterate over the list and assign values to @b Session object(s).

C interface:

   CC_MqttsnPredefinedTopicInfo infos[100];
   unsigned count = cc_mqttsn_gw_config_get_predefined_topics(handle, infos, 100);
   unsigned idx;
   for (idx = 0; idx < count; idx++) {
       const CC_MqttsnPredefinedTopicInfo* elem = infos[idx];
       ... /* assign elem info to @b Session object(s).
*  }
*  

C interface also allows to retrieve number of predefined topics in case there is no known limit for the buffer upfront and it needs to be dynamically allocated:

unsigned count = cc_mqttsn_gw_config_available_predefined_topics(handle);

Authentication Information

The Session object can inquire authentication information when some client attempts connection (see Client Authentication). Retrieve this information from the Config object using the following API.

C++ interface:

const cc_mqttsn_gateway::Config::AuthInfosList& list = config.authInfos();

C interface:

CC_MqttsnAuthInfo infos[100];
unsigned count = cc_mqttsn_gw_config_get_auth_infos(handle, infos, 100);
... // use up to count infos.

C interface also allows to retrieve total number of authentication infos available. It can be useful in case there is no known limit for the buffer upfront and it needs to be dynamically allocated:

unsigned count = cc_mqttsn_gw_config_available_auth_infos(handle);

Topic ID Allocation Range

The Session object can be configured to limit its range of topic IDs, which are allocated for newly registered topic strings (see Allocating Topic IDs). Retrieve this information from the Config object using the following API.

C++ interface:

const cc_mqttsn_gateway::Config::TopicIdsRange range = config.topicIdAllocRange();
std::uint16_t minTopicId = range.first;
std::uint16_t maxTopicId = range.second;

C interface:

unsigned short minTopicId = 0;
unsigned short maxTopicId = 0;
cc_mqttsn_gw_config_topic_id_alloc_range(handle, &minTopicId, &maxTopicId);

Broker Address and Port

The MQTT-SN gateway application must connect and forward traffic to MQTT broker. Below are API functions that can be used to retrieve the TCP/IP address and port of the broker.

C++ interface

const std::string& addr = config.brokerTcpHostAddress();
std::uint16_t port = config.brokerTcpHostPort();

C interface

const char* addr = cc_mqttsn_gw_config_broker_address(handle);
unsigned short port = cc_mqttsn_gw_config_broker_port(handle);

Custom Configuration Values

The Config object has a list of predefined options it recognises in the configuration file. It also accumulates all the options it doesn't recognise. As a reminder: the first word (until the first white character) in the configuration line is considered to be a key, and the rest of the string (from the next non-white character until the end of the line) is considered to be a value. The Config option allows access to such values for the driving code to parse and use.

C++ interface

const cc_mqttsn_gateway::Config::ConfigMap map = config.configMap();
auto iters = map.equal_range("my_custom_config");
for (auto iter = iters.first; iter != iters.second; ++iter) {
    const std::string& value = iter->second;
    ... // Parse and use the value
}

NOTE, that cc_mqttsn_gateway::Config::ConfigMap type is a multimap, it allows multiple entries for the same key.

C interface:
First, retrieve the number of available entries for the provided configuration key:

unsigned count = cc_mqttsn_gw_config_values_count(handle, "my_custom_config");

Then, access the available configuration values:

unsigned idx;
for (idx = 0; idx < count; idx++) {
    const char* value = cc_mqttsn_gw_config_get_value(handle, "my_custom_config", idx);
    ... /* Parse and use the value */
}