MQTT Client API#

MQTTc_ConfigureTaskStk()#

Description#

Configure the MQTT client task stack properties to use the parameters contained in the passed structure instead of the default parameters.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  HTTPc_ConfigureTaskStk (CPU_STK_SIZE   stk_size_elements,
                              void          *p_stk_base)

Arguments#

stk_size_elements

Size of the stack, in CPU_STK elements.

p_stk_base

Pointer to base of the stack.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before MQTTc_Init(). If it is not called, default values will be used to initialize the module.

MQTTc_ConfigureMemSeg()#

Description#

Configure the memory segment that will be used to allocate internal data needed by MQTT client module instead of the default memory segment.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to the memory segment from which the internal data will be allocated. If DEF_NULL, the internal data will be allocated from the global Heap.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before MQTTc_Init(). If it is not called, default values will be used to initialize the module.

MQTTc_ConfigureQty()#

Description#

Overwrite the quantity configuration object for MQTT client.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_ConfigureQty (MQTTc_QTY_CFG  *p_qty_cfg)

Arguments#

p_qty_cfg

Pointer to structure containing the quantity parameters.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional. If it is called, it must be called before MQTTc_Init(). If it is not called, default values will be used to initialize the module.

MQTTc_Init()#

Description#

Initializes the MQTT client module.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_Init (const  MQTTc_CFG      *p_cfg,
                  const  RTOS_TASK_CFG  *p_task_cfg,
                         MEM_SEG        *p_mem_seg,
                         RTOS_ERR       *p_err)

Arguments#

p_cfg

Pointer to MQTT Client Configuration Object.

p_task_cfg

Pointer to task configuration structure.

p_mem_seg

Memory segment from which internal data will be allocated. If DEF_NULL, it will be allocated from the global heap.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_TaskPrioSet()#

Description#

Sets priority of the MQTT client task.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void MQTTc_TaskPrioSet (RTOS_TASK_PRIO   prio,
                        RTOS_ERR        *p_err)

Arguments#

prio

New priority for the MQTT client task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_TaskDlySet()#

Description#

Sets task delay.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void MQTTc_TaskDlySet (CPU_INT08U   dly_ms,
                       RTOS_ERR    *p_err)

Arguments#

dly_ms

New delay in millisecond for the MQTT client task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_InactivityTimeoutDfltSet()#

Description#

Sets default inactivity timeout in second of the MQTT client connection.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void MQTTc_InactivityTimeoutDfltSet (CPU_INT16U   inactivity_timeout_s,
                                     RTOS_ERR    *p_err)

Arguments#

inactivity_timeout_s

New default timeout in second to set on new MQTT connection.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function.

Returned Value#

None.

Notes / Warnings#

  1. It is possible to set each connection with a different inactivity timeout by calling MQTTc_ConnSetParam() before opening the connection.

MQTTc_ConnSetParam()#

Description#

Sets parameters related to the TCP and MQTT Client Connection.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_ConnSetParam (MQTTc_CONN        *p_conn,
                          MQTTc_PARAM_TYPE   type,
                          void              *p_param,
                          RTOS_ERR          *p_err)

Arguments#

p_conn

Pointer to the current MQTTc Connection.

type

Parameter type :

  • MQTTc_PARAM_TYPE_BROKER_IP_ADDR Broker's IP address.

  • MQTTc_PARAM_TYPE_BROKER_NAME Broker's name.

  • MQTTc_PARAM_TYPE_BROKER_PORT_NBR Broker's port number.

  • MQTTc_PARAM_TYPE_INACTIVITY_TIMEOUT_S Inactivity timeout (in seconds).

  • MQTTc_PARAM_TYPE_CLIENT_ID_STR Client ID string.

  • MQTTc_PARAM_TYPE_USERNAME_STR Client username string.

  • MQTTc_PARAM_TYPE_PASSWORD_STR Client password string.

  • MQTTc_PARAM_TYPE_KEEP_ALIVE_TMR_SEC Keep alive timer (in seconds).

  • MQTTc_PARAM_TYPE_WILL_CFG_PTR Configures a pointer, if any.

  • MQTTc_PARAM_TYPE_CALLBACK_ON_COMPL Generic callback on completion

  • MQTTc_PARAM_TYPE_CALLBACK_ON_CONNECT_CMPL Callback on connection completion.

  • MQTTc_PARAM_TYPE_CALLBACK_ON_PUBLISH_CMPL Callback on publish completion.

  • MQTTc_PARAM_TYPE_CALLBACK_ON_SUBSCRIBE_CMPL Callback on subscribe completion.

  • MQTTc_PARAM_TYPE_CALLBACK_ON_UNSUBSCRIBE_CMPL Callback on unsubscribe completion.

  • MQTTc_PARAM_TYPE_CALLBACK_ON_PINGREQ_CMPL Callback on ping request completion.

  • MQTTc_PARAM_TYPE_CALLBACK_ON_DISCONNECT_CMPL Callback on disconnection

  • MQTTc_PARAM_TYPE_CALLBACK_ON_PUBLISH_RX Callback once publish is received.

  • MQTTc_PARAM_TYPE_CALLBACK_ARG_PTR Pointer on an argument passed to callback.

  • MQTTc_PARAM_TYPE_TIMEOUT_MS 'Open' timeout (in milliseconds).

  • MQTTc_PARAM_TYPE_PUBLISH_RX_MSG_PTR Pointer on the message that is used to receive the publish.

p_param

Parameter's value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_ConnClose()#

Description#

Requests to close a MQTT client Connection.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_ConnClose (MQTTc_CONN   *p_conn,
                       MQTTc_FLAGS   flags,
                       RTOS_ERR     *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection to close.

flags

Configuration flags, reserved for future usage.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_ConnClr()#

Description#

Clears an MQTT client Connection before its first usage.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_ConnClr (MQTTc_CONN  *p_conn,
                     RTOS_ERR    *p_err)

Arguments#

p_conn

Pointer to the MQTTc Connection.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. This function MUST be called before the MQTTc_CONN object is used for the first time.

MQTTc_Connect()#

Description#

Sends a 'Connect' message to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_Connect (MQTTc_CONN  *p_conn,
                     MQTTc_MSG   *p_msg,
                     RTOS_ERR    *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection to use.

p_msg

Pointer to the MQTT client Message object to use.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_ConnOpen()#

Description#

Opens a new MQTT Client connection.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_ConnOpen (MQTTc_CONN     *p_conn,
                      MQTTc_FLAGS     flags,
                      RTOS_ERR       *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to open.

flags

Configuration flags, reserved for future usage.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_TYPE

  • RTOS_ERR_BLK_ALLOC_CALLBACK

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_NOT_SUPPORTED

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_NET_INVALID_ADDR_SRC

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_NET_IF_LINK_DOWN

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

  • RTOS_ERR_NET_OP_IN_PROGRESS

  • RTOS_ERR_TX

  • RTOS_ERR_ALREADY_EXISTS

  • RTOS_ERR_NOT_FOUND

  • RTOS_ERR_NET_INVALID_CONN

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_NET_ADDR_UNRESOLVED

  • RTOS_ERR_NET_NEXT_HOP

  • RTOS_ERR_NET_CONN_CLOSED_FAULT

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_Disconnect()#

Description#

Sends a 'Disconnect' message to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_Disconnect (MQTTc_CONN  *p_conn,
                        MQTTc_MSG   *p_msg,
                        RTOS_ERR    *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_MsgClr()#

Description#

Clears the Message object members.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_MsgClr (MQTTc_MSG  *p_msg,
                    RTOS_ERR   *p_err)

Arguments#

p_msg

Pointer to the message object to clear.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_MsgSetParam()#

Description#

Sets the parameter related to a given MQTT Message.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_MsgSetParam (MQTTc_MSG         *p_msg,
                         MQTTc_PARAM_TYPE   type,
                         void              *p_param,
                         RTOS_ERR          *p_err)

Arguments#

p_msg

Pointer to a message object.

type

Parameter type :

  • MQTTc_PARAM_TYPE_MSG_BUF_PTR Msg's buf ptr.

  • MQTTc_PARAM_TYPE_MSG_BUF_LEN Msg's buf len.

p_param

Parameter's value.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_PingReq()#

Description#

Sends a 'PingReq' message to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_PingReq (MQTTc_CONN  *p_conn,
                     MQTTc_MSG   *p_msg,
                     RTOS_ERR    *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_Publish()#

Description#

Sends a 'Publish' message to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_Publish (       MQTTc_CONN    *p_conn,
                            MQTTc_MSG     *p_msg,
                     const  CPU_CHAR      *topic_str,
                            CPU_INT08U     qos_lvl,
                            CPU_BOOLEAN    retain_flag,
                     const  CPU_INT08U    *p_payload,
                            CPU_INT32U     payload_len,
                            RTOS_ERR      *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

topic_str

String containing the topic on which to publish. Must stay valid until the message has been completely sent.

qos_lvl

Level of QoS at which to publish.

retain_flag

Flag that indicates if the retain flag in the PUBLISH header needs to be set.

p_payload

Pointer to the payload to publish. Must stay valid until the message has been completely sent.

payload_len

Length, in bytes, of the payload.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_Subscribe()#

Description#

Sends a 'Subscribe' message to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_Subscribe (       MQTTc_CONN  *p_conn,
                              MQTTc_MSG   *p_msg,
                       const  CPU_CHAR    *topic_str,
                              CPU_INT08U   req_qos,
                              RTOS_ERR    *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

topic_str

String containing the topic at which to subscribe. Must stay valid until the message has been completely sent.

req_qos

Requested level of QoS for this subscription.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_SubscribeMult()#

Description#

Sends a 'Subscribe' message containing multiple topics to MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_SubscribeMult (       MQTTc_CONN   *p_conn,
                                  MQTTc_MSG    *p_msg,
                           const  CPU_CHAR    **topic_str_tbl,
                                  CPU_INT08U   *req_qos_tbl,
                                  CPU_INT08U    topic_nbr,
                                  RTOS_ERR     *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

topic_str_tbl

Table containing string of all the topic(s) at which to subscribe. Must all stay valid until the message has been completely sent.

req_qos_tbl

Table of the requested level of QoS for each subscription.

topic_nbr

Number of topics and QoS' contained in tables.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_Unsubscribe()#

Description#

Sends an 'Unsubscribe' message to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_Unsubscribe (       MQTTc_CONN  *p_conn,
                                MQTTc_MSG   *p_msg,
                         const  CPU_CHAR    *topic_str,
                                RTOS_ERR    *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

topic_str

String containing the topic at which to unsubscribe. Must stay valid until the message has been completely sent.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.

MQTTc_UnsubscribeMult()#

Description#

Sends an 'Unsubscribe' message for multiple topics to the MQTT server.

Files#

mqtt_client.h/mqtt_client.c

Prototype#

void  MQTTc_UnsubscribeMult (       MQTTc_CONN   *p_conn,
                                    MQTTc_MSG    *p_msg,
                             const  CPU_CHAR    **topic_str_tbl,
                                    CPU_INT08U    topic_nbr,
                                    RTOS_ERR     *p_err)

Arguments#

p_conn

Pointer to the MQTT client Connection object to use.

p_msg

Pointer to the MQTT client Message object to use.

topic_str_tbl

Table containing string of all the topic(s) at which to unsubscribe. Must stay valid until the message has been completely sent.

topic_nbr

Number of topic contained in tables.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_INVALID_HANDLE

Returned Value#

None.

Notes / Warnings#

None.