Functions#

This section provides a reference to the MQTT API functions.

Note

  • Stack overflows may occur when invoking functions or using your own variables or data structures while handling callbacks. Configure the stack size by modifying the pre-processor macro SL_SI91X_EVENT_HANDLER_STACK_SIZE as per your application's requirements. See here for the instructions in modifying a pre-processor macro.

  • Event/Callback handlers must not contain function calls or code which can block or delay the execution of the event/callback handler as it will cause all the other events to queue up and delay the execution of other events since all the events are invoked and handled from a single thread.

  • Do not call any synchronous SDK APIs from within the Event/Callback handlers.

Functions#

sl_status_t
sl_mqtt_client_init(sl_mqtt_client_t *client, sl_mqtt_client_event_handler_t event_handler)


Initialize the mqtt_client and registers the event_handler.

sl_status_t
sl_mqtt_client_deinit(sl_mqtt_client_t *client)

Deinitialize the MQTT client.

sl_status_t
sl_mqtt_client_connect(sl_mqtt_client_t *client, const sl_mqtt_broker_t *broker, const sl_mqtt_client_last_will_message_t *last_will_message, const sl_mqtt_client_configuration_t *configuration, uint32_t timeout)


Connect the client to MQTT broker.

sl_status_t
sl_mqtt_client_disconnect(sl_mqtt_client_t *client, uint32_t timeout)


Disconnect the client from MQTT broker.

sl_status_t
sl_mqtt_client_publish(sl_mqtt_client_t *client, const sl_mqtt_client_message_t *message, uint32_t timeout, void *context)

Publish a message.

sl_status_t
sl_mqtt_client_subscribe(sl_mqtt_client_t *client, const uint8_t *topic, uint16_t topic_length, sl_mqtt_qos_t qos_level, uint32_t timeout, sl_mqtt_client_message_received_t message_handler, void *context)

Indicate which client can subscribe to a topic.

sl_status_t
sl_mqtt_client_unsubscribe(sl_mqtt_client_t *client, const uint8_t *topic, uint16_t length, uint32_t timeout, void *context)


Indicate which client can unsubscribe a topic.

Function Documentation#

sl_mqtt_client_init#

sl_status_t sl_mqtt_client_init (sl_mqtt_client_t * client, sl_mqtt_client_event_handler_t event_handler)


Initialize the mqtt_client and registers the event_handler.

Parameters
[in]client


Valid pointer to the client structure of type sl_mqtt_client_t. This shall not be null.

[in]event_handler

Event handler of type sl_mqtt_client_event_handler_t which will be called for various events on client.

Returns


Definition at line 38 of file components/service/mqtt/inc/sl_mqtt_client.h

sl_mqtt_client_deinit#

sl_status_t sl_mqtt_client_deinit (sl_mqtt_client_t * client)

Deinitialize the MQTT client.

Parameters
[in]client

Valid pointer to the client structure of type sl_mqtt_client_t

Returns


Definition at line 51 of file components/service/mqtt/inc/sl_mqtt_client.h

sl_mqtt_client_connect#

sl_status_t sl_mqtt_client_connect (sl_mqtt_client_t * client, const sl_mqtt_broker_t * broker, const sl_mqtt_client_last_will_message_t * last_will_message, const sl_mqtt_client_configuration_t * configuration, uint32_t timeout)


Connect the client to MQTT broker.

Parameters
[in]client

sl_mqtt_client_t client which would be connected to the broker.

[in]broker

Broker configuration of type sl_mqtt_broker_t

[in]last_will_message

Last will message of the client of type sl_mqtt_client_last_will_message_t

[in]configuration

Client configuration of type sl_mqtt_client_configuration_t

[in]timeout

Timeout for the API. If the value is zero, the API will be asynchronous.

Returns

  • sl_status_t. If called asynchronously, SL_STATUS_IN_PROGRESS will be returned as status.

Note

  • In subsequent calls to connect, it is optional to provide broker, last_will_message, and configuration parameters.

  • If broker and configuration parameters are given null, then value given in the first connect() call would be retained.

  • In case of last_will_message parameter, values given in each connect() call would be considered. If value of last_will_message parameter is given as null, then no will message would be sent to the broker parameter.

  • Only is_clean_session, credential_id, client_id, client_id_length of sl_mqtt_client_configuration_t are considered. Topic length of last_will_message should be less than SI91X_MQTT_CLIENT_WILL_TOPIC_MAXIMUM_LENGTH. Client ID length should be less than SI91X_MQTT_CLIENT_CLIENT_ID_MAXIMUM_LENGTH. Username length should be less than SI91X_MQTT_CLIENT_USERNAME_MAXIMUM_LENGTH. Password length should be less than SI91X_MQTT_CLIENT_PASSWORD_MAXIMUM_LENGTH.


Definition at line 84 of file components/service/mqtt/inc/sl_mqtt_client.h

sl_mqtt_client_disconnect#

sl_status_t sl_mqtt_client_disconnect (sl_mqtt_client_t * client, uint32_t timeout)


Disconnect the client from MQTT broker.

Parameters
[in]client


sl_mqtt_client_t client which needs to be disconnected from the broker.

[in]timeout


Timeout for the API. If the value is zero, the API will be asynchronous.

Returns


  • sl_status_t. If called asynchronously, SL_STATUS_IN_PROGRESS will be returned as status.


Definition at line 103 of file components/service/mqtt/inc/sl_mqtt_client.h

sl_mqtt_client_publish#

sl_status_t sl_mqtt_client_publish (sl_mqtt_client_t * client, const sl_mqtt_client_message_t * message, uint32_t timeout, void * context)

Publish a message.

Parameters
[in]client


sl_mqtt_client_t client which requires to publish the message.

[in]message


sl_mqtt_client_message_t Message which needs to be published.

[in]timeout


Timeout for the API. If the value is zero, the API will be asynchronous.

[in]context


Context which would be returned in event handler if the API is called asynchronously. The caller must ensure that the lifecycle of context is retained until the callback is invoked. The deallocation of context is also the responsibility of the caller.

Returns


  • sl_status_t. If called asynchronously, SL_STATUS_IN_PROGRESS will be returned as status.

Note

  • The maximum length of the topic should be less than SI91X_MQTT_CLIENT_TOPIC_MAXIMUM_LENGTH.


Definition at line 124 of file components/service/mqtt/inc/sl_mqtt_client.h

sl_mqtt_client_subscribe#

sl_status_t sl_mqtt_client_subscribe (sl_mqtt_client_t * client, const uint8_t * topic, uint16_t topic_length, sl_mqtt_qos_t qos_level, uint32_t timeout, sl_mqtt_client_message_received_t message_handler, void * context)

Indicate which client can subscribe to a topic.

Parameters
[in]client


sl_mqtt_client_t client which needs to subscribe to the topic.

[in]topic

Topic of interest.

[in]topic_length


Length of the topic.

[in]qos_level


Quality of service of type sl_mqtt_qos_t using which client subscribes.

[in]timeout


Timeout for API. If the value is zero, the API will be asynchronous.

[in]message_handler


sl_mqtt_client_message_received_t message handler which invokes for messages published on the topic.

[in]context

Context that is sent back to the message handler. The caller must ensure that the lifecycle of the context is retained until the callback is invoked. The deallocation of context is also the responsibility of the caller.

Returns


  • sl_status_t. If called asynchronously, SL_STATUS_IN_PROGRESS will be returned as status.

Note

  • The maximum length of the topic should be less than SI91X_MQTT_CLIENT_TOPIC_MAXIMUM_LENGTH.


Definition at line 154 of file components/service/mqtt/inc/sl_mqtt_client.h

sl_mqtt_client_unsubscribe#

sl_status_t sl_mqtt_client_unsubscribe (sl_mqtt_client_t * client, const uint8_t * topic, uint16_t length, uint32_t timeout, void * context)


Indicate which client can unsubscribe a topic.

Parameters
[in]client


sl_mqtt_client_t client that unsubscribes the topic.

[in]topic


Topic from which client needs to unsubscribe.

[in]length


Length of the topic.

[in]timeout


Timeout for the API. If the value is zero, the API will be asynchronous.

[in]context


Context that returns in event handler if the API is called asynchronously. The caller must ensure that the lifecycle of the context is retained until the callback is invoked. The deallocation of context is also the responsibility of the caller.

Returns


  • sl_status_t. If called asynchronously, SL_STATUS_IN_PROGRESS will be returned as status.

Note

  • The maximum length of the topic should be less than SI91X_MQTT_CLIENT_TOPIC_MAXIMUM_LENGTH


Definition at line 183 of file components/service/mqtt/inc/sl_mqtt_client.h