Detailed Description

Interface for Session entity.

The responsibility of the Session object is to manage and forward traffic of messages between single MQTT-SN client and broker.

Public Types
using	BinaryData = std::vector< std::uint8_t >
	Type for buffer of binary data.

using	AuthInfo = std::pair< std::string, BinaryData >
	Type of authentication information.

using	NextTickProgramReqCb = std::function< void(unsigned value)>
	Type of callback, used to request new time measurement.

using	CancelTickWaitReqCb = std::function< unsigned()>
	Type of callback, used to cancel existing time measurement.

using	ClientSendDataReqCb = std::function< void(const std::uint8_t *buf, std::size_t bufSize, unsigned broadcastRadius)>
	Type of callback, used to request delivery of serialised message to the client.

using	BrokerSendDataReqCb = std::function< void(const std::uint8_t *buf, std::size_t bufSize)>
	Type of callback, used to request delivery of serialised message to the broker.

using	TerminationReqCb = std::function< void()>
	Type of callback, used to request session termination.

using	BrokerReconnectReqCb = std::function< void()>
	Type of callback used to request reconnection to the broker.

using	ClientConnectedReportCb = std::function< void(const std::string &clientId)>
	Type of callback used to report client ID of the newly connected MQTT-SN client.

using	AuthInfoReqCb = std::function< AuthInfo(const std::string &clientId)>
	Type of callback used to request authentication information of the client that is trying connect.

using	ErrorReportCb = std::function< void(const char *msg)>
	Type of the callback used to report detected errors.

using	FwdEncSessionCreatedReportCb = std::function< bool(Session *session)>
	Type of callback used to notify the application about forwarding encapsulation session being created.

using	FwdEncSessionDeletedReportCb = std::function< void(Session *session)>
	Type of callback used to notify the application about forwarding encapsulation session being deleted.

Public Member Functions
	Session ()
	Default constructor.

	~Session ()
	Destructor.

void	setNextTickProgramReqCb (NextTickProgramReqCb &&func)
	Set the callback to be invoked when new time measurement is required.

void	setCancelTickWaitReqCb (CancelTickWaitReqCb &&func)
	Set the callback to be invoked when previously requested time measurement needs to be cancelled.

void	setSendDataClientReqCb (ClientSendDataReqCb &&func)
	Set the callback to be invoked when new data needs to be sent to the client.

void	setSendDataBrokerReqCb (BrokerSendDataReqCb &&func)
	Set the callback to be invoked when new data needs to be sent to the broker.

void	setTerminationReqCb (TerminationReqCb &&func)
	Set the callback to be invoked when the session needs to be terminated and this Session object deleted.

void	setBrokerReconnectReqCb (BrokerReconnectReqCb &&func)
	Set the callback to be invoked when the session needs to close existing TCP/IP connection to the broker and open a new one.

void	setClientConnectedReportCb (ClientConnectedReportCb &&func)
	Set the callback to be invoked when MQTT-SN client is successfully connected to the broker.

void	setAuthInfoReqCb (AuthInfoReqCb &&func)
	Set the callback to be used to request authentication information for specific client.

void	setErrorReportCb (ErrorReportCb &&func)
	Set the callback to be used to report detected errors.

void	setFwdEncSessionCreatedReportCb (FwdEncSessionCreatedReportCb &&func)
	Set the callback to be invoked when the forwarding encapsulation session is detected and to notify application about such session creation.

void	setFwdEncSessionDeletedReportCb (FwdEncSessionDeletedReportCb &&func)
	Set the callback to be invoked when the forwarding encapsulation session is about to be deleted.

void	setGatewayId (std::uint8_t value)
	Set gateway numeric ID to be reported when requested.

std::uint8_t	getGatewayId () const
	Get configured gateway numeric ID to be reported when requested.

void	setRetryPeriod (unsigned value)
	Set retry period to wait between resending unacknowledged message to the client and/or broker.

unsigned	getRetryPeriod () const
	Get the current configuration of the retry period.

void	setRetryCount (unsigned value)
	Set number of retry attempts to perform before abandoning attempt to send unacknowledged message.

unsigned	getRetryCount () const
	Get the current configuration of the retry count.

void	setSleepingClientMsgLimit (std::size_t value)
	Provide limit to number pending messages being accumulated for the sleeping client.

std::size_t	getSleepingClientMsgLimit () const
	Get currenly configured limit to pending messages being accumulated for the sleeping client.

void	setDefaultClientId (const std::string &value)
	Provide default client ID for clients that report empty one in their attempt to connect.

const std::string &	getDefaultClientId () const
	Get current default client id configuration.

void	setPubOnlyKeepAlive (std::uint16_t value)
	Provide default "keep alive" period for "publish only" clients, that do not make an attempt to connect to the gateway.

std::uint16_t	getPubOnlyKeepAlive () const
	Get current configuration of the default "keep alive" period for "publish only" clients.

bool	start ()
	Start this object's operation.

void	stop ()
	Stop the operation of the object.

bool	isRunning () const
	Check whether the object's operation has been successfull started.

void	tick ()
	Notify the Session object about requested time period expiry.

std::size_t	dataFromClient (const std::uint8_t *buf, std::size_t len)
	Provide data received from the client for processing.

std::size_t	dataFromBroker (const std::uint8_t *buf, std::size_t len)
	Provide data received from the broker for processing.

void	setBrokerConnected (bool connected)
	Notify the Session object about broker being connected / disconnected.

bool	getBrokerConnected () const
	Get currently recorded broker connection status.

bool	addPredefinedTopic (const std::string &topic, std::uint16_t topicId)
	Add predefined topic string and ID information.

bool	setTopicIdAllocationRange (std::uint16_t minVal, std::uint16_t maxVal)
	Limit range of topic IDs allocated for newly registered topics.

Member Typedef Documentation

◆ AuthInfo

using cc_mqttsn_gateway::Session::AuthInfo = std::pair<std::string, BinaryData>

Type of authentication information.

The first element of the pair is username, and the second element of the pair is binary password.

◆ AuthInfoReqCb

using cc_mqttsn_gateway::Session::AuthInfoReqCb = std::function<AuthInfo (const std::string& clientId)>

Type of callback used to request authentication information of the client that is trying connect.

Parameters

[in] clientId Client ID

Returns: Authentication information

◆ BrokerReconnectReqCb

using cc_mqttsn_gateway::Session::BrokerReconnectReqCb = std::function<void ()>

Type of callback used to request reconnection to the broker.

When the callback is invoked, the driving code must close existing TCP/IP connection to the broker and create a new one.

◆ BrokerSendDataReqCb

using cc_mqttsn_gateway::Session::BrokerSendDataReqCb = std::function<void (const std::uint8_t* buf, std::size_t bufSize)>

Type of callback, used to request delivery of serialised message to the broker.

Parameters

[in]	buf	Buffer containing serialised message.
[in]	bufSize	Number of bytes in the buffer

◆ CancelTickWaitReqCb

using cc_mqttsn_gateway::Session::CancelTickWaitReqCb = std::function<unsigned ()>

Type of callback, used to cancel existing time measurement.

When invoked the existing time measurement needs to be cancelled. The function also needs to return amount of milliseconds elapsed since last timer programming request.

Returns: Number of elapsed milliseconds since last timer programming request.

◆ ClientConnectedReportCb

using cc_mqttsn_gateway::Session::ClientConnectedReportCb = std::function<void (const std::string& clientId)>

Type of callback used to report client ID of the newly connected MQTT-SN client.

The callback can be used to provide additional client specific information, such as predefined topic IDs.

Parameters

[in] clientId Client ID

◆ ClientSendDataReqCb

using cc_mqttsn_gateway::Session::ClientSendDataReqCb = std::function<void (const std::uint8_t* buf, std::size_t bufSize, unsigned broadcastRadius)>

Type of callback, used to request delivery of serialised message to the client.

Parameters

[in]	buf	Buffer containing serialised message.
[in]	bufSize	Number of bytes in the buffer
[in]	broadcastRadius	Broadcast radius. 0 means unitcast

◆ ErrorReportCb

using cc_mqttsn_gateway::Session::ErrorReportCb = std::function<void (const char* msg)>

Type of the callback used to report detected errors.

Parameters

[in] msg Error message

◆ FwdEncSessionCreatedReportCb

using cc_mqttsn_gateway::Session::FwdEncSessionCreatedReportCb = std::function<bool (Session* session)>

Type of callback used to notify the application about forwarding encapsulation session being created.

The application is responsible to perform the necessary session configuration as well as set all the callbacks except the one set by the setSendDataClientReqCb() and setTerminationReqCb(). The data sent to the client as well as the session termination are managed by the calling session object. The application is responsible to manage the timer as well as broker connection of the reported session.

Parameters

[in] session Pointer to the created session object. Owned by the session object invoking the callback, mustn't be deleted by the application.

Returns: true in case of success, false in case of falure.

◆ FwdEncSessionDeletedReportCb

using cc_mqttsn_gateway::Session::FwdEncSessionDeletedReportCb = std::function<void (Session* session)>

Type of callback used to notify the application about forwarding encapsulation session being deleted.

The application is responsible to remove any reference to the session object from its internal data structes.

Parameters

[in] session Pointer to the created session object. Owned by the session object invoking the callback, mustn't be deleted by the application.

◆ NextTickProgramReqCb

using cc_mqttsn_gateway::Session::NextTickProgramReqCb = std::function<void (unsigned value)>

Type of callback, used to request new time measurement.

When the requested time is due, the driving code is expected to call tick() member function.

Parameters

[in] value Number of milliseconds to measure.

◆ TerminationReqCb

using cc_mqttsn_gateway::Session::TerminationReqCb = std::function<void ()>

Type of callback, used to request session termination.

When the callback is invoked, the driving code must flush all the previously sent messages to appropriate I/O links and delete this session object.

Member Function Documentation

◆ addPredefinedTopic()

bool cc_mqttsn_gateway::Session::addPredefinedTopic	(	const std::string &	topic,
		std::uint16_t	topicId
	)

Add predefined topic string and ID information.

Parameters

[in]	topic	Topic string
[in]	topicId	Numeric topic ID.

Returns: success/failure status

◆ dataFromBroker()

std::size_t cc_mqttsn_gateway::Session::dataFromBroker	(	const std::uint8_t *	buf,
		std::size_t	len
	)

Provide data received from the broker for processing.

This call may cause invocation of some callbacks, such as request to cancel the currently running time measurement, send new message(s) and/or (re)start time measurement.

Parameters

[in]	buf	Pointer to the buffer of data to process.
[in]	len	Number of bytes in the data buffer.

Returns: Number of processed bytes.

Note: The function returns number of bytes that were actually consumed, and can be removed from the holding buffer.

◆ dataFromClient()

std::size_t cc_mqttsn_gateway::Session::dataFromClient	(	const std::uint8_t *	buf,
		std::size_t	len
	)

Provide data received from the client for processing.

This call may cause invocation of some callbacks, such as request to cancel the currently running time measurement, send new message(s) and/or (re)start time measurement.

Parameters

[in]	buf	Pointer to the buffer of data to process.
[in]	len	Number of bytes in the data buffer.

Returns: Number of processed bytes.

Note: The function returns number of bytes that were actually consumed, and can be removed from the holding buffer.

◆ isRunning()

bool cc_mqttsn_gateway::Session::isRunning ( ) const

Check whether the object's operation has been successfull started.

Returns: true/false

◆ setAuthInfoReqCb()

void cc_mqttsn_gateway::Session::setAuthInfoReqCb ( AuthInfoReqCb && func )

Set the callback to be used to request authentication information for specific client.

This is an optional callback. It can be used when there is a need to provide authentication details (username/password) for specific clients.

Parameters

[in] func R-value reference to the callback object

◆ setBrokerConnected()

void cc_mqttsn_gateway::Session::setBrokerConnected ( bool connected )

Notify the Session object about broker being connected / disconnected.

The report of broker being connected or disconnected must be performed only when the session's operation has been successfully started (see start()). Otherwise the call to this function gets ignored.

Parameters

[in] connected Connection status - true means connected, false disconnected.

◆ setBrokerReconnectReqCb()

void cc_mqttsn_gateway::Session::setBrokerReconnectReqCb ( BrokerReconnectReqCb && func )

Set the callback to be invoked when the session needs to close existing TCP/IP connection to the broker and open a new one.

This is a must have callback, without it the object can not be started (see start()).

Parameters

[in] func R-value reference to the callback object

◆ setCancelTickWaitReqCb()

void cc_mqttsn_gateway::Session::setCancelTickWaitReqCb ( CancelTickWaitReqCb && func )

Set the callback to be invoked when previously requested time measurement needs to be cancelled.

This is a must have callback, without it the object can not be started (see start()).

Parameters

[in] func R-value reference to the callback object

◆ setClientConnectedReportCb()

void cc_mqttsn_gateway::Session::setClientConnectedReportCb ( ClientConnectedReportCb && func )

Set the callback to be invoked when MQTT-SN client is successfully connected to the broker.

This is an optional callback. It can be used when there is a need to provide client specific configuration, such as predefined topic IDs, valid only for specific client.

Parameters

[in] func R-value reference to the callback object

◆ setDefaultClientId()

void cc_mqttsn_gateway::Session::setDefaultClientId ( const std::string & value )

Provide default client ID for clients that report empty one in their attempt to connect.

Parameters

[in] value Default client ID string.

◆ setErrorReportCb()

void cc_mqttsn_gateway::Session::setErrorReportCb ( ErrorReportCb && func )

Set the callback to be used to report detected errors.

Parameters

[in] func R-value reference to the callback object

◆ setFwdEncSessionCreatedReportCb()

void cc_mqttsn_gateway::Session::setFwdEncSessionCreatedReportCb ( FwdEncSessionCreatedReportCb && func )

Set the callback to be invoked when the forwarding encapsulation session is detected and to notify application about such session creation.

When not set, the forwarding enapsulation messages will be ignored

Parameters

[in] func R-value reference to the callback object

◆ setFwdEncSessionDeletedReportCb()

void cc_mqttsn_gateway::Session::setFwdEncSessionDeletedReportCb ( FwdEncSessionDeletedReportCb && func )

Set the callback to be invoked when the forwarding encapsulation session is about to be deleted.

Parameters

[in] func R-value reference to the callback object

◆ setGatewayId()

void cc_mqttsn_gateway::Session::setGatewayId ( std::uint8_t value )

Set gateway numeric ID to be reported when requested.

If not set, default value 0 is assumed.

Parameters

[in] value Gateway numeric ID.

◆ setNextTickProgramReqCb()

void cc_mqttsn_gateway::Session::setNextTickProgramReqCb ( NextTickProgramReqCb && func )

Set the callback to be invoked when new time measurement is required.

This is a must have callback, without it the object can not be started (see start()).

Parameters

[in] func R-value reference to the callback object

◆ setPubOnlyKeepAlive()

void cc_mqttsn_gateway::Session::setPubOnlyKeepAlive ( std::uint16_t value )

Provide default "keep alive" period for "publish only" clients, that do not make an attempt to connect to the gateway.

MQTT-SN protocol allows "publish only" clients that don't make any attempt to connect to the gateway/broker and send all their messages with QoS=-1. In this case, the gateway must connect to the broker on behalf of the "publish only" client. Such connection attempt requires to specify "keep alive" period. Use this function to set the value.

Parameters

[in] value Max number of seconds between messages the "publish only" client is going to send.

◆ setRetryCount()

void cc_mqttsn_gateway::Session::setRetryCount ( unsigned value )

Set number of retry attempts to perform before abandoning attempt to send unacknowledged message.

Some messages, may require acknowledgement by the client and/or broker. The amount of retry attempts before abandoning the attempt to deliver the message may be specified using this function. The default value is 3.

Parameters

[in] value Number of retry attempts.

◆ setRetryPeriod()

void cc_mqttsn_gateway::Session::setRetryPeriod ( unsigned value )

Set retry period to wait between resending unacknowledged message to the client and/or broker.

Some messages, may require acknowledgement by the client and/or broker. The delay (in seconds) between such attempts to resend the message may be specified using this function. The default value is 10 seconds.

Parameters

[in] value Number of seconds to wait before making an attempt to resend.

◆ setSendDataBrokerReqCb()

void cc_mqttsn_gateway::Session::setSendDataBrokerReqCb ( BrokerSendDataReqCb && func )

Set the callback to be invoked when new data needs to be sent to the broker.

This is a must have callback, without it the object can not be started (see start()).

Parameters

[in] func R-value reference to the callback object

◆ setSendDataClientReqCb()

void cc_mqttsn_gateway::Session::setSendDataClientReqCb ( ClientSendDataReqCb && func )

Set the callback to be invoked when new data needs to be sent to the client.

This is a must have callback, without it the object can not be started (see start()).

Parameters

[in] func R-value reference to the callback object

◆ setSleepingClientMsgLimit()

void cc_mqttsn_gateway::Session::setSleepingClientMsgLimit ( std::size_t value )

Provide limit to number pending messages being accumulated for the sleeping client.

When client is known to be in "ASLEEP" state, the gateway must accumulate all the messages the broker sends until client wakes up or explicitly requests to send them. This function may be used to limit amount of such messages to prevent acquiring lots of RAM by the gateway application.

Parameters

[in] value Max number of pending messages.

◆ setTerminationReqCb()

void cc_mqttsn_gateway::Session::setTerminationReqCb ( TerminationReqCb && func )

Set the callback to be invoked when the session needs to be terminated and this Session object deleted.

This is a must have callback, without it the object can not be started (see start()).

Parameters

[in] func R-value reference to the callback object

◆ setTopicIdAllocationRange()

bool cc_mqttsn_gateway::Session::setTopicIdAllocationRange	(	std::uint16_t	minVal,
		std::uint16_t	maxVal
	)

Limit range of topic IDs allocated for newly registered topics.

Parameters

[in]	minVal	Min topic ID.
[in]	maxVal	Max topic ID.

Returns: success/failure status

◆ start()

bool cc_mqttsn_gateway::Session::start ( )

Start this object's operation.

The function will check whether all necessary callbacks have been set.

Returns: true if the operation has been successfully started, false in case some necessary callback hasn't been set.

◆ tick()

void cc_mqttsn_gateway::Session::tick ( )

Notify the Session object about requested time period expiry.

This function needs to be called from the driving code after the requested time measurement has expired.

The documentation for this class was generated from the following file:

include/cc_mqttsn_gateway/Session.h

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ AuthInfo

◆ AuthInfoReqCb

◆ BrokerReconnectReqCb

◆ BrokerSendDataReqCb

◆ CancelTickWaitReqCb

◆ ClientConnectedReportCb

◆ ClientSendDataReqCb

◆ ErrorReportCb

◆ FwdEncSessionCreatedReportCb

◆ FwdEncSessionDeletedReportCb

◆ NextTickProgramReqCb

◆ TerminationReqCb

Member Function Documentation

◆ addPredefinedTopic()

◆ dataFromBroker()

◆ dataFromClient()

◆ isRunning()

◆ setAuthInfoReqCb()

◆ setBrokerConnected()

◆ setBrokerReconnectReqCb()

◆ setCancelTickWaitReqCb()

◆ setClientConnectedReportCb()

◆ setDefaultClientId()

◆ setErrorReportCb()

◆ setFwdEncSessionCreatedReportCb()

◆ setFwdEncSessionDeletedReportCb()

◆ setGatewayId()

◆ setNextTickProgramReqCb()

◆ setPubOnlyKeepAlive()

◆ setRetryCount()

◆ setRetryPeriod()

◆ setSendDataBrokerReqCb()

◆ setSendDataClientReqCb()

◆ setSleepingClientMsgLimit()

◆ setTerminationReqCb()

◆ setTopicIdAllocationRange()

◆ start()

◆ tick()