MQTT-client Objects

µC/MQTT-client offers many structures that the application can use to create objects to interact with the µC/MQTT-client stack.

All the MQTT-client objects required by the application must be allocated by the application and passed to the µC/MQTT-client stack.

All objects or strings passed to the µC/MQTT-client stack MUST stay valid and unmodified for the duration of the MQTT message for message-oriented parameters and objects; or until the MQTT connection is closed for Connection-oriented parameters and objects.

MQTT-client Connection (MQTTc_CONN)

This structure is the main one used by µC/MQTT-client. It contains all parameters relative to an MQTT connection (server port number, server address, server host name, etc.) and also many internal parameters for the MQTT connection and MQTT message processing.

Each configurable parameter SHOULD be set up with the function MQTTc_ConnSetParam(). The list of available parameters for a connection can be viewed here.

The members of an MQTT-client Connection object should never be directly tampered with at any time.

Listing - MQTTc_CONN Structure
struct  mqttc_conn {
    NET_SOCK_ID                 SockId;                         /* Connection's socket ID.                              */
    CPU_INT08U                  SockSelFlags;                   /* Flags to identify which oper must be checked in Sel. */
    CPU_CHAR                   *BrokerIP_Addr;                  /* MQTT broker's IP addr.                               */
    CPU_CHAR                   *BrokerNamePtr;                  /* MQTT broker's name.                                  */
    CPU_INT16U                  BrokerPortNbr;                  /* MQTT broker's port nbr.                              */
    CPU_INT16U                  InactivityTimeout_s;            /* Inactivity timeout, in seconds.                      */
    CPU_CHAR                   *ClientID_Str;                   /* Client ID str.                                       */
    CPU_CHAR                   *UsernameStr;                    /* Username str.                                        */
    CPU_CHAR                   *PasswordStr;                    /* Password str.                                        */
    CPU_INT16U                  KeepAliveTimerSec;              /* Keep alive timer duration, in seconds.               */
    MQTTc_WILL_CFG             *WillCfgPtr;                     /* Ptr to will cfg, if any.                             */
    NET_APP_SOCK_SECURE_CFG    *SecureCfgPtr;                   /* Ptr to secure will cfg, if any.                      */
                                                                /* -------------------- CALLBACKS --------------------- */
    MQTTc_CMPL_CALLBACK         OnCmpl;                         /* Generic, on cmpl callback.                           */
    MQTTc_CMPL_CALLBACK         OnConnectCmpl;                  /* On connect cmpl callback.                            */
    MQTTc_CMPL_CALLBACK         OnPublishCmpl;                  /* On publish cmpl callback.                            */
    MQTTc_CMPL_CALLBACK         OnSubscribeCmpl;                /* On subscribe cmpl callback.                          */
    MQTTc_CMPL_CALLBACK         OnUnsubscribeCmpl;              /* On unsubscribe cmpl callback.                        */
    MQTTc_CMPL_CALLBACK         OnPingReqCmpl;                  /* On ping req cmpl callback.                           */
    MQTTc_CMPL_CALLBACK         OnDisconnectCmpl;               /* On disconnect cmpl callback.                         */
    MQTTc_PUBLISH_RX_CALLBACK   OnPublishRx;                    /* On publish rx'd cmpl callback.                       */
    void                       *ArgPtr;                         /* Ptr to arg that will be provided to callbacks.       */
    CPU_INT32U                  TimeoutMs;                      /* Timeout for 'Open' operation, in milliseconds.       */
                                                                /* ----------------- NEXT MSG VALUES ------------------ */
    CPU_INT08U                  NextMsgHeader;                  /* Header of next msg to parse.                         */
    CPU_INT32U                  NextMsgRxLen;                   /* Rx len of next msg.                                  */
    MQTTc_MSG_TYPE              NextMsgType;                    /* Next msg's type.                                     */
    CPU_INT32U                  NextMsgLen;                     /* Len remaining to rx for next msg.                    */
    CPU_BOOLEAN                 NextMsgLenIsCmpl;               /* Flag indicating if next msg's len value is rx'd.     */
    CPU_INT16U                  NextMsgMsgID;                   /* ID of next msg, if any.                              */
    CPU_BOOLEAN                 NextMsgMsgID_IsCmpl;            /* Flag indicating if next msg's ID has been rx'd.      */
    MQTTc_MSG                  *NextMsgPtr;                     /* Ptr to next msg, if known.                           */
    MQTTc_MSG                  *PublishRxMsgPtr;                /* Ptr to msg that is used to rx publish from server.   */
    MQTTc_MSG                  *TxMsgHeadPtr;                   /* Ptr to head of msg needing to tx or waiting reply.   */
    CPU_INT32U                  NextTxMsgTxLen;                 /* Len of already xfer'd data.                          */
    MQTTc_CONN                 *NextPtr;                        /* Ptr to next conn.                                    */
};

MQTT-client Message (MQTTc_MSG)

This structure regroups parameters and flags related to the configuration of an MQTT message.

Each configurable parameter SHOULD be set up with the function MQTTc_MsgSetParam(). The list of available parameters for a connection can be viewed here.

The members of an MQTT-client Message object should never be directly tempered with at any time.

Listing - MQTTc_MSG Structure
struct  mqttc_msg {
    MQTTc_CONN       *ConnPtr;                                  /* Ptr to MQTTc_CONN associated.                        */
    MQTTc_MSG_TYPE    Type;                                     /* Msg's type.                                          */
    MQTTc_MSG_STATE   State;                                    /* Msg's state.                                         */
    CPU_INT08U        QoS;                                      /* Msg's QoS.                                           */
    CPU_INT16U        MsgID;                                    /* Msg ID used by msg.                                  */
    CPU_INT08U       *BufPtr;                                   /* Ptr to rx/tx buf.                                    */
    CPU_INT32U        BufLen;                                   /* Avail buf len for msg.                               */
    CPU_INT32U        XferLen;                                  /* Len of xfer.                                         */
    MQTTc_ERR         Err;                                      /* Err associated to processing of msg.                 */
    MQTTc_MSG        *NextPtr;                                  /* Ptr to next msg.                                     */
};