|
NetBurner 3.5.6
PDF Version |
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 Client * | GetFirstClient () |
| Start the Client Task. | |
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.
Connection state values.
How to adjust rate limit buckets when modifying the current rate limit.
Rate limit types for Client messaging.
| Enumerator | |
|---|---|
| eRateLimit_Publish | Limit for Publish requests per second. |
| eRateLimit_Subscribe | Limit for Subscribe requests per second. |
Limit types for the Client interactions with the Broker.
| 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.
| *brokerURI | The URI for the broker to use. (Must be a URI with protocol, like mqtt://1.2.3.4) |
| *pClientId | A string containing the Client ID to use with the broker |
| maxKeepAlive | The 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) |
| bCleanStart | Whether the broker start a fresh session and remove any previous subscriptions. |
| *lwtMsg | Pointer to a PublishRequest containing the Last Will and Testament to use for this client's connections |
| *pConnMsg | Message payload to send to the LWT topic after connecting to the broker. |
| *pDisconnMsg | Message payload to send to the LWT topic just prior to intentionally disconnecting from the broker. |
| *pUsername | Username to use when connecting to the broker. |
| *pPassword | Password to use when connecting to the broker. |
| *addProps | Additional message Properties to send with Connection Requests |
| ConnectOnStartup | Whether the client should automatically connect after startup. |
| 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.
| *brokerURI | The URI for the broker to use. (Must be a URI with protocol, like mqtt://1.2.3.4) |
| *pClientId | A string containing the Client ID to use with the broker |
| maxKeepAlive | The 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) |
| bCleanStart | Whether the broker start a fresh session and remove any previous subscriptions. |
| *lwtMsg | Pointer to a PublishRequest containing the Last Will and Testament to use for this client's connections |
| *pConnMsg | Message payload to send to the LWT topic after connecting to the broker. |
| *pDisconnMsg | Message payload to send to the LWT topic just prior to intentionally disconnecting from the broker. |
| *pUsername | Username to use when connecting to the broker. |
| *pPassword | Password to use when connecting to the broker. |
| *addProps | Additional message Properties to send with Connection Requests |
| ConnectOnStartup | Whether the client should automatically connect after startup. |
| 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.
| bWaitForConnection | Wait for the client to finish connecting to the broker before returning. |
| pNewBrokerURI | If non-null, a pointer to the new Broker URI to use |
| notifyCb | Pointer to a notification callback for connection state events. |
| notifyCtx | Context to pass to the notification callback as additional data. |
| 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.
| bWaitForConnection | Wait for the client to finish connecting to the broker before returning. |
| pNewBrokerURI | If non-null, a pointer to the new Broker ParsedURI to use |
| notifyCb | Pointer to a notification callback for connection state events. |
| notifyCtx | Context to pass to the notification callback as additional data. |
| int MQTT::Client::Disconnect | ( | ) |
Disconnect the Client from the Broker.
|
inline |
Set the Client Certificate and Private Key to use when connecting to a Broker via TLS.
| **cert | Pointer to return pointer for the certificate buffer address |
| *len | Pointer to return value for the length of the certificate |
| **privkey | Pointer to return pointer for the the private key buffer address |
| *privlen | Pointer to return value for the length of the private key |
| eConnectionStatus MQTT::Client::GetConnectionStatus | ( | ) |
Get the current state of the Client's connection to the Broker.
|
inlinestatic |
| int MQTT::Client::Publish | ( | const char * | topic, |
| const char * | pStr, | ||
| int | prio, | ||
| TickTimeout & | t, | ||
| uint8_t | qos = 0 ) |
Publish a message.
| *topic | Topic to publish message to |
| *pStr | String containing data to be published |
| prio | Priority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN) |
| &t | Timeout indicating how long to block before returning timeout error |
| qos | Quality of Service level to use for the resulting Publish message |
| 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.
| *topic | Topic to publish message to |
| *pData | Data to be published |
| len | Length of data to be published |
| prio | Priority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN) |
| &t | Timeout indicating how long to block before returning timeout error |
| qos | Quality of Service level to use for the resulting Publish message |
| int MQTT::Client::Publish | ( | PublishRequest * | req, |
| int | prio, | ||
| TickTimeout & | t ) |
Publish a fully defined request.
| *req | Publish Request describing the message to be sent |
| prio | Priority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN) |
| &t | Timeout indicating how long to block before returning timeout error |
| int MQTT::Client::QueueAllSubscriptions | ( | ) |
Queue all Client's registered MqttObjs to be subscribed and published according to the object's operation flags.
| int MQTT::Client::QueuePublish | ( | mqtt_leaf & | leaf | ) |
Queue an MqttObj to be published.
| &leaf | Reference to the object to publish. |
| int MQTT::Client::QueuePublish | ( | PublishRequest * | req, |
| int * | prio ) |
Queue a publish message from a fully defined request.
| *req | Publish Request describing the message to be sent |
| prio | Priority level of the message to be published (see MQTT_OBJ_PRIORITY_MAX and MQTT_OBJ_PRIORITY_MIN) |
| int MQTT::Client::QueueSubscribe | ( | mqtt_leaf & | leaf | ) |
Queue an MqttObj to subscribe.
| &leaf | Reference to the object to subscribe. |
| int MQTT::Client::QueueSubscribe | ( | SubUnsubQueueMsg * | qmsg | ) |
Register a TopicHandler and subscribe its Topic on the Broker.
| *qmsg | Pointer to asynchronous Subscription Request structure |
| int MQTT::Client::QueueUnsubscribe | ( | mqtt_leaf & | leaf | ) |
Queue an MqttObj to unsubscribe.
| &leaf | Reference to the object to unsubscribe. |
| int MQTT::Client::QueueUnsubscribe | ( | SubUnsubQueueMsg * | qmsg | ) |
Queue unsubscribing and deregistering a TopicHandler.
| *qmsg | Pointer to fully defined unsubscription request |
| void MQTT::Client::RegisterMqttObj | ( | mqtt_leaf & | leaf, |
| uint32_t | interval = 0 ) |
Register an MqttObj with the Client.
| &leaf | Reference to the MqttObj to be registered with the Client |
| interval | Publication interval (in TimeTicks) for the registered object |
| int MQTT::Client::RegisterTopicHandler | ( | TopicHandler * | newHandler, |
| int * | handlerIdx ) |
Register a TopicHandler with the Client.
| *newHandler | Pointer to the TopicHanler to Register |
| *handlerIdx | Pointer to return value of the index the handler is registered at |
| void MQTT::Client::RemoveObj | ( | mqtt_leaf & | leaf | ) |
Deregister/remove an MqttObj from the Client.
| &leaf | Reference to the MqttObj to be removed from the Client |
| int MQTT::Client::RemoveTopicHandler | ( | int | handlerIdx | ) |
Remove/deregister a TopicHandler from the Client by index.
| handlerIdx | Registration index of the topic handler to be removed |
| int MQTT::Client::RemoveTopicHandler | ( | TopicHandler * | handler | ) |
Remove/deregister a TopicHandler from the Client by reference.
| *handler | Pointer to the TopicHandler to be removed |
| int MQTT::Client::SendNextPubReq | ( | ) |
| int MQTT::Client::SendNextSubReq | ( | ) |
|
inline |
Set the Client Certificate and Private Key to use when connecting to a Broker via TLS.
| *cert | Pointer to the certificate buffer to use |
| len | Length of the certificate |
| *privkey | Pointer to the private key buffer |
| privlen | Length of the private key |
| void MQTT::Client::SetConnectNotify | ( | ConnAckCb_t | notifyCb, |
| void * | notifyCtx ) |
Set the connection notification callback and it's context information.
| notifyCb | Notification callback for connection state events. |
| notifyCtx | Context to pass to the notification callback as additional data. |
| 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.
| type | The rate limit to set the value of. |
| bucketMax | The maximum count for the limit bucket (i.e. burst maximum) |
| fillCount | The count to add to the bucket each time interval |
| fillTicks | The interval, in TimeTicks, between each filling of the bucket. |
| adjMethod | The adjustment type to perform to the current bucket count when setting the new rate limit. |
| adjCount | The count to use when adjusting the current bucket count. |
| 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.
| reqPerSecond | The maximum number of allowed Publish messages per second. |
| 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.
| reqPerSecond | The maximum number of allowed Publish messages per second. |
|
static |
| int MQTT::Client::Subscribe | ( | SubscribeRequest * | req, |
| int * | handlerIdx, | ||
| TickTimeout & | t ) |
Register a TopicHandler (via fully specified SubscribeRequest) and subscribe its Topic on the Broker.
| *req | Fully described subscription request to be sent to the Broker |
| *handlerIdx | Pointer to int to return the registration index of the TopicHandler |
| &t | Timeout indicating how long to block before returning timeout error |
| 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.
| &handler | TopicHandler to be registered and subscribed |
| *handlerIdx | Pointer to int to return the registration index of the TopicHandler |
| &t | Timeout indicating how long to block before returning timeout error |
| subOpts | Flags describing Subscription options to request when Subscribing on the Broker |
| int MQTT::Client::Unsubscribe | ( | const char * | topicFilter, |
| TickTimeout & | t ) |
Unsubscribe and deregister a TopicHandler.
| *topicFilter | The Topic Filter of the registered TopicHandler and on the broker to be Unsubscribed from |
| &t | Timeout indicating how long to block before returning timeout error |
| int MQTT::Client::Unsubscribe | ( | int | handlerIdx, |
| TickTimeout & | t, | ||
| const char * | topicFilter = NULL ) |
Unsubscribe and deregister a TopicHandler.
| handlerIdx | The registration index of the TopicHandler to unsubscribe and deregister |
| &t | Timeout indicating how long to block before returning timeout error |
| *topicFilter | The Topic Filter on the broker to be Unsubscribed from |