Session

Table of Contents

• Allocation
• Receiving Data
  • Receiving Data from Client
  • Receiving Data from Broker
• Sending Data
  • Sending Data to Client
  • Sending Data to Broker
• Time Measurement
• Session Termination
• Re-Connection to Broker
• Gateway ID
• Retry Attempts
• Predefined Topics
• Allocating Topic IDs
• Start Operation
• Connection to Broker
• Client Authentication
• Connected Client Report
• Default Client ID
• Publish Only Client
• Sleeping Client
• Forwarder Encapsulation Support
• Errors Report

The Session object is responsible to manage and forward traffic of messages between single MQTT-SN client and the broker. When new message is received over the I/O link, the driving code must check whether any Session object has already been created for the client that sent the message (the clients can be differentiated by their origin address). If such Session does NOT exist, it must be created.

The received data needs to be forwarded to appropriate Session object for processing. And when the Session object requests to send message back, it needs to be sent to the right address. It is a responsibility of the driving code to maintain a valid map between the client's address and appropriate Session object.

Allocation

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

std::unique_ptr<cc_mqttsn_gateway::Session> session(new cc_mqttsn_gateway::Session());
 
// Using raw pointer to force doxygen to propely generate links to the 
// member functions in the code snippets below.
cc_mqttsn_gateway::Session* session = new cc_mqttsn_gateway::Session();

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

CC_MqttsnSessionHandle handle = cc_mqttsn_gw_session_alloc();

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

cc_mqttsn_gw_session_free(handle);

Receiving Data

The MQTT-SN gateway Session serves as message translator and forwarder between MQTT-SN client and MQTT broker. The driver code is responsible to manage these two independent communication links. Once a message is received on any of them, it must be provided the the Session object for processing.

Receiving Data from Client

C++ interface:

std::size_t consumed = session->dataFromClient(buf, bufLen);

C interface:

unsigned consumed = cc_mqttsn_gw_session_data_from_client(handle, buf, bufLen);

NOTE, that functions return number of bytes that were actually processed. If number of processed bytes is less that number of bytes residing in the buffer, then probably some unexpected protocol error has occurred.

The call to this function may cause invocation of various callback functions that have been set.

Receiving Data from Broker

C++ interface:

std::size_t consumed = session->dataFromBroker(buf, bufLen);

C interface:

unsigned consumed = cc_mqttsn_gw_session_data_from_broker(handle, buf, bufLen);

NOTE, that functions return number of bytes that were actually processed. If number of processed bytes is less that number of bytes residing in the buffer, then probably some unexpected protocol error has occurred.

The call to this function may cause invocation of various callback functions that have been set.

Sending Data

The Session object may require to send a message to either client or broker. The driving code has to provide appropriate callbacks for this purpose. When the callback is invoked, it is provided with pointer to data buffer. This buffer resides in internal data structures of the Session object. After the callback returns, this buffer may be updated. It means, that the driving code may require to copy the buffer to its internal data structures to preserve the data intact until send over I/O link operation is complete.

Sending Data to Client

C++ interface:

session->setSendDataClientReqCb(
    [](const std::uint8_t* buf, std::size_t bufLen)
    {
        ... 
    });

C interface:

void my_send_to_client(void* userData, CC_MqttsnSessionHandle session, const unsigned char* buf, unsigned bufLen)
{
    ...
}
 
cc_mqttsn_gw_session_set_send_data_to_client_cb(handle, &my_send_to_client, someUserData);

Sending Data to Broker

C++ interface:

session->setSendDataBrokerReqCb(
    [](const std::uint8_t* buf, std::size_t bufLen)
    {
        ... 
    });

C interface:

void my_send_to_broker(void* userData, CC_MqttsnSessionHandle session, const unsigned char* buf, unsigned bufLen)
{
    ...
}
 
cc_mqttsn_gw_session_set_send_data_to_broker_cb(handle, &my_send_to_broker, someUserData);

Time Measurement

The Session object may require to measure time to identify message delivery timeouts. It relies on the driving code to provide such service. There is a need to set appropriate callback:

C++ interface:

session.setNextTickProgramReqCb(
    [](unsigned duration)
    {
        ... // Set timer to expire after duration milliseconds
            // After expiry call session.tick()
    });

C interface:

void my_tick_req(void* userData, CC_MqttsnSessionHandle session, unsigned duration)
{
    ... /* Set timer to expire after duration milliseconds */
    ... /* After expiry call cc_mqttsn_gw_session_tick() */
}
 
cc_mqttsn_gw_session_set_tick_req_cb(handle, &my_tick_req, someUserData);

After the requested time expires, the driving code needs to notify the Session object. It must call the appropriate tick() function.

C++ interface:

session->tick();

C interface:

cc_mqttsn_gw_session_tick(handle); 

Based on some events, the Session object may require knowledge of elapsed time since last tick programming request. For this purpose the driving code must set a callback to cancel the existing time measurement and return number of elapsed milliseconds.

C++ interface:

session->setCancelTickWaitReqCb(
    []() -> unsigned
    {
        ... // cancel timer
        return ...; // return number of elapsed milliseconds
    });

C interface:

unsigned my_cancel_timer_req(void* userData, CC_MqttsnSessionHandle session)
{
    ... /* cancel timer */
    return ...; /* return number of elapsed milliseconds */
}
 
cc_mqttsn_gw_session_set_cancel_tick_cb(handle, &my_cancel_timer_req, someUserData);

Session Termination

The Session object may recognise disconnection of MQTT-SN client and/or MQTT broker. As the result the session object must be destructed immediately and new one is created once the client renews its connection. The request to terminate the session is performed via callback, which must be set by the driving code.

C++ interface:

session->setTerminationReqCb(
    []()
    {
        ... // Destruct session object.
    });

C interface:

void my_session_term(void* userData, CC_MqttsnSessionHandle session)
{
    ... /* Remove reference to session object from internal data structures */
    cc_mqttsn_gw_session_free(handle);
}
 
cc_mqttsn_gw_session_set_term_req_cb(handle, &my_session_term, someUserData);

Re-Connection to Broker

The MQTT-SN protocol specification defines messages and operations, that are not properly supported by the MQTT protocol, such as will information update. The Session object supports these kind of operations by sending updated CONNECT request to the broker on behalf of the client. However, MQTT protocol disallows multiple CONNECT messages in the single connection session. As the result the gateway must perform the following steps:

1. send DISCONNECT message
2. close existing TCP/IP connection
3. open new TCP/IP connection
4. send new CONNECT message with updated connection information.

Due to the reason, that TCP/IP connection to the broker is managed by the driving code, it must implement steps 2 and 3 in the list above.

The Session object issues the reconnection request via callback, which must be provided by the driving code.

C++ interface

session->setBrokerReconnectReqCb(
    []()
    {
        ... // Close existing TCP/IP connection to broker and open a new one
    });

C interface

void my_broker_reconnect(void* userData, CC_MqttsnSessionHandle session)
{
    ... /* Close existing TCP/IP connection to broker and open a new one */
}
 
cc_mqttsn_gw_session_set_broker_reconnect_req_cb(handle, &my_broker_reconnect, someUserData);

NOTE, that the updated connection statuses of the broker (first disconnected and then connected) must be reported to the Session object when they happen. Details are in Connection to Broker section below.

Gateway ID

The MQTT-SN client may broadcast SEARCHGW message in an attempt to discover existing gateways on the network. The Session object is responsible to send GWINFO message as a response. Such message contains numeric gateway ID. Hence, the Session object must also be aware of the gateway ID information:

C++ interface:

session->setGatewayId(5);

C interface:

cc_mqttsn_gw_session_set_id(handle, 5);

It is also possible to retrieve the current configuration:

C++ interface:

std::uint8_t id = session->getGatewayId();

C interface:

unsigned char id = cc_mqttsn_gw_session_get_id(gw);

Retry Attempts

There are cases when the communication to either client or broker is driven by the Session object itself. Such communication may involve messages that require acknowledgement by the other side. If acknowledgement is not received in time, the message must be re-sent. The Session object may be configured with duration (in seconds) between resend attempts and total number of attempts to perform.

C++ interface:

session->setRetryPeriod(5U); // 5 seconds between resend attempts
session->setRetryCount(4U); // up to 4 attempts to resend the same message

C interface:

cc_mqttsn_gw_session_set_retry_period(handle, 5U); /* 5 seconds between resend attempts */
cc_mqttsn_gw_session_set_retry_count(handle, 4U); /* up to 4 attempts to resend the same message */

If not configured, the default values of 10 seconds and 3 attempts apply.

It is also possible to retrieve the current configuration:

C++ interface:

unsigned retryPeriod = session->getRetryPeriod();
unsigned retryCount = session->getRetryCount();

C interface:

unsigned retryPeriod = cc_mqttsn_gw_session_get_retry_period(gw);
unsigned retryCount = cc_mqttsn_gw_session_get_retry_count(gw);

Predefined Topics

The messages in MQTT-SN protocol are published with numeric topic IDs instead of strings (like in original MQTT). The protocol also allows bypassing the topic strings registration and using predefined IDs directly. In this case the Session object must be configured with all known and applicable topic string and topic numeric ID pairs. It will use this information to convert between numeric topic ID topic topic string when forwarding PUBLISH messages to both directions.

C++ interface:

if (!session->addPredefinedTopic("some/predefined/topic", 123)) {
    ... // report error
}
 
if (!session->addPredefinedTopic("other/predefined/topic", 1111)) {
    ... // report error
}

C interface:

if (!cc_mqttsn_gw_session_add_predefined_topic(handle, "some/predefined/topic", 123)) {
    ... /* report error */
}
 
if (!cc_mqttsn_gw_session_add_predefined_topic(handle, "other/predefined/topic", 1111)) {
    ... /* report error */
}

Allocating Topic IDs

When not using predefined topic IDs, there is a process of topic string registration and allocating relevant numeric topic ID. This allocation is performed by the Session object. By default the Session object will pick the first number available. However, it may be wise to reserve some range of topic IDs to be predefined ones, especially when there are some client specific predefined topic IDs, which added later when connected client ID is known (see Connected Client Report). The library provides a way to limit range of topic IDs allocated during the registration process.

C++ interface:

if (!session->setTopicIdAllocationRange(0x1000, 0xffff)) {
    ... // report error
}

C interface:

if (!cc_mqttsn_gw_session_set_topic_id_alloc_range(handle, 0x1000, 0xffff)) {
    ... // report error
}

Start Operation

After been properly configured the Session object needs to be started.

C++ interface:

if (!session->start()) {
    ... // The session hasn't been properly configured, report error
}

C interface:

if (!cc_mqttsn_gw_session_start(handle)) {
    ... /* The session hasn't been properly configured, report error */
}

If not properly started, the Session object will ignore any input from client and broker.

The operation of the Session object can also be stopped / paused for a while.

C++ interface:

session->stop();

C interface:

cc_mqttsn_gw_session_stop(handle);

The operation of the stopped Session object may be restarted using the same cc_mqttsn_gateway::Session::start() and cc_mqttsn_gw_session_start() functions.

Connection to Broker

AFTER (important emphasis here) successfully starting operation of the Session object (see Start Operation) the driving code must initiate TCP/IP connection to the MQTT broker. The driving code must also constantly monitor the state of this connection and to the Session object any detected change. When started, the Session object assumes broker is disconnected.

C++ interface:

session->setBrokerConnected(true); // Reports broker being connected

C interface:

cc_mqttsn_gw_session_set_broker_connected(handle, true); // Reports broker being connected

When issuing broker re-connection request (see Re-Connection to Broker), the Session object expects this call to happen twice: the first one for disconnection report and second one for new connection report.

The driving code also responsible to detect unsolicited disconnects of TCP/IP link to the broker and report it to the Session object using the same function call.

It is also possible to retrieve the current status:

C++ interface:

bool brokerConnected = session->getBrokerConnected();

C interface:

bool brokerConnected = cc_mqttsn_gw_session_get_broker_connected(handle);

Client Authentication

The MQTT protocol supports client authentication, where the CONNECT message may contain username and password. The MQTT-SN protocol, on the other hand, lacks this feature. The Session object provides an ability to set a callback function, which will be invoked when MQTT-SN client's connection request is recognised. This callback may provide authentication information for this client, which is going to be filled in the forwarded CONNECT request.

C++ interface:

session->setAuthInfoReqCb(
    [](const std::string& clientId) -> cc_mqttsn_gateway::Session::AuthInfo
    {
        return std::make_pair(getUsernameFor(clientId), getPasswordFor(clientId));
        
    }); 

C interface:

void my_auth_callback(
    void* userData, 
    CC_MqttsnSessionHandle handle,
    const char* clientId, 
    const char** username, 
    const unsigned char** password, 
    unsigned* passwordLen)
{
    *username = ...; /* assign pointer to username for provided client ID */
    *password = ...; /* assign pointer to password for provided client ID */
    *passwordLen = ...; /* specify length of the password */
}
 
cc_mqttsn_gw_session_set_auth_info_req_cb(handle, &my_auth_callback, someUserData);

Connected Client Report

The Session object provides an ability to get notified when a MQTT-SN client is successfully connected. The notification is performed using a callback. Inside this callback, the driving code may provide some client specific configurations, such as new predefined topic IDs relevant only to the connected client.

C++ interface:

session->setClientConnectedReportCb(
    [session](const std::string& clientId)
    {
        if (!session->addPredefinedTopic("client/specific/predefined/topic", 2222)) {
            ... /* report error */
        }
    }); 

C interface:

void my_client_connect_report(void* userData, CC_MqttsnSessionHandle handle, const char* clientId)
{
    if (!cc_mqttsn_gw_session_add_predefined_topic(handle, "client/specific/predefined/topic", 2222)) {
        ... /* report error */
    }
}
 
cc_mqttsn_gw_session_set_client_connect_report_cb(handle, &my_client_connect_report, someUserData);

Default Client ID

The Session object interface allows to specify the default ID of the client, which is going to be used to connect to broker, if the client doesn't provide non-empty ID string in its connection attempt. This may be useful when client is connected over one-to-one I/O link such as RS-232. In order to simplify the client implementation and reduce amount of data transferred on the link, the Session object may be configured to substitute the empty client ID with other, non-empty one, when forwarding the connection request to the broker.

The default client ID configuration may also be used with "publish only" clients (see Publish Only Client below). The configured client ID will be used when connecting to the broker on behalf of the "publish only" client.

C++ interface:

session->setDefaultClientId("some_default_id");

C interface:

cc_mqttsn_gw_session_set_default_client_id(handle, "some_default_id");

NOTE, that the Session object will make an attempt to substitute reported client ID if and only if the client ID is empty and configured default client ID is NOT.

It is also possible to retrieve the current configuration:

C++ interface:

const std::string& defaultClientId = session->getDefaultClientId();

C interface:

const char* defaultClientId = cc_mqttsn_gw_session_get_default_client_id(handle);

Publish Only Client

The MQTT-SN protocol allows "publish only" clients, which don't make an attempt to connect to the gateway/broker, but allowed to publish messages with predefined topic IDs and QoS=-1. The gateway must connect to the broker on behalf of such client. The connection operation involves knowledge about client ID and "keep alive" period. The client ID, that is going to be used, is configured as Default Client ID. The "keep alive" period can be provided using separate function:

C++ interface:

session->setPubOnlyKeepAlive(100); // 100 seconds

C interface:

cc_mqttsn_gw_session_set_pub_only_keep_alive(handle, 100); /* 100 seconds */

If such configuration is not provided, the default value of 60 seconds is assumed.

It is also possible to retrieve the current configuration:

C++ interface:

std::uint16_t pubOnlyKeepAlive = session->getPubOnlyKeepAlive();

C interface:

unsigned pubOnlyKeepAlive = cc_mqttsn_gw_session_get_pub_only_keep_alive(handle);

Sleeping Client

The Session object supports client entering the SLEEP mode without any extra configuration. It will send the PINGREQ messages on behalf of the client to keep the connection to the broker alive, and will accumulate all the messages sent to the client until it wakes up.

However, it may be a good idea to limit the number of messages, the Session object is allowed to accumulate, to avoid consumption of too much memory.

C++ interface:

session->setSleepingClientMsgLimit(1000); // no more that 1000 messages

C++ interface:

cc_mqttsn_gw_session_set_sleeping_client_msg_limit(handle, 1000); /* no more that 1000 messages */

It is also possible to retrieve the current configuration:

C++ interface:

std::size_t limit = session->getSleepingClientMsgLimit();

C interface:

unsigned long long limit = cc_mqttsn_gw_session_get_sleeping_client_msg_limit(handle);

Forwarder Encapsulation Support

In case the gateway need to support forwarder encapsulation functionality there is a need to set extra two callbacks.

C++ interface:

session->setFwdEncSessionCreatedReportCb(
    [](cc_mqttsn_gateway::Session* fwdSession) -> bool
    {
        ... // Perform the session configuration and set all the necessary callbacks
        return true;
    });
 
session->setFwdEncSessionDeletedReportCb(
    [](cc_mqttsn_gateway::Session* fwdSession) -> bool
    {
        ... // Remove any reference to fwdSession in the data structures
    });

C interface:

bool my_fwd_enc_session_created_report_cb(void* userData, CC_MqttsnSessionHandle handle)
{
    ... // Perform the session configuration and set all the necessary callbacks
    return true;
}
 
void my_fwd_enc_session_deleted_report_cb(void* userData, CC_MqttsnSessionHandle handle)
{
    ... // Remove any reference to handle in the data structures
}
 
cc_mqttsn_gw_session_set_fwd_enc_session_created_cb(handle, &my_fwd_enc_session_created_report_cb, someDserData);
cc_mqttsn_gw_session_set_fwd_enc_session_deleted_cb(handle, &my_fwd_enc_session_deleted_report_cb, someDserData);

When the new forward encapsulation session creation is reported, the application is responsible to perform the necessary session configuration as well as set all the necessary callbacks, except the Sending Data to Client and the Session Termination. These callbacks will be set by the reporting session.

The reported forward encapsulation session object is owned by the reporting session and its deletion will be reported using the deletion report callback.

The gateway application is responsible to manage the connection to the broker as well as timers of the reported forward encapsulation session.

When the forward encapsulation session is reported, it's not started yet. It will be when the callback function returns. However, the gateway application is expected to initiate asynchronous connection to the broker and report the connectivity later on. The important part is that broker connectivity must be reported after the callback function returns.

Errors Report

The gateway library can detect and report some unexpected behavior from the application, client, and/or broker. The Session object reports such errors via callback:

C++ interface

session->setErrorReportCb(
    [](const char* msg)
    {
        std::cerr << "ERROR: " << msg << std::endl;
    });

C interface

void my_error_report(void* userData, CC_MqttsnSessionHandle session, const char* msg)
{
    printf("ERROR: %s\n", msg);
}
 
cc_mqttsn_gw_session_set_error_report_cb(handle, &my_error_report, someUserData);