Network Services API
2.60.00.07
|
The MQTTClient Module provides an easy-to-use API to enable constrained and deeply embedded micro-controller based products to interact with cloud or network based MQTT servers. The users of MQTTClient services, while benefiting from the abstraction of the MQTT protocol, will find them suitable for varied deployments of MQTT subscribers and/or publishers. More...
Data Structures | |
struct | MQTTClient_OperationMetaDataCB |
struct | MQTTClient_RecvMetaDataCB |
struct | MQTTClient_ConnParams |
struct | MQTTClient_Params |
struct | MQTTClient_SubscribeParams |
struct | MQTTClient_UnsubscribeParams |
struct | MQTTClient_Will |
Macros | |
#define | MQTTCLIENT_ERR_NETWORK MQTT_PACKET_ERR_NETWORK |
#define | MQTTCLIENT_ERR_TIMEOUT MQTT_PACKET_ERR_TIMEOUT |
#define | MQTTCLIENT_ERR_NET_OPS MQTT_PACKET_ERR_NET_OPS |
#define | MQTTCLIENT_ERR_FNPARAM MQTT_PACKET_ERR_FNPARAM |
#define | MQTTCLIENT_ERR_PKT_AVL MQTT_PACKET_ERR_PKT_AVL |
#define | MQTTCLIENT_ERR_PKT_LEN MQTT_PACKET_ERR_PKT_LEN |
#define | MQTTCLIENT_ERR_NOTCONN MQTT_PACKET_ERR_NOTCONN |
#define | MQTTCLIENT_ERR_BADCALL MQTT_PACKET_ERR_BADCALL |
#define | MQTTCLIENT_ERR_CONTENT MQTT_PACKET_ERR_CONTENT |
#define | MQTTCLIENT_ERR_LIBQUIT MQTT_PACKET_ERR_LIBQUIT |
#define | MQTTCLIENT_ERR_REMLSTN MQTT_PACKET_ERR_REMLSTN |
#define | MQTTCLIENT_OPERATION_CONNACK MQTT_CONNACK |
#define | MQTTCLIENT_OPERATION_EVT_PUBACK MQTT_PUBACK |
#define | MQTTCLIENT_OPERATION_PUBCOMP MQTT_PUBCOMP |
#define | MQTTCLIENT_OPERATION_SUBACK MQTT_SUBACK |
#define | MQTTCLIENT_OPERATION_UNSUBACK MQTT_UNSUBACK |
#define | MQTTCLIENT_NETCONN_IP4 MQTT_DEV_NETCONN_OPT_IP4 |
#define | MQTTCLIENT_NETCONN_IP6 MQTT_DEV_NETCONN_OPT_IP6 |
#define | MQTTCLIENT_NETCONN_URL MQTT_DEV_NETCONN_OPT_URL |
#define | MQTTCLIENT_NETCONN_SEC MQTT_DEV_NETCONN_OPT_SEC |
#define | MQTTCLIENT_NETCONN_SKIP_DOMAIN_NAME_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DOMAIN_NAME_VERIFICATION |
#define | MQTTCLIENT_NETCONN_SKIP_CERTIFICATE_CATALOG_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_CERTIFICATE_CATALOG_VERIFICATION |
#define | MQTTCLIENT_NETCONN_SKIP_DATE_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DATE_VERIFICATION |
Typedefs | |
typedef struct MQTTClient_OperationMetaDataCB | MQTTClient_OperationMetaDataCB |
typedef struct MQTTClient_RecvMetaDataCB | MQTTClient_RecvMetaDataCB |
typedef struct MQTTClient_ConnParams | MQTTClient_ConnParams |
typedef struct MQTTClient_Params | MQTTClient_Params |
typedef void(* | MQTTClient_CallBack) (int32_t event, void *metaData, uint32_t metaDateLen, void *data, uint32_t dataLen) |
typedef void * | MQTTClient_Handle |
typedef struct MQTTClient_SubscribeParams | MQTTClient_SubscribeParams |
typedef struct MQTTClient_UnsubscribeParams | MQTTClient_UnsubscribeParams |
typedef struct MQTTClient_Will | MQTTClient_Will |
Enumerations | |
enum | MQTTClient_Option { MQTTClient_USER_NAME = 0, MQTTClient_PASSWORD = 1, MQTTClient_WILL_PARAM = 2, MQTTClient_CALLBACKS = 3, MQTTClient_KEEPALIVE_TIME = 4, MQTTClient_CLEAN_CONNECT = 5, MQTTClient_MAX_PARAM = 6 } |
enum | MQTTClient_EventCB { MQTTClient_RECV_CB_EVENT = 0, MQTTClient_OPERATION_CB_EVENT = 1, MQTTClient_DISCONNECT_CB_EVENT = 2 } |
Functions | |
MQTTClient_Handle | MQTTClient_create (MQTTClient_CallBack defaultCallback, MQTTClient_Params *params) |
Create an MQTTClient instance. More... | |
int16_t | MQTTClient_delete (MQTTClient_Handle handle) |
Delete an MQTTClient instance. More... | |
int16_t | MQTTClient_run (MQTTClient_Handle handle) |
MQTTClient state machine. More... | |
int16_t | MQTTClient_connect (MQTTClient_Handle handle) |
Connect to a broker. More... | |
int16_t | MQTTClient_disconnect (MQTTClient_Handle handle) |
Disconnect from a broker. More... | |
int16_t | MQTTClient_publish (MQTTClient_Handle handle, char *topic, uint16_t topicLen, char *msg, uint16_t msgLen, uint32_t flags) |
Publish a named message to the broker. More... | |
int16_t | MQTTClient_subscribe (MQTTClient_Handle handle, MQTTClient_SubscribeParams *value, uint8_t numberOfTopics) |
Subscribe to a set of topics. More... | |
int16_t | MQTTClient_unsubscribe (MQTTClient_Handle handle, MQTTClient_UnsubscribeParams *value, uint8_t numberOfTopics) |
Unsubscribe from a set of topics. More... | |
int16_t | MQTTClient_set (MQTTClient_Handle handle, uint16_t option, void *value, uint16_t valueLength) |
Set client parameters. More... | |
int16_t | MQTTClient_get (MQTTClient_Handle handle, uint16_t option, void *value, uint16_t valueLength) |
Get client parameters. More... | |
The MQTTClient Module provides an easy-to-use API to enable constrained and deeply embedded micro-controller based products to interact with cloud or network based MQTT servers. The users of MQTTClient services, while benefiting from the abstraction of the MQTT protocol, will find them suitable for varied deployments of MQTT subscribers and/or publishers.
In addition to providing services to the application, each MQTTClient instance encompasses a RTOS task to handle the incoming messages from the server. Such a dedicated context to process the messages from the server facilitates the apps to receive data (i.e. PUBLISH messages) even when they are blocked, whilst awaiting ACK for a previous transaction with the server. The receive task in the MQTT Layer can not be disabled anytime, however its system wide priority is configurable and can be set.
Some of the salient features of the MQTTClient Layer are
The implementation enables the application developers to configure the following parameters using the compile line flags (-D option)
To use the MQTTClient APIs, the application should include its header file as follows:
And, add the following MQTT library to the link line:
#define MQTTCLIENT_ERR_NETWORK MQTT_PACKET_ERR_NETWORK |
Problem in network (sock err)
#define MQTTCLIENT_ERR_TIMEOUT MQTT_PACKET_ERR_TIMEOUT |
Net transaction has timed out
#define MQTTCLIENT_ERR_NET_OPS MQTT_PACKET_ERR_NET_OPS |
Platform Net Ops un-available
#define MQTTCLIENT_ERR_FNPARAM MQTT_PACKET_ERR_FNPARAM |
Invalid parameter(s) provided
#define MQTTCLIENT_ERR_PKT_AVL MQTT_PACKET_ERR_PKT_AVL |
No pkts are available in pool
#define MQTTCLIENT_ERR_PKT_LEN MQTT_PACKET_ERR_PKT_LEN |
Inadequate free buffer in pkt
#define MQTTCLIENT_ERR_NOTCONN MQTT_PACKET_ERR_NOTCONN |
Lib isn't CONNECTED to server
#define MQTTCLIENT_ERR_BADCALL MQTT_PACKET_ERR_BADCALL |
Irrelevant call for LIB state
#define MQTTCLIENT_ERR_CONTENT MQTT_PACKET_ERR_CONTENT |
MSG / Data content has errors
#define MQTTCLIENT_ERR_LIBQUIT MQTT_PACKET_ERR_LIBQUIT |
Needs reboot library has quit
#define MQTTCLIENT_ERR_REMLSTN MQTT_PACKET_ERR_REMLSTN |
No remote listener for socket
#define MQTTCLIENT_OPERATION_CONNACK MQTT_CONNACK |
CONNACK has been received from the server
#define MQTTCLIENT_OPERATION_EVT_PUBACK MQTT_PUBACK |
PUBACK has been received from the server
#define MQTTCLIENT_OPERATION_PUBCOMP MQTT_PUBCOMP |
PUBCOMP has been received from the server
#define MQTTCLIENT_OPERATION_SUBACK MQTT_SUBACK |
SUBACK has been received from the server
#define MQTTCLIENT_OPERATION_UNSUBACK MQTT_UNSUBACK |
UNSUBACK has been received from the server
#define MQTTCLIENT_NETCONN_IP4 MQTT_DEV_NETCONN_OPT_IP4 |
Assert for IPv4 connection
#define MQTTCLIENT_NETCONN_IP6 MQTT_DEV_NETCONN_OPT_IP6 |
Assert for IPv6 connection, otherwise IPv4
#define MQTTCLIENT_NETCONN_URL MQTT_DEV_NETCONN_OPT_URL |
Server address is an URL and not IP address
#define MQTTCLIENT_NETCONN_SEC MQTT_DEV_NETCONN_OPT_SEC |
Connection to server must be secure (TLS)
#define MQTTCLIENT_NETCONN_SKIP_DOMAIN_NAME_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DOMAIN_NAME_VERIFICATION |
Assert to skip domain name verification
#define MQTTCLIENT_NETCONN_SKIP_CERTIFICATE_CATALOG_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_CERTIFICATE_CATALOG_VERIFICATION |
Assert to skip certificate catalog verification
#define MQTTCLIENT_NETCONN_SKIP_DATE_VERIFICATION MQTT_DEV_NETCONN_OPT_SKIP_DATE_VERIFICATION |
Assert to skip date verification
typedef struct MQTTClient_OperationMetaDataCB MQTTClient_OperationMetaDataCB |
typedef struct MQTTClient_RecvMetaDataCB MQTTClient_RecvMetaDataCB |
typedef struct MQTTClient_ConnParams MQTTClient_ConnParams |
Secure Socket Parameters to open a secure connection
typedef struct MQTTClient_Params MQTTClient_Params |
typedef void(* MQTTClient_CallBack) (int32_t event, void *metaData, uint32_t metaDateLen, void *data, uint32_t dataLen) |
typedef void* MQTTClient_Handle |
typedef struct MQTTClient_SubscribeParams MQTTClient_SubscribeParams |
typedef struct MQTTClient_UnsubscribeParams MQTTClient_UnsubscribeParams |
typedef struct MQTTClient_Will MQTTClient_Will |
enum MQTTClient_Option |
enum MQTTClient_EventCB |
MQTTClient_Handle MQTTClient_create | ( | MQTTClient_CallBack | defaultCallback, |
MQTTClient_Params * | params | ||
) |
Create an MQTTClient instance.
[in] | defaultCallback | async event handler |
[in] | params | parameters |
int16_t MQTTClient_delete | ( | MQTTClient_Handle | handle | ) |
Delete an MQTTClient instance.
[in] | handle | handle to the MQTTClient instance |
int16_t MQTTClient_run | ( | MQTTClient_Handle | handle | ) |
MQTTClient state machine.
This function need to be called from the context created by the user in case of OS environment.
[in] | handle | handle to the MQTTClient instance |
int16_t MQTTClient_connect | ( | MQTTClient_Handle | handle | ) |
Connect to a broker.
[in] | handle | handle to the MQTTClient instance |
int16_t MQTTClient_disconnect | ( | MQTTClient_Handle | handle | ) |
Disconnect from a broker.
[in] | handle | handle to the MQTTClient instance |
int16_t MQTTClient_publish | ( | MQTTClient_Handle | handle, |
char * | topic, | ||
uint16_t | topicLen, | ||
char * | msg, | ||
uint16_t | msgLen, | ||
uint32_t | flags | ||
) |
Publish a named message to the broker.
In addition to the PUBLISH specific parameters, the caller can indicate whether the routine should block until the time, the message has been acknowledged by the server. This is applicable only for non-QoS0 messages.
In case, the app has chosen not to await for the ACK from the server, the MQTT implementation will notify the app about the subscription through the callback routine.
[in] | handle | handle to the MQTTClient instance |
[in] | topic | topic of the data to be published. It is NULL terminated. |
[in] | topicLen | topic length. |
[in] | msg | binary data to be published |
[in] | msgLen | length of the msg |
[in] | flags | QOS define MQTT_PUBLISH_QOS_0, MQTT_PUBLISH_QOS_1 or MQTT_PUBLISH_QOS_2 use MQTT_PUBLISH_RETAIN is message should be retained |
int16_t MQTTClient_subscribe | ( | MQTTClient_Handle | handle, |
MQTTClient_SubscribeParams * | value, | ||
uint8_t | numberOfTopics | ||
) |
Subscribe to a set of topics.
To receive data about a set of topics from the server, the app through this routine must subscribe to those topic names with the server. The caller can indicate whether the routine should block until a time, the message has been acknowledged by the server.
In case, the app has chosen not to await for the ACK from the server, the MQTT implementation will notify the app about the subscription through the callback routine.
[in] | handle | handle to the MQTTClient instance |
[in] | value | a pointer to a struct of subscribe parameters which hold: Topic name to subscribe. It is a pointer to NULL terminated strings. Qos value for the topic. persistent session flag in order to enable or disable persistent session. callback function which is optional - if NULL use the default callback |
[in] | numberOfTopics | number of such topics |
int16_t MQTTClient_unsubscribe | ( | MQTTClient_Handle | handle, |
MQTTClient_UnsubscribeParams * | value, | ||
uint8_t | numberOfTopics | ||
) |
Unsubscribe from a set of topics.
The app should use this service to stop receiving data for the named topics from the server.
[in] | handle | handle to the MQTTClient instance |
[in] | value | topics set of topics to be unsubscribed. It is an array of pointers to NULL terminated strings. |
[in] | numberOfTopics | count number of topics to be unsubscribed |
int16_t MQTTClient_set | ( | MQTTClient_Handle | handle, |
uint16_t | option, | ||
void * | value, | ||
uint16_t | valueLength | ||
) |
Set client parameters.
This function can set different parameters to the client. Will message params, user name and password, keep alive time and clean/persistent session.
[in] | handle | handle to the MQTTClient instance |
[in] | option | Define the actual option to set. Applicable values: |
[in] | value | Specifies a value for the option |
[in] | valueLength | Specifies the length of the value |
int16_t MQTTClient_get | ( | MQTTClient_Handle | handle, |
uint16_t | option, | ||
void * | value, | ||
uint16_t | valueLength | ||
) |
Get client parameters.
This function can get different parameters from the client. Will message params, user name and password, keep alive time and clean/persistent session.
[in] | handle | handle to the MQTTClient instance |
[in] | option | Define the actual option to set. Applicable values: |
[in] | value | Specifies a value for the option |
[in] | valueLength | Specifies the length of the value |