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#
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#
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#
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#
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 completionMQTTc_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 disconnectionMQTTc_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#
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.