Functions of MQTT-SN client library. More...

Functions
CC_MqttsnClientHandle	cc_mqttsn_client_new ()
	Allocate new client. More...

void	cc_mqttsn_client_free (CC_MqttsnClientHandle client)
	Free previously allocated client. More...

void	cc_mqttsn_client_set_next_tick_program_callback (CC_MqttsnClientHandle client, CC_MqttsnNextTickProgramFn fn, void *data)
	Set callback to call when time measurement is required. More...

void	cc_mqttsn_client_set_cancel_next_tick_wait_callback (CC_MqttsnClientHandle client, CC_MqttsnCancelNextTickWaitFn fn, void *data)
	Set callback to terminate current time measurement. More...

void	cc_mqttsn_client_set_send_output_data_callback (CC_MqttsnClientHandle client, CC_MqttsnSendOutputDataFn fn, void *data)
	Set callback to send raw data over I/O link. More...

void	cc_mqttsn_client_set_gw_status_report_callback (CC_MqttsnClientHandle client, CC_MqttsnGwStatusReportFn fn, void *data)
	Set callback to report status of the gateway. More...

void	cc_mqttsn_client_set_gw_disconnect_report_callback (CC_MqttsnClientHandle client, CC_MqttsnGwDisconnectReportFn fn, void *data)
	Set callback to report unsolicited disconnection of the gateway. More...

void	cc_mqttsn_client_set_message_report_callback (CC_MqttsnClientHandle client, CC_MqttsnMessageReportFn fn, void *data)
	Set callback to report incoming messages. More...

CC_MqttsnErrorCode	cc_mqttsn_client_start (CC_MqttsnClientHandle client)
	Start the library's operation. More...

CC_MqttsnErrorCode	cc_mqttsn_client_stop (CC_MqttsnClientHandle client)
	Stop the library's operation. More...

unsigned	cc_mqttsn_client_process_data (CC_MqttsnClientHandle client, const unsigned char *buf, unsigned bufLen)
	Provide data, received over I/O link, to the library for processing. More...

void	cc_mqttsn_client_tick (CC_MqttsnClientHandle client)
	Notify client about requested time expiry. More...

void	cc_mqttsn_client_set_retry_period (CC_MqttsnClientHandle client, unsigned value)
	Set retry period to wait between resending unacknowledged message to the gateway. More...

void	cc_mqttsn_client_set_retry_count (CC_MqttsnClientHandle client, unsigned value)
	Set number of retry attempts to perform before reporting unsuccessful result of the operation. More...

void	cc_mqttsn_client_set_broadcast_radius (CC_MqttsnClientHandle client, unsigned char value)
	Set broadcast radius. More...

void	cc_mqttsn_client_set_searchgw_enabled (CC_MqttsnClientHandle client, bool value)
	Enable/Disable search for gateways. More...

void	cc_mqttsn_client_search_gw (CC_MqttsnClientHandle client)
	Send SEARCHGW message. More...

void	cc_mqttsn_client_discard_gw (CC_MqttsnClientHandle client, unsigned char gwId)
	Discard information about the gateway. More...

void	cc_mqttsn_client_discard_all_gw (CC_MqttsnClientHandle client)
	Discard information about all gateways. More...

bool	cc_mqttsn_client_cancel (CC_MqttsnClientHandle client)
	Cancel current asynchronous operation. More...

CC_MqttsnErrorCode	cc_mqttsn_client_connect (CC_MqttsnClientHandle client, const char clientId, unsigned short keepAliveSeconds, bool cleanSession, const CC_MqttsnWillInfo willInfo, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Issue the connect request to the gateway. More...

CC_MqttsnErrorCode	cc_mqttsn_client_reconnect (CC_MqttsnClientHandle client, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Reconnect to the gateway using previously used client ID and keep alive period. More...

CC_MqttsnErrorCode	cc_mqttsn_client_disconnect (CC_MqttsnClientHandle client, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Disconnect from the gateway. More...

CC_MqttsnErrorCode	cc_mqttsn_client_publish_id (CC_MqttsnClientHandle client, CC_MqttsnTopicId topicId, const unsigned char msg, unsigned msgLen, CC_MqttsnQoS qos, bool retain, CC_MqttsnAsyncOpCompleteReportFn callback, void data)
	Publish message with predefined topic ID. More...

CC_MqttsnErrorCode	cc_mqttsn_client_publish (CC_MqttsnClientHandle client, const char topic, const unsigned char msg, unsigned msgLen, CC_MqttsnQoS qos, bool retain, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Publish message with topic string. More...

CC_MqttsnErrorCode	cc_mqttsn_client_subscribe_id (CC_MqttsnClientHandle client, CC_MqttsnTopicId topicId, CC_MqttsnQoS qos, CC_MqttsnSubscribeCompleteReportFn callback, void *data)
	Subscribe to topic having predefined topic ID. More...

CC_MqttsnErrorCode	cc_mqttsn_client_subscribe (CC_MqttsnClientHandle client, const char topic, CC_MqttsnQoS qos, CC_MqttsnSubscribeCompleteReportFn callback, void data)
	Subscribe to topic. More...

CC_MqttsnErrorCode	cc_mqttsn_client_unsubscribe_id (CC_MqttsnClientHandle client, CC_MqttsnTopicId topicId, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Unsubscribe from messages having predefined topic ID. More...

CC_MqttsnErrorCode	cc_mqttsn_client_unsubscribe (CC_MqttsnClientHandle client, const char topic, CC_MqttsnAsyncOpCompleteReportFn callback, void data)
	Unsubscribe from messages having specified topic. More...

CC_MqttsnErrorCode	cc_mqttsn_client_will_update (CC_MqttsnClientHandle client, const CC_MqttsnWillInfo willInfo, CC_MqttsnAsyncOpCompleteReportFn callback, void data)
	Update will recorded with the gateway/broker. More...

CC_MqttsnErrorCode	cc_mqttsn_client_will_topic_update (CC_MqttsnClientHandle client, const char topic, CC_MqttsnQoS qos, bool retain, CC_MqttsnAsyncOpCompleteReportFn callback, void data)
	Update topic of the will recorded with the gateway/broker. More...

CC_MqttsnErrorCode	cc_mqttsn_client_will_msg_update (CC_MqttsnClientHandle client, const unsigned char msg, unsigned msgLen, CC_MqttsnAsyncOpCompleteReportFn callback, void data)
	Update will message body recorded with the gateway/broker. More...

CC_MqttsnErrorCode	cc_mqttsn_client_sleep (CC_MqttsnClientHandle client, unsigned short duration, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Notify gateway about entering the sleep state. More...

CC_MqttsnErrorCode	cc_mqttsn_client_check_messages (CC_MqttsnClientHandle client, CC_MqttsnAsyncOpCompleteReportFn callback, void *data)
	Check for accumulated pending messages the gateway has to report. More...

Detailed Description

Functions of MQTT-SN client library.

Function Documentation

◆ cc_mqttsn_client_cancel()

bool cc_mqttsn_client_cancel ( CC_MqttsnClientHandle client )

Cancel current asynchronous operation.

The library provides support for multiple asynchronous operations, which report their completion via provided callback. The library also doesn't support start of the new operation before previous one completed. This function provides an ability to cancel existing operation to allow issue of the new request. When successfully cancelled the callback of the asyncrhonous operation will report CC_MqttsnAsyncOpStatus_Aborted as operation result status.

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

Returns: true in case an asynchronous operation was cancelled, false otherwise.

◆ cc_mqttsn_client_check_messages()

CC_MqttsnErrorCode cc_mqttsn_client_check_messages	(	CC_MqttsnClientHandle	client,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Check for accumulated pending messages the gateway has to report.

Can be invoked after successful entering the sleep state using cc_mqttsn_client_sleep(). According to MQTT-SN protocol specification, this function will force sending PINGREQ message to the gateway. The gateway then will deliver all the pending messages, which may cause multiple invocation of message report callback (set with cc_mqttsn_client_set_message_report_callback()). After gateway reports all accumulated messages, it will send PINGRESP message, which will case invocation of the provided callback. After the callback is invoked, the client may return to "asleep" state and will be required to check messages again or wake up after number of seconds provided in cc_mqttsn_client_sleep() call.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_connect()

CC_MqttsnErrorCode cc_mqttsn_client_connect	(	CC_MqttsnClientHandle	client,
		const char *	clientId,
		unsigned short	keepAliveSeconds,
		bool	cleanSession,
		const CC_MqttsnWillInfo *	willInfo,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Issue the connect request to the gateway.

This function needs to be called to connect to the gateway. When the operation is complete, the provided callback will be invoked. Note, that the function cannot be successfully called when client is already connected to the gateway. In order to change the will information use cc_mqttsn_client_will_update() function. If some other operation timed out, use cc_mqttsn_client_reconnect() to refresh the connection. In order to change client ID and/or "keep alive" value disconnect first (using cc_mqttsn_client_disconnect()) and then try to connect again.

IMPORTANT : The buffers containing client ID string, as well as will topic and message (if such exist) must be preserved intact until the connect operation is complete (provided callback is invoked). The CC_MqttsnWillInfo structure passed as willInfo parameter may reside on the stack and be destructed immediately after this function returns, but the buffers its data members point to must be preserved.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	clientId	Client ID string.
[in]	keepAliveSeconds	Maximum number of seconds allowed between the messages sent to the gateway. If no publish is performed during this timeframe, the library will generate PINGREQ message and send to the gateway.
[in]	cleanSession	Request to establish clean session.
[in]	willInfo	Requested will information, can be NULL.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_discard_all_gw()

void cc_mqttsn_client_discard_all_gw ( CC_MqttsnClientHandle client )

Discard information about all gateways.

The client library maintains the list of gateways that either advertised their presence or replied to previously sent SEARCHGW messages. This function causes the callback, set using cc_mqttsn_client_set_gw_status_report_callback() function, to be invoked reporting CC_MqttsnGwStatus_Discarded as status value for all the recorded gateways.

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

◆ cc_mqttsn_client_discard_gw()

void cc_mqttsn_client_discard_gw	(	CC_MqttsnClientHandle	client,
		unsigned char	gwId
	)

Discard information about the gateway.

The client library maintains the list of gateways that either advertised their presence or replied to previously sent SEARCHGW messages. This function causes information about specified gateway to be dropped. If such information exists, the callback, set using cc_mqttsn_client_set_gw_status_report_callback() function, will be invoked reporting CC_MqttsnGwStatus_Discarded as status value.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	gwId	ID of the gateway.

◆ cc_mqttsn_client_disconnect()

CC_MqttsnErrorCode cc_mqttsn_client_disconnect	(	CC_MqttsnClientHandle	client,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Disconnect from the gateway.

When the operation is complete, the provided callback will be invoked. Regardless of the reported disconnect result, the library assumes "disconnected" internal state and some functions, such as requests to publish and/or subscribe may not work.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_free()

void cc_mqttsn_client_free ( CC_MqttsnClientHandle client )

Free previously allocated client.

When used communication channel to the gateway is no longer needed, the client data structes allocated with cc_mqttsn_client_new() must be released using this function.

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

◆ cc_mqttsn_client_new()

CC_MqttsnClientHandle cc_mqttsn_client_new ( )

Allocate new client.

When work with the client is complete, cc_mqttsn_client_free() function must be invoked.

Returns: Handle to allocated client object. This handle needs to be passed as first parameter to all other API functions.

◆ cc_mqttsn_client_process_data()

unsigned cc_mqttsn_client_process_data	(	CC_MqttsnClientHandle	client,
		const unsigned char *	buf,
		unsigned	bufLen
	)

Provide data, received over I/O link, to the library for processing.

This call may cause invocation of some callbacks, such as request to cancel the currently running time measurement, send some messages to the gateway, report incoming application message, and (re)start time measurement.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	buf	Pointer to the buffer of data to process.
[in]	bufLen	Number of bytes in the data buffer.

Returns: Number of processed bytes.

Note: The function returns number of bytes that were actually consumed, and can be removed from the holding buffer.

◆ cc_mqttsn_client_publish()

CC_MqttsnErrorCode cc_mqttsn_client_publish	(	CC_MqttsnClientHandle	client,
		const char *	topic,
		const unsigned char *	msg,
		unsigned	msgLen,
		CC_MqttsnQoS	qos,
		bool	retain,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Publish message with topic string.

When publish operation is complete, the provided callback will be invoked. Note, that the callback MAY be invoked immediately for publish operation with QoS=0 if requested topic is already registered.

IMPORTANT : The buffer containing message data must be preserved intact until the end of the operation (provided callback is invoked).

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topic	Topic string.
[in]	msg	Pointer to buffer containing data to be published.
[in]	msgLen	Size of the buffer containing data to be published.
[in]	qos	Quality of service level.
[in]	retain	Retain flag.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_publish_id()

CC_MqttsnErrorCode cc_mqttsn_client_publish_id	(	CC_MqttsnClientHandle	client,
		CC_MqttsnTopicId	topicId,
		const unsigned char *	msg,
		unsigned	msgLen,
		CC_MqttsnQoS	qos,
		bool	retain,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Publish message with predefined topic ID.

When publish operation is complete, the provided callback will be invoked. Note, that the callback will be invoked immediately for publish operation with QoS=-1 or QoS=0.

IMPORTANT : The buffer containing message data must be preserved intact until the end of the operation (provided callback is invoked).

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topicId	Predefined topic ID.
[in]	msg	Pointer to buffer containing data to be published.
[in]	msgLen	Size of the buffer containing data to be published.
[in]	qos	Quality of service level.
[in]	retain	Retain flag.
[in]	callback	Callback to be invoked when operation is complete. It can be NULL for publish requests with QoS=-1 or QoS=0. Such publish requests do not require acknowledgement from the gateway and report their completion immediatelly.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_reconnect()

CC_MqttsnErrorCode cc_mqttsn_client_reconnect	(	CC_MqttsnClientHandle	client,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Reconnect to the gateway using previously used client ID and keep alive period.

The invocation will work only when in "connected" or "asleep" state, It will not work after invocation of cc_mqttsn_client_disconnect(). When the operation is complete, the provided callback will be invoked. If successful completion is reported, the client is properly connected to the gateway again.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_search_gw()

void cc_mqttsn_client_search_gw ( CC_MqttsnClientHandle client )

Send SEARCHGW message.

This function performs one send of SEARCHGW message regardless of whether the search for gateways is enabled or disabled.

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

◆ cc_mqttsn_client_set_broadcast_radius()

void cc_mqttsn_client_set_broadcast_radius	(	CC_MqttsnClientHandle	client,
		unsigned char	value
	)

Set broadcast radius.

When searching for gateways, the client library broadcasts SEARCHGW messages. It contains the broadcast radius value. This value can be set using this function. Default radius value is 0.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	value	Broadcast radius.

◆ cc_mqttsn_client_set_cancel_next_tick_wait_callback()

void cc_mqttsn_client_set_cancel_next_tick_wait_callback	(	CC_MqttsnClientHandle	client,
		CC_MqttsnCancelNextTickWaitFn	fn,
		void *	data
	)

Set callback to terminate current time measurement.

The client may request termination of currently running time measurement, previously requested via callback, which was set using cc_mqttsn_client_set_next_tick_program_callback() function. This function sets appropriate callback. When invoked, it must returne number of elapsed milliseconds since previoius time measurement request.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	fn	Callback function.
[in]	data	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

◆ cc_mqttsn_client_set_gw_disconnect_report_callback()

void cc_mqttsn_client_set_gw_disconnect_report_callback	(	CC_MqttsnClientHandle	client,
		CC_MqttsnGwDisconnectReportFn	fn,
		void *	data
	)

Set callback to report unsolicited disconnection of the gateway.

The callback will be invoked when gateway sends unsolicited DISCONNECT message or does not reply to PINGREQ message.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	fn	Callback function.
[in]	data	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

◆ cc_mqttsn_client_set_gw_status_report_callback()

void cc_mqttsn_client_set_gw_status_report_callback	(	CC_MqttsnClientHandle	client,
		CC_MqttsnGwStatusReportFn	fn,
		void *	data
	)

Set callback to report status of the gateway.

The callback is invoked when gateway status has changed.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	fn	Callback function.
[in]	data	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

◆ cc_mqttsn_client_set_message_report_callback()

void cc_mqttsn_client_set_message_report_callback	(	CC_MqttsnClientHandle	client,
		CC_MqttsnMessageReportFn	fn,
		void *	data
	)

Set callback to report incoming messages.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	fn	Callback function.
[in]	data	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

◆ cc_mqttsn_client_set_next_tick_program_callback()

void cc_mqttsn_client_set_next_tick_program_callback	(	CC_MqttsnClientHandle	client,
		CC_MqttsnNextTickProgramFn	fn,
		void *	data
	)

Set callback to call when time measurement is required.

The MQTT-SN client may require to measure time. When such measurement is required, the provided callback will be invoked with the timeout duration in milliseconds. After requested time expires, the cc_mqttsn_client_tick() function must be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	fn	Callback function.
[in]	data	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

◆ cc_mqttsn_client_set_retry_count()

void cc_mqttsn_client_set_retry_count	(	CC_MqttsnClientHandle	client,
		unsigned	value
	)

Set number of retry attempts to perform before reporting unsuccessful result of the operation.

Some messages, sent to the gateway, may require acknowledgement by the latter. The amount of retry attempts before reporting unsuccessful result of the operation may be specified using this function. The default value is 3.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	value	Number of retry attempts.

◆ cc_mqttsn_client_set_retry_period()

void cc_mqttsn_client_set_retry_period	(	CC_MqttsnClientHandle	client,
		unsigned	value
	)

Set retry period to wait between resending unacknowledged message to the gateway.

Some messages, sent to the gateway, may require acknowledgement by the latter. The delay (in seconds) between such attempts to resend the message may be specified using this function. The default value is 15 seconds.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	value	Number of seconds to wait before making an attempt to resend.

◆ cc_mqttsn_client_set_searchgw_enabled()

void cc_mqttsn_client_set_searchgw_enabled	(	CC_MqttsnClientHandle	client,
		bool	value
	)

Enable/Disable search for gateways.

According to MQTT-SN protocol specification the client may search for the gateways by broadcasting SEARCHGW message. If address of the gateway is known (such as known UDP host), there may be no need to send these messages. To enable/disable search for available gateways can be done using this function. By default the search for the gateway is enabled.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	value	true to enable, and false to disable.

◆ cc_mqttsn_client_set_send_output_data_callback()

void cc_mqttsn_client_set_send_output_data_callback	(	CC_MqttsnClientHandle	client,
		CC_MqttsnSendOutputDataFn	fn,
		void *	data
	)

Set callback to send raw data over I/O link.

The callback is invoked when there is a need to send data to the gateway. The callback is invoked for every single message that need to be sent as a single datagram.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	fn	Callback function.
[in]	data	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

◆ cc_mqttsn_client_sleep()

CC_MqttsnErrorCode cc_mqttsn_client_sleep	(	CC_MqttsnClientHandle	client,
		unsigned short	duration,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Notify gateway about entering the sleep state.

When the operation is complete, the provided callback will be invoked. If successful completion is reported, the client may enter the low power mode and do not send any messages within the "keep alive" period specified in cc_mqttsn_client_connect() invocation. However, there is a need to either wake up (using cc_mqttsn_client_reconnect()) or check for the accumulated messages (using cc_mqttsn_client_check_messages()) within the period specified in this function invocation.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	duration	Muximal number of seconds the client will remain in the sleep state until next check of accumulated pending messages (use cc_mqttsn_client_check_messages() for this purpose) or full wake up (use cc_mqttsn_client_reconnect() for this purpose).
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_start()

CC_MqttsnErrorCode cc_mqttsn_client_start ( CC_MqttsnClientHandle client )

Start the library's operation.

The function will check whether all necessary callback functions were set. In not CC_MqttsnErrorCode_BadParam will be returned. If search for gateways is enabled (see description of cc_mqttsn_client_set_searchgw_enabled()), the library may send SEARCHGW message by invoking the callback, set by cc_mqttsn_client_set_send_output_data_callback().

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_stop()

CC_MqttsnErrorCode cc_mqttsn_client_stop ( CC_MqttsnClientHandle client )

Stop the library's operation.

The operation may be resumed using cc_mqttsn_client_start().

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

Returns: Error code indicating success/failure status of the operation

◆ cc_mqttsn_client_subscribe()

CC_MqttsnErrorCode cc_mqttsn_client_subscribe	(	CC_MqttsnClientHandle	client,
		const char *	topic,
		CC_MqttsnQoS	qos,
		CC_MqttsnSubscribeCompleteReportFn	callback,
		void *	data
	)

Subscribe to topic.

When subscribe operation is complete, the provided callback will be invoked.

IMPORTANT : The buffer containing topic string must be preserved intact until the end of the operation (provided callback is invoked).

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topic	Topic string.
[in]	qos	Maximum level of quality of service the messages are sent to this client.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_subscribe_id()

CC_MqttsnErrorCode cc_mqttsn_client_subscribe_id	(	CC_MqttsnClientHandle	client,
		CC_MqttsnTopicId	topicId,
		CC_MqttsnQoS	qos,
		CC_MqttsnSubscribeCompleteReportFn	callback,
		void *	data
	)

Subscribe to topic having predefined topic ID.

When subscribe operation is complete, the provided callback will be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topicId	Predefined topic ID.
[in]	qos	Maximum level of quality of service the messages are sent to this client.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_tick()

void cc_mqttsn_client_tick ( CC_MqttsnClientHandle client )

Notify client about requested time expiry.

The reported amount of milliseconds needs to be from the last request to program timer via callback (set by cc_mqttsn_client_set_next_tick_program_callback()). It can be less than actually requested via the callback. If this function is called, the library assumes that previously requested timeout measurement is not in progress any more, and will request new measurement if needed. This call may cause invocation of some other callbacks, such as a request to send new data to the gateway.

Parameters

[in] client Handle returned by cc_mqttsn_client_new() function.

◆ cc_mqttsn_client_unsubscribe()

CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe	(	CC_MqttsnClientHandle	client,
		const char *	topic,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Unsubscribe from messages having specified topic.

When unsubscribe operation is complete, the provided callback will be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topic	Topic string.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_unsubscribe_id()

CC_MqttsnErrorCode cc_mqttsn_client_unsubscribe_id	(	CC_MqttsnClientHandle	client,
		CC_MqttsnTopicId	topicId,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Unsubscribe from messages having predefined topic ID.

When unsubscribe operation is complete, the provided callback will be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topicId	Predefined topic ID.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_will_msg_update()

CC_MqttsnErrorCode cc_mqttsn_client_will_msg_update	(	CC_MqttsnClientHandle	client,
		const unsigned char *	msg,
		unsigned	msgLen,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Update will message body recorded with the gateway/broker.

When the operation is complete, the provided callback will be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	msg	Pointer to message body buffer
[in]	msgLen	Length of message body buffer.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_will_topic_update()

CC_MqttsnErrorCode cc_mqttsn_client_will_topic_update	(	CC_MqttsnClientHandle	client,
		const char *	topic,
		CC_MqttsnQoS	qos,
		bool	retain,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Update topic of the will recorded with the gateway/broker.

When the operation is complete, the provided callback will be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	topic	New will topic string. The parameter can be NULL. In this case the request means erase current will information recorded with the gateway/broker.
[in]	qos	Quality of service for the will.
[in]	retain	Retain flag.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.

◆ cc_mqttsn_client_will_update()

CC_MqttsnErrorCode cc_mqttsn_client_will_update	(	CC_MqttsnClientHandle	client,
		const CC_MqttsnWillInfo *	willInfo,
		CC_MqttsnAsyncOpCompleteReportFn	callback,
		void *	data
	)

Update will recorded with the gateway/broker.

When the operation is complete, the provided callback will be invoked.

Parameters

[in]	client	Handle returned by cc_mqttsn_client_new() function.
[in]	willInfo	New will full information. The parameter can be NULL or the topic data member of the CC_MqttsnWillInfo struct may be null. In this case the request means erase current will information recorded with the gateway/broker.
[in]	callback	Callback to be invoked when operation is complete, must NOT be NULL.
[in]	data	Pointer to any user data, it will be passed as the first parameter to the invoked completion report callback, can be NULL.

Returns: Error code indicating success/failure status of the operation.