NetBurner 3.5.6
PDF Version
MQTT::Client Class Reference

Advanced low-level MQTT Client for interacting with Mqtt Brokers. The client handles all network communications with the Broker and handles local message queueing and dispatching to topic handlers. More...

#include <mqtt.h>

Inherits TimeOutManager.

Inherited by MQTT::ConfiguredClient.

Public Types

enum  eSessionLimit {
  eLimit_Size_Tx , eLimit_Size_Rx , eLimit_InFlight_Tx , eLimit_InFlight_Rx ,
  eLimit_Subscriptions , eLimit_SubAliases , eLimit_PublishAliases , eLimit_QoS ,
  eLimit_SessionExpirary
}
 Limit types for the Client interactions with the Broker. More...
 
enum  eRateLimitType { eRateLimit_Publish , eRateLimit_Subscribe }
 Rate limit types for Client messaging. More...
 
enum  eRateLimitAdjustMethod { eRateLimitAdj_None , eRateLimitAdj_Set , eRateLimitAdj_Add , eRateLimitAdj_Subtract }
 How to adjust rate limit buckets when modifying the current rate limit. More...
 
enum  eConnectionStatus {
  eConnStat_Error , eConnStat_No_Broker_Configured , eConnStat_Resolving , eConnStat_InProgress ,
  eConnStat_Established , eConnStat_Refused , eConnStat_Disconnected
}
 Connection state values. More...
 

Public Member Functions

 Client (const char *brokerURI, const char *pClientId, uint16_t maxKeepAlive=MQTT_DEFAULT_KEEP_ALIVE, bool bCleanStart=true, PublishRequest *lwtMsg=NULL, const char *pConnMsg=NULL, const char *pDisconnMsg=NULL, const char *pUsername=NULL, const char *pPassword=NULL, RequestProperty *addProps=NULL, bool ConnectOnStartup=true)
 Constructor. This version takes a raw string for the broker URI.
 
 Client (const ParsedURI *brokerURI, const char *pClientId, uint16_t maxKeepAlive=MQTT_DEFAULT_KEEP_ALIVE, bool bCleanStart=true, PublishRequest *lwtMsg=NULL, const char *pConnMsg=NULL, const char *pDisconnMsg=NULL, const char *pUsername=NULL, const char *pPassword=NULL, RequestProperty *addProps=NULL, bool ConnectOnStartup=true)
 Constructor. This version takes a ParsedURI object for the broker URI.
 
int Connect (bool bWaitForConnection, const char *pNewBrokerURI, ConnAckCb_t notifyCb=NULL, void *notifyCtx=NULL)
 Begin the process of Connecting the client to the Broker.
 
int Connect (bool bWaitForConnection=true, const ParsedURI *pNewBrokerURI=NULL, ConnAckCb_t notifyCb=NULL, void *notifyCtx=NULL)
 Begin the process of Connecting the client to the Broker.
 
int Disconnect ()
 Disconnect the Client from the Broker.
 
void SetConnectNotify (ConnAckCb_t notifyCb, void *notifyCtx)
 Set the connection notification callback and it's context information.
 
int SetRateLimit (eRateLimitType type, uint8_t bucketMax, uint8_t fillCount, uint8_t fillTicks, eRateLimitAdjustMethod adjMethod, uint8_t adjCount)
 Set the value for a given rate limit.
 
int SetRateLimit_Publish (int reqPerSecond)
 Set the Publish rate limit. This method automatically determines the fillCount and fillTicks to use for refilling the credit bucket.
 
int SetRateLimit_Subscribe (int reqPerSecond)
 Set the Subscribe rate limit. This method automatically determines the fillCount and fillTicks to use for refilling the credit bucket.
 
eConnectionStatus GetConnectionStatus ()
 Get the current state of the Client's connection to the Broker.
 
void SetClientCert (uint8_t *cert, uint32_t len, uint8_t *privkey, uint32_t privlen)
 Set the Client Certificate and Private Key to use when connecting to a Broker via TLS.
 
void GetClientCert (uint8_t **cert, uint32_t *len, uint8_t **privkey, uint32_t *privlen)
 Set the Client Certificate and Private Key to use when connecting to a Broker via TLS.
 
int QueuePublish (mqtt_leaf &leaf)
 Queue an MqttObj to be published.
 
int QueueSubscribe (mqtt_leaf &leaf)
 Queue an MqttObj to subscribe.
 
int QueueUnsubscribe (mqtt_leaf &leaf)
 Queue an MqttObj to unsubscribe.
 
int QueueAllSubscriptions ()
 Queue all Client's registered MqttObjs to be subscribed and published according to the object's operation flags.
 
int Publish (const char *topic, uint8_t *pData, uint32_t len, int prio, TickTimeout &t, uint8_t qos=0)
 Publish a binary payload message.
 
int Publish (const char *topic, const char *pStr, int prio, TickTimeout &t, uint8_t qos=0)
 Publish a message.
 
int Publish (PublishRequest *req, int prio, TickTimeout &t)
 Publish a fully defined request.
 
int QueuePublish (PublishRequest *req, int *prio)
 Queue a publish message from a fully defined request.
 
int Subscribe (TopicHandler &handler, int *handlerIdx, TickTimeout &t, uint8_t subOpts=Pkt::eSubOpt_NoLocal)
 Register a TopicHandler and subscribe its Topic on the Broker.
 
int Subscribe (SubscribeRequest *req, int *handlerIdx, TickTimeout &t)
 Register a TopicHandler (via fully specified SubscribeRequest) and subscribe its Topic on the Broker.
 
int QueueSubscribe (SubUnsubQueueMsg *qmsg)
 Register a TopicHandler and subscribe its Topic on the Broker.
 
int Unsubscribe (int handlerIdx, TickTimeout &t, const char *topicFilter=NULL)
 Unsubscribe and deregister a TopicHandler.
 
int Unsubscribe (const char *topicFilter, TickTimeout &t)
 Unsubscribe and deregister a TopicHandler.
 
int QueueUnsubscribe (SubUnsubQueueMsg *qmsg)
 Queue unsubscribing and deregistering a TopicHandler.
 
int RegisterTopicHandler (TopicHandler *newHandler, int *handlerIdx)
 Register a TopicHandler with the Client.
 
int RemoveTopicHandler (TopicHandler *handler)
 Remove/deregister a TopicHandler from the Client by reference.
 
int RemoveTopicHandler (int handlerIdx)
 Remove/deregister a TopicHandler from the Client by index.
 
void RegisterMqttObj (mqtt_leaf &leaf, uint32_t interval=0)
 Register an MqttObj with the Client.
 
void RemoveObj (mqtt_leaf &leaf)
 Deregister/remove an MqttObj from the Client.
 
int SendNextPubReq ()
 Send the next queued Publish Request.
 
int SendNextSubReq ()
 Send the next queued SubUnSub Request.
 

Static Public Member Functions

static void StartTask (uint8_t taskPrio=MQTT_TASK_PRIO)
 Start the Client Task.
 
static ClientGetFirstClient ()
 Start the Client Task.
 

Detailed Description

Advanced low-level MQTT Client for interacting with Mqtt Brokers. The client handles all network communications with the Broker and handles local message queueing and dispatching to topic handlers.

Basic users should use the ConfiguredClient for easier implementation.

Member Enumeration Documentation

◆ eConnectionStatus

Connection state values.

Enumerator
eConnStat_Error 

General error with client connection.

eConnStat_No_Broker_Configured 

Error, no broker configured to be used.

eConnStat_Resolving 

Currently resolving broker address.

eConnStat_InProgress 

Connection to broker in progress.

eConnStat_Established 

Connection with broker established.

eConnStat_Refused 

Connection refused by broker.

◆ eRateLimitAdjustMethod

How to adjust rate limit buckets when modifying the current rate limit.

Enumerator
eRateLimitAdj_None 

Do not modify the current limit token count.

eRateLimitAdj_Set 

Set the current limit token count to the adjustment value.

eRateLimitAdj_Add 

Add the adjustment value to the current token count.

eRateLimitAdj_Subtract 

Subtract the adjustment value from the current token count.

◆ eRateLimitType

Rate limit types for Client messaging.

Enumerator
eRateLimit_Publish 

Limit for Publish requests per second.

eRateLimit_Subscribe 

Limit for Subscribe requests per second.

◆ eSessionLimit

Limit types for the Client interactions with the Broker.

Enumerator
eLimit_Size_Tx 

Maximum receive message size accepted.

eLimit_Size_Rx 

Maximum transmit message size allowed.

eLimit_InFlight_Tx 

Maximum number of outstanding tx messages with QoS > 0.

eLimit_InFlight_Rx 

Maximum number of outstanding rx messages with QoS > 0.

eLimit_Subscriptions 

Maximum number of topic subscriptions.

eLimit_SubAliases 

Maximum number of subscription aliases.

eLimit_PublishAliases 

Maximum number of Publish topic name aliases.

eLimit_QoS 

Maximum QoS for messages.

eLimit_SessionExpirary 

Maximum time for Session before expiring.

Constructor & Destructor Documentation

◆ Client() [1/2]

MQTT::Client::Client ( const char * brokerURI,
const char * pClientId,
uint16_t maxKeepAlive = MQTT_DEFAULT_KEEP_ALIVE,
bool bCleanStart = true,
PublishRequest * lwtMsg = NULL,
const char * pConnMsg = NULL,
const char * pDisconnMsg = NULL,
const char * pUsername = NULL,
const char * pPassword = NULL,
RequestProperty * addProps = NULL,
bool ConnectOnStartup = true )

Constructor. This version takes a raw string for the broker URI.

Parameters
*brokerURIThe URI for the broker to use. (Must be a URI with protocol, like mqtt://1.2.3.4)
*pClientIdA string containing the Client ID to use with the broker
maxKeepAliveThe number of seconds when, after multiple failed MQTT keepalive messages, the connection will be automatically restarted (Note: the server may impose a different maximum keepalive)
bCleanStartWhether the broker start a fresh session and remove any previous subscriptions.
*lwtMsgPointer to a PublishRequest containing the Last Will and Testament to use for this client's connections
*pConnMsgMessage payload to send to the LWT topic after connecting to the broker.
*pDisconnMsgMessage payload to send to the LWT topic just prior to intentionally disconnecting from the broker.
*pUsernameUsername to use when connecting to the broker.
*pPasswordPassword to use when connecting to the broker.
*addPropsAdditional message Properties to send with Connection Requests
ConnectOnStartupWhether the client should automatically connect after startup.

◆ Client() [2/2]

MQTT::Client::Client ( const ParsedURI * brokerURI,
const char * pClientId,
uint16_t maxKeepAlive = MQTT_DEFAULT_KEEP_ALIVE,
bool bCleanStart = true,
PublishRequest * lwtMsg = NULL,
const char * pConnMsg = NULL,
const char * pDisconnMsg = NULL,
const char * pUsername = NULL,
const char * pPassword = NULL,
RequestProperty * addProps = NULL,
bool ConnectOnStartup = true )

Constructor. This version takes a ParsedURI object for the broker URI.

Parameters
*brokerURIThe URI for the broker to use. (Must be a URI with protocol, like mqtt://1.2.3.4)
*pClientIdA string containing the Client ID to use with the broker
maxKeepAliveThe number of seconds when, after multiple failed MQTT keepalive messages, the connection will be automatically restarted (Note: the server may impose a different maximum keepalive)
bCleanStartWhether the broker start a fresh session and remove any previous subscriptions.
*lwtMsgPointer to a PublishRequest containing the Last Will and Testament to use for this client's connections
*pConnMsgMessage payload to send to the LWT topic after connecting to the broker.
*pDisconnMsgMessage payload to send to the LWT topic just prior to intentionally disconnecting from the broker.
*pUsernameUsername to use when connecting to the broker.
*pPasswordPassword to use when connecting to the broker.
*addPropsAdditional message Properties to send with Connection Requests
ConnectOnStartupWhether the client should automatically connect after startup.

Member Function Documentation

◆ Connect() [1/2]

int MQTT::Client::Connect ( bool bWaitForConnection,
const char * pNewBrokerURI,
ConnAckCb_t notifyCb = NULL,
void * notifyCtx = NULL )

Begin the process of Connecting the client to the Broker.

Parameters
bWaitForConnectionWait for the client to finish connecting to the broker before returning.
pNewBrokerURIIf non-null, a pointer to the new Broker URI to use
notifyCbPointer to a notification callback for connection state events.
notifyCtxContext to pass to the notification callback as additional data.
Returns
eResult_t indicating result

◆ Connect() [2/2]

int MQTT::Client::Connect ( bool bWaitForConnection = true,
const ParsedURI * pNewBrokerURI = NULL,
ConnAckCb_t notifyCb = NULL,
void * notifyCtx = NULL )

Begin the process of Connecting the client to the Broker.

Parameters
bWaitForConnectionWait for the client to finish connecting to the broker before returning.
pNewBrokerURIIf non-null, a pointer to the new Broker ParsedURI to use
notifyCbPointer to a notification callback for connection state events.
notifyCtxContext to pass to the notification callback as additional data.
Returns
eResult_t indicating result

◆ Disconnect()

int MQTT::Client::Disconnect ( )

Disconnect the Client from the Broker.

Returns
eResult_t indicating result

◆ GetClientCert()

void MQTT::Client::GetClientCert ( uint8_t ** cert,
uint32_t * len,
uint8_t ** privkey,
uint32_t * privlen )
inline

Set the Client Certificate and Private Key to use when connecting to a Broker via TLS.

Parameters
**certPointer to return pointer for the certificate buffer address
*lenPointer to return value for the length of the certificate
**privkeyPointer to return pointer for the the private key buffer address
*privlenPointer to return value for the length of the private key
See also
Client::GetClientCert

◆ GetConnectionStatus()

eConnectionStatus MQTT::Client::GetConnectionStatus ( )

Get the current state of the Client's connection to the Broker.

Returns
eConnectionStatus The current status of the client's connection to the Broker
See also
Client::Connect, Client::Disconnect, Client::GetConnectionStatusString

◆ GetFirstClient()

static Client * MQTT::Client::GetFirstClient ( )
inlinestatic

Start the Client Task.

Returns
Pointer to the first registered Client

◆ Publish() [1/3]

int MQTT::Client::Publish ( const char * topic,
const char * pStr,
int prio,
TickTimeout & t,
uint8_t qos = 0 )

Publish a message.

Parameters
*topicTopic to publish message to
*pStrString containing data to be published
prioPriority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN)
&tTimeout indicating how long to block before returning timeout error
qosQuality of Service level to use for the resulting Publish message
Returns
eResult_t return code
See also
Client::QueuePublish

◆ Publish() [2/3]

int MQTT::Client::Publish ( const char * topic,
uint8_t * pData,
uint32_t len,
int prio,
TickTimeout & t,
uint8_t qos = 0 )

Publish a binary payload message.

Parameters
*topicTopic to publish message to
*pDataData to be published
lenLength of data to be published
prioPriority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN)
&tTimeout indicating how long to block before returning timeout error
qosQuality of Service level to use for the resulting Publish message
Returns
eResult_t return code
See also
Client::QueuePublish

◆ Publish() [3/3]

int MQTT::Client::Publish ( PublishRequest * req,
int prio,
TickTimeout & t )

Publish a fully defined request.

Parameters
*reqPublish Request describing the message to be sent
prioPriority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN)
&tTimeout indicating how long to block before returning timeout error
Returns
eResult_t return code
See also
Client::QueuePublish

◆ QueueAllSubscriptions()

int MQTT::Client::QueueAllSubscriptions ( )

Queue all Client's registered MqttObjs to be subscribed and published according to the object's operation flags.

Returns
eResult_t return code
See also
Client::QueuePublish, Client::QueueSubscribe

◆ QueuePublish() [1/2]

int MQTT::Client::QueuePublish ( mqtt_leaf & leaf)

Queue an MqttObj to be published.

Parameters
&leafReference to the object to publish.
Returns
eResult_t return code
See also
Client::QueueSubscribe, Client::QueueUnsubscribe

◆ QueuePublish() [2/2]

int MQTT::Client::QueuePublish ( PublishRequest * req,
int * prio )

Queue a publish message from a fully defined request.

Parameters
*reqPublish Request describing the message to be sent
prioPriority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN)
Returns
eResult_t return code
See also
Client::Publish

◆ QueueSubscribe() [1/2]

int MQTT::Client::QueueSubscribe ( mqtt_leaf & leaf)

Queue an MqttObj to subscribe.

Parameters
&leafReference to the object to subscribe.
Returns
eResult_t return code
See also
Client::QueuePublish, Client::QueueUnsubscribe

◆ QueueSubscribe() [2/2]

int MQTT::Client::QueueSubscribe ( SubUnsubQueueMsg * qmsg)

Register a TopicHandler and subscribe its Topic on the Broker.

Parameters
*qmsgPointer to asynchronous Subscription Request structure
Returns
eResult_t return code
See also
Client::Subscribe

◆ QueueUnsubscribe() [1/2]

int MQTT::Client::QueueUnsubscribe ( mqtt_leaf & leaf)

Queue an MqttObj to unsubscribe.

Parameters
&leafReference to the object to unsubscribe.
Returns
eResult_t return code
See also
Client::QueuePublish, Client::QueueSubscribe

◆ QueueUnsubscribe() [2/2]

int MQTT::Client::QueueUnsubscribe ( SubUnsubQueueMsg * qmsg)

Queue unsubscribing and deregistering a TopicHandler.

Parameters
*qmsgPointer to fully defined unsubscription request
Returns
eResult_t return code
See also
Client::Unsubscribe

◆ RegisterMqttObj()

void MQTT::Client::RegisterMqttObj ( mqtt_leaf & leaf,
uint32_t interval = 0 )

Register an MqttObj with the Client.

Parameters
&leafReference to the MqttObj to be registered with the Client
intervalPublication interval (in TimeTicks) for the registered object
See also
Client::RemoveObj

◆ RegisterTopicHandler()

int MQTT::Client::RegisterTopicHandler ( TopicHandler * newHandler,
int * handlerIdx )

Register a TopicHandler with the Client.

Parameters
*newHandlerPointer to the TopicHanler to Register
*handlerIdxPointer to return value of the index the handler is registered at
Returns
eResult_t return code
See also
Client::Subscribe

◆ RemoveObj()

void MQTT::Client::RemoveObj ( mqtt_leaf & leaf)

Deregister/remove an MqttObj from the Client.

Parameters
&leafReference to the MqttObj to be removed from the Client
See also
Client::RemoveObj

◆ RemoveTopicHandler() [1/2]

int MQTT::Client::RemoveTopicHandler ( int handlerIdx)

Remove/deregister a TopicHandler from the Client by index.

Parameters
handlerIdxRegistration index of the topic handler to be removed
Returns
eResult_t return code
See also
Client::Unsubscribe

◆ RemoveTopicHandler() [2/2]

int MQTT::Client::RemoveTopicHandler ( TopicHandler * handler)

Remove/deregister a TopicHandler from the Client by reference.

Parameters
*handlerPointer to the TopicHandler to be removed
Returns
eResult_t return code
See also
Client::Unsubscribe

◆ SendNextPubReq()

int MQTT::Client::SendNextPubReq ( )

Send the next queued Publish Request.

Returns
eResult_t return code
See also
Client::SendNextSubReq

◆ SendNextSubReq()

int MQTT::Client::SendNextSubReq ( )

Send the next queued SubUnSub Request.

Returns
eResult_t return code
See also
Client::SendNextPubReq

◆ SetClientCert()

void MQTT::Client::SetClientCert ( uint8_t * cert,
uint32_t len,
uint8_t * privkey,
uint32_t privlen )
inline

Set the Client Certificate and Private Key to use when connecting to a Broker via TLS.

Parameters
*certPointer to the certificate buffer to use
lenLength of the certificate
*privkeyPointer to the private key buffer
privlenLength of the private key
See also
Client::GetClientCert

◆ SetConnectNotify()

void MQTT::Client::SetConnectNotify ( ConnAckCb_t notifyCb,
void * notifyCtx )

Set the connection notification callback and it's context information.

Parameters
notifyCbNotification callback for connection state events.
notifyCtxContext to pass to the notification callback as additional data.

◆ SetRateLimit()

int MQTT::Client::SetRateLimit ( eRateLimitType type,
uint8_t bucketMax,
uint8_t fillCount,
uint8_t fillTicks,
eRateLimitAdjustMethod adjMethod,
uint8_t adjCount )

Set the value for a given rate limit.

Parameters
typeThe rate limit to set the value of.
bucketMaxThe maximum count for the limit bucket (i.e. burst maximum)
fillCountThe count to add to the bucket each time interval
fillTicksThe interval, in TimeTicks, between each filling of the bucket.
adjMethodThe adjustment type to perform to the current bucket count when setting the new rate limit.
adjCountThe count to use when adjusting the current bucket count.
Returns
eResult_t Return code
See also
Client::SetRateLimit_Publish, Client::SetRateLimit_Subscribe

◆ SetRateLimit_Publish()

int MQTT::Client::SetRateLimit_Publish ( int reqPerSecond)

Set the Publish rate limit. This method automatically determines the fillCount and fillTicks to use for refilling the credit bucket.

Parameters
reqPerSecondThe maximum number of allowed Publish messages per second.
Returns
eResult_t Return code
See also
Client::SetRateLimit, Client::SetRateLimit_Subscribe

◆ SetRateLimit_Subscribe()

int MQTT::Client::SetRateLimit_Subscribe ( int reqPerSecond)

Set the Subscribe rate limit. This method automatically determines the fillCount and fillTicks to use for refilling the credit bucket.

Parameters
reqPerSecondThe maximum number of allowed Publish messages per second.
Returns
eResult_t Return code
See also
Client::SetRateLimit, Client::SetRateLimit_Publish

◆ StartTask()

static void MQTT::Client::StartTask ( uint8_t taskPrio = MQTT_TASK_PRIO)
static

Start the Client Task.

Parameters
taskPrioThe OS Task Priority to assign to the Client Task

◆ Subscribe() [1/2]

int MQTT::Client::Subscribe ( SubscribeRequest * req,
int * handlerIdx,
TickTimeout & t )

Register a TopicHandler (via fully specified SubscribeRequest) and subscribe its Topic on the Broker.

Parameters
*reqFully described subscription request to be sent to the Broker
*handlerIdxPointer to int to return the registration index of the TopicHandler
&tTimeout indicating how long to block before returning timeout error
Returns
eResult_t return code
See also
Client::QueueSubscribe

◆ Subscribe() [2/2]

int MQTT::Client::Subscribe ( TopicHandler & handler,
int * handlerIdx,
TickTimeout & t,
uint8_t subOpts = Pkt::eSubOpt_NoLocal )

Register a TopicHandler and subscribe its Topic on the Broker.

Parameters
&handlerTopicHandler to be registered and subscribed
*handlerIdxPointer to int to return the registration index of the TopicHandler
&tTimeout indicating how long to block before returning timeout error
subOptsFlags describing Subscription options to request when Subscribing on the Broker
Returns
eResult_t return code
See also
Client::QueueSubscribe

◆ Unsubscribe() [1/2]

int MQTT::Client::Unsubscribe ( const char * topicFilter,
TickTimeout & t )

Unsubscribe and deregister a TopicHandler.

Parameters
*topicFilterThe Topic Filter of the registered TopicHandler and on the broker to be Unsubscribed from
&tTimeout indicating how long to block before returning timeout error
Returns
eResult_t return code
See also
Client::QueueUnsubscribe

◆ Unsubscribe() [2/2]

int MQTT::Client::Unsubscribe ( int handlerIdx,
TickTimeout & t,
const char * topicFilter = NULL )

Unsubscribe and deregister a TopicHandler.

Parameters
handlerIdxThe registration index of the TopicHandler to unsubscribe and deregister
&tTimeout indicating how long to block before returning timeout error
*topicFilterThe Topic Filter on the broker to be Unsubscribed from
Returns
eResult_t return code
See also
Client::QueueUnsubscribe

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