Functions

group mqtt_api_functions

C APIs provided by the MQTT library.

All library API functions except cy_mqtt_init and cy_mqtt_deinit are thread safe.

Typedefs

typedef void (*cy_mqtt_callback_t)(cy_mqtt_t mqtt_handle, cy_mqtt_event_t event, void *user_data)

MQTT event callback functions type used to process the disconnect event and incoming MQTT publish packets received from the MQTT broker.

note

MQTT library functions should not be invoked from this callback function.

Return

: void

Parameters
  • mqtt_handle: [in] : MQTT handle.

  • event: [in] : MQTT event information. For event values refer cy_mqtt_event_t .

  • user_data: [in] : Pointer to user data provided during cy_mqtt_create.

Functions

cy_rslt_t cy_mqtt_init(void)

Performs network sockets initialization required for the MQTT library.

It must be called once (and only once) before calling any other function in this library.

note

cy_mqtt_init and cy_mqtt_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

cy_rslt_t cy_mqtt_create(uint8_t *buffer, uint32_t buff_len, cy_awsport_ssl_credentials_t *security, cy_mqtt_broker_info_t *broker_info, cy_mqtt_callback_t event_callback, void *user_data, cy_mqtt_t *mqtt_handle)

Creates a MQTT instance and initializes its members based on the supplied arguments.

Initializes the core AWS MQTT library and its components. The handle to the MQTT instance is returned via the handle pointer supplied by the user on success. This handle is used for creating MQTT connection with MQTT broker. Same handle is used for MQTT Publish, Subscribe, and Unsubscribing from MQTT topic.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters
  • buffer: [in] : Network buffer for send and receive. Application needs to allocate memory for network buffer and should not be freed until MQTT object is deleted. The minimum buffer size is defined by CY_MQTT_MIN_NETWORK_BUFFER_SIZE. Please make sure the buffer allocated is larger than CY_MQTT_MIN_NETWORK_BUFFER_SIZE. This buffer is used for sending and receiving MQTT packets over the network. Hence, the buffer size should be sufficiently large enough to hold the MQTT packet header and payload. For example: To send/receive the MQTT payload of 4 kb, it’s recommended to allocate 4.5 kb or more buffer.

  • buff_len: [in] : Network buffer length in bytes.

  • security: [in] : Credentials for TLS connection. Application needs to allocate memory for keys, certs, and sni/user names should not be freed until MQTT object is deleted.

  • broker_info: [in] : MQTT broker information. Refer cy_mqtt_broker_info_t for details.

  • event_callback: [in] : Application callback function which needs to be called on arrival of MQTT incoming publish packets and network disconnection notification from network layer.

  • user_data: [in] : Pointer to user data to be passed in the event callback.

  • mqtt_handle: [out] : Pointer to store the MQTT handle allocated by this function on successful return.

cy_rslt_t cy_mqtt_connect(cy_mqtt_t mqtt_handle, cy_mqtt_connect_info_t *connect_info)

Connects to the given MQTT broker using a secured/non-secured TCP connection and establishes MQTT client session with the broker.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters

cy_rslt_t cy_mqtt_publish(cy_mqtt_t mqtt_handle, cy_mqtt_publish_info_t *pub_msg)

Publishes the MQTT message on given MQTT topic.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters

cy_rslt_t cy_mqtt_subscribe(cy_mqtt_t mqtt_handle, cy_mqtt_subscribe_info_t *sub_info, uint8_t sub_count)

Subscribes for MQTT message on the given MQTT topic or list of topics.

note

Single subscription request with multiple topics, this function returns success if at least one of the subscription is successful. If subscription fails for any of the topic in the list, the failure is indicated through 'allocated_qos' set to CY_MQTT_QOS_INVALID. Refer cy_mqtt_subscribe_info_t for more details. Upon return, the 'allocated_qos' indicate the QoS level allocated by the MQTT broker for the successfully subscribed topic.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters
  • mqtt_handle: [in] : MQTT handle created using cy_mqtt_create.

  • sub_info: [in, out] : Pointer to array of MQTT subscription information structure. Refer cy_mqtt_subscribe_info_t for details.

  • sub_count: [in] : Number of subscription topics in the subscription array.

cy_rslt_t cy_mqtt_unsubscribe(cy_mqtt_t mqtt_handle, cy_mqtt_unsubscribe_info_t *unsub_info, uint8_t unsub_count)

Unsubscribes from a given MQTT topic.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters
  • mqtt_handle: [in] : MQTT handle created using cy_mqtt_create.

  • unsub_info: [in] : Pointer to array of MQTT unsubscription information structure. Refer cy_mqtt_unsubscribe_info_t for details.

  • unsub_count: [in] : Number of unsubscription topics in the unsubscription array.

cy_rslt_t cy_mqtt_disconnect(cy_mqtt_t mqtt_handle)

Initiates MQTT client disconnection from connected MQTT broker.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters

cy_rslt_t cy_mqtt_delete(cy_mqtt_t mqtt_handle)

Deletes the given MQTT instance and frees the resources allocated for the instance by the cy_mqtt_create function.

Before calling this API function, MQTT connection with broker must be disconnected. And the MQTT handle should not be used after delete.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.

Parameters

cy_rslt_t cy_mqtt_deinit(void)

One-time deinitialization function for network sockets implementation.

It should be called after destroying all network socket connections.

note

cy_mqtt_init and cy_mqtt_deinit API functions are not thread-safe. The caller must ensure that these two API functions are not invoked simultaneously from different threads.

Return

cy_rslt_t : CY_RSLT_SUCCESS on success; error codes in Macros otherwise.