Classes
struct	CC_Mqtt5PublishBasicConfig
	Configuration structure to be passed to the cc_mqtt5_client_publish_config_basic(). More...

struct	CC_Mqtt5PublishExtraConfig
	Configuration structure to be passed to the cc_mqtt5_client_publish_config_extra(). More...

struct	CC_Mqtt5PublishResponse
	Response information from broker to "publish" request. More...

Typedefs
typedef void(*	CC_Mqtt5PublishCompleteCb) (void data, CC_Mqtt5PublishHandle handle, CC_Mqtt5AsyncOpStatus status, const CC_Mqtt5PublishResponse response)
	Callback used to report completion of the "publish" operation.

typedef struct CC_Mqtt5Publish *	CC_Mqtt5PublishHandle
	Handle for "publish" operation.

Enumerations
enum	CC_Mqtt5PublishOrdering { CC_Mqtt5PublishOrdering_SameQos , CC_Mqtt5PublishOrdering_Full , CC_Mqtt5PublishOrdering_ValuesLimit }
	Publish ordering configuration. More...

enum	CC_Mqtt5TopicAliasPreference { CC_Mqtt5TopicAliasPreference_UseAliasIfAvailable = 0 , CC_Mqtt5TopicAliasPreference_ForceAliasOnly = 1 , CC_Mqtt5TopicAliasPreference_ForceTopicOnly = 2 , CC_Mqtt5TopicAliasPreference_ForceTopicWithAlias = 3 , CC_Mqtt5TopicAliasPreference_ValuesLimit }
	Preference of whether to use numeric "Topic Alias" instead of string topic during publish operation. More...

Functions
CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_add_user_prop (CC_Mqtt5PublishHandle handle, const CC_Mqtt5UserProp *prop)
	Add user property to the configuration of the "publish" operation.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_cancel (CC_Mqtt5PublishHandle handle)
	Cancel the allocated "publish" operation.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_config_basic (CC_Mqtt5PublishHandle handle, const CC_Mqtt5PublishBasicConfig *config)
	Perform basic configuration of the "publish" operation.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_config_extra (CC_Mqtt5PublishHandle handle, const CC_Mqtt5PublishExtraConfig *config)
	Perform extra properties configuration of the "publish" operation.

unsigned	cc_mqtt5_client_publish_count (CC_Mqtt5ClientHandle handle)
	Get amount incomplete "publish" operations.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_full (CC_Mqtt5ClientHandle handle, const CC_Mqtt5PublishBasicConfig basicConfig, const CC_Mqtt5PublishExtraConfig extraConfig, CC_Mqtt5PublishCompleteCb cb, void *cbData)
	Prepare, configure, and send "publish" request in one go (full version)

CC_Mqtt5PublishOrdering	cc_mqtt5_client_publish_get_ordering (CC_Mqtt5ClientHandle handle)
	Retrieve the configured the publish operations ordering.

unsigned	cc_mqtt5_client_publish_get_resend_attempts (CC_Mqtt5PublishHandle handle)
	Retrieve the configured the amount of resend attempts for the "publish" operation.

unsigned	cc_mqtt5_client_publish_get_response_timeout (CC_Mqtt5PublishHandle handle)
	Retrieve the configured the broker response timeout for the "publish" operation.

void	cc_mqtt5_client_publish_init_config_basic (CC_Mqtt5PublishBasicConfig *config)
	Intialize the CC_Mqtt5PublishBasicConfig configuration structure.

void	cc_mqtt5_client_publish_init_config_extra (CC_Mqtt5PublishExtraConfig *config)
	Intialize the CC_Mqtt5PublishExtraConfig configuration structure.

CC_Mqtt5PublishHandle	cc_mqtt5_client_publish_prepare (CC_Mqtt5ClientHandle handle, CC_Mqtt5ErrorCode *ec)
	Prepare "publish" operation.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_send (CC_Mqtt5PublishHandle handle, CC_Mqtt5PublishCompleteCb cb, void *cbData)
	Send the configured "publish" operation to broker.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_set_ordering (CC_Mqtt5ClientHandle handle, CC_Mqtt5PublishOrdering ordering)
	Configure the ordering of the published messages.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_set_resend_attempts (CC_Mqtt5PublishHandle handle, unsigned attempts)
	Configure the amount of attempts to resend "publish" operation until the acknowledgement is received.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_set_response_timeout (CC_Mqtt5PublishHandle handle, unsigned ms)
	Configure the broker response timeout for the "publish" operation.

CC_Mqtt5ErrorCode	cc_mqtt5_client_publish_simple (CC_Mqtt5ClientHandle handle, const CC_Mqtt5PublishBasicConfig basicConfig, CC_Mqtt5PublishCompleteCb cb, void cbData)
	Prepare, configure, and send "publish" request in one go (simple version)

bool	cc_mqtt5_client_publish_was_initiated (CC_Mqtt5PublishHandle handle)
	Check whether the "publish" operation was actually initiated (PUBLISH was sent)

Detailed Description

Typedef Documentation

◆ CC_Mqtt5PublishCompleteCb

typedef void(* CC_Mqtt5PublishCompleteCb) (void *data, CC_Mqtt5PublishHandle handle, CC_Mqtt5AsyncOpStatus status, const CC_Mqtt5PublishResponse *response)

Callback used to report completion of the "publish" operation.

Parameters

[in]	data	Pointer to user data object passed as last parameter to the cc_mqtt5_client_publish_send().
[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function. When the callback is invoked the handle is already invalid and cannot be used in any relevant function invocation, but it allows end application to identify the original "publish" operation and use the same callback function in parallel requests.
[in]	status	Status of the "publish" operation.
[in]	response	Response information from the broker. Not-NULL is reported if and onfly if the "status" is equal to CC_Mqtt5AsyncOpStatus_Complete.

Postcondition: The data members of the reported response can NOT be accessed after the function returns.

◆ CC_Mqtt5PublishHandle

typedef struct CC_Mqtt5Publish* CC_Mqtt5PublishHandle

Handle for "publish" operation.

Returned by cc_mqtt5_client_publish_prepare() function.

Enumeration Type Documentation

◆ CC_Mqtt5PublishOrdering

enum CC_Mqtt5PublishOrdering

Publish ordering configuration.

Enumerator
CC_Mqtt5PublishOrdering_SameQos	Preserve strict order only between same QoS messages.
CC_Mqtt5PublishOrdering_Full	Preserve strict order between all messages.
CC_Mqtt5PublishOrdering_ValuesLimit	Limit for the values.

◆ CC_Mqtt5TopicAliasPreference

enum CC_Mqtt5TopicAliasPreference

Preference of whether to use numeric "Topic Alias" instead of string topic during publish operation.

Enumerator
CC_Mqtt5TopicAliasPreference_UseAliasIfAvailable	Use topic alias if such is available.
CC_Mqtt5TopicAliasPreference_ForceAliasOnly	Force sending topic alias, requires topic alias to be allocated.
CC_Mqtt5TopicAliasPreference_ForceTopicOnly	Force sending topic string even if topic alias is available.
CC_Mqtt5TopicAliasPreference_ForceTopicWithAlias	Force sending both topic string and its numeric alias.
CC_Mqtt5TopicAliasPreference_ValuesLimit	Limit for the values.

Function Documentation

◆ cc_mqtt5_client_publish_add_user_prop()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_add_user_prop	(	CC_Mqtt5PublishHandle	handle,
		const CC_Mqtt5UserProp *	prop
	)

Add user property to the configuration of the "publish" operation.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	prop	Single user property info. Must NOT be NULL. Does not need to be preserved after invocation.

Returns: Result code of the call.

◆ cc_mqtt5_client_publish_cancel()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_cancel ( CC_Mqtt5PublishHandle handle )

Cancel the allocated "publish" operation.

In case the cc_mqtt5_client_publish_send() function was successfully called before, the operation is cancelled without callback invocation.

Parameters

[in] handle Handle returned by cc_mqtt5_client_publish_prepare() function.

Returns: Result code of the call.

Postcondition: The handle of the "publish" operation is no longer valid and must be discarded.

◆ cc_mqtt5_client_publish_config_basic()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_config_basic	(	CC_Mqtt5PublishHandle	handle,
		const CC_Mqtt5PublishBasicConfig *	config
	)

Perform basic configuration of the "publish" operation.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	config	Basic configuration structure. Must NOT be NULL. Does not need to be preserved after invocation.

Returns: Result code of the call.

Postcondition: Some of the properties can get assigned regardless of the return value.

Precondition: Mustn't be called more than once for a single "publish" operation when "topic alias" can be used.

◆ cc_mqtt5_client_publish_config_extra()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_config_extra	(	CC_Mqtt5PublishHandle	handle,
		const CC_Mqtt5PublishExtraConfig *	config
	)

Perform extra properties configuration of the "publish" operation.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	config	Extra properties configuration structure. Must NOT be NULL. Does not need to be preserved after invocation.

Returns: Result code of the call.

Precondition: Mustn't be called more than once for a single "publish" operation.

Postcondition: Some of the properties can get assigned regardless of the return value.

◆ cc_mqtt5_client_publish_count()

unsigned cc_mqtt5_client_publish_count ( CC_Mqtt5ClientHandle handle )

Get amount incomplete "publish" operations.

Parameters

[in] handle Handle returned by cc_mqtt5_client_alloc() function.

Returns: Amount of publish operations that have been prepared before, and are still incomplete.

◆ cc_mqtt5_client_publish_full()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_full	(	CC_Mqtt5ClientHandle	handle,
		const CC_Mqtt5PublishBasicConfig *	basicConfig,
		const CC_Mqtt5PublishExtraConfig *	extraConfig,
		CC_Mqtt5PublishCompleteCb	cb,
		void *	cbData
	)

Prepare, configure, and send "publish" request in one go (full version)

Abstracts away sequence of the following functions invocation:

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_alloc() function.
[in]	basicConfig	Basic configuration.
[in]	extraConfig	Extra configuration. Can be NULL.
[in]	cb	Callback to be invoked when "publish" operation is complete.
[in]	cbData	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

Returns: Result code of the call.

◆ cc_mqtt5_client_publish_get_ordering()

CC_Mqtt5PublishOrdering cc_mqtt5_client_publish_get_ordering ( CC_Mqtt5ClientHandle handle )

Retrieve the configured the publish operations ordering.

Parameters

[in] handle Handle returned by cc_mqtt5_client_publish_prepare() function.

Returns: Current ordering configuraiton.

◆ cc_mqtt5_client_publish_get_resend_attempts()

unsigned cc_mqtt5_client_publish_get_resend_attempts ( CC_Mqtt5PublishHandle handle )

Retrieve the configured the amount of resend attempts for the "publish" operation.

Parameters

[in] handle Handle returned by cc_mqtt5_client_publish_prepare() function.

Returns: Configured amount of resend attempts.

◆ cc_mqtt5_client_publish_get_response_timeout()

unsigned cc_mqtt5_client_publish_get_response_timeout ( CC_Mqtt5PublishHandle handle )

Retrieve the configured the broker response timeout for the "publish" operation.

Parameters

[in] handle Handle returned by cc_mqtt5_client_publish_prepare() function.

Returns: Response timeout duration in milliseconds.

◆ cc_mqtt5_client_publish_init_config_basic()

void cc_mqtt5_client_publish_init_config_basic ( CC_Mqtt5PublishBasicConfig * config )

Intialize the CC_Mqtt5PublishBasicConfig configuration structure.

Parameters

[out] config Configuration structure. Must not be NULL.

◆ cc_mqtt5_client_publish_init_config_extra()

void cc_mqtt5_client_publish_init_config_extra ( CC_Mqtt5PublishExtraConfig * config )

Intialize the CC_Mqtt5PublishExtraConfig configuration structure.

Parameters

[out] config Configuration structure. Must not be NULL.

◆ cc_mqtt5_client_publish_prepare()

CC_Mqtt5PublishHandle cc_mqtt5_client_publish_prepare	(	CC_Mqtt5ClientHandle	handle,
		CC_Mqtt5ErrorCode *	ec
	)

Prepare "publish" operation.

For successful operation the client needs to be in the "connected" state.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_alloc() function.
[out]	ec	Error code reporting result of the operation. Can be NULL.

Returns: Handle of the "publish" operation, will be NULL in case of failure. To analyze the reason failure use "ec" output parameter.

Postcondition: The "publish" operation is allocated, use either cc_mqtt5_client_publish_send() or cc_mqtt5_client_publish_cancel() to prevent memory leaks.

◆ cc_mqtt5_client_publish_send()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_send	(	CC_Mqtt5PublishHandle	handle,
		CC_Mqtt5PublishCompleteCb	cb,
		void *	cbData
	)

Send the configured "publish" operation to broker.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	cb	Callback to be invoked when "publish" operation is complete, can be NULL.
[in]	cbData	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. Can be NULL.

Returns: Result code of the call.

Postcondition: The handle of the "publish" operation can be discarded.; The provided callback will be invoked when the "publish" operation is complete if and only if the function returns CC_Mqtt5ErrorCode_Success.

◆ cc_mqtt5_client_publish_set_ordering()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_set_ordering	(	CC_Mqtt5ClientHandle	handle,
		CC_Mqtt5PublishOrdering	ordering
	)

Configure the ordering of the published messages.

The ordering configuration is expected to be performed before any "publish" operation is issued. The configuration is persistent between re-connects.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	ordering	Ordering configuration.

Returns: Result code of the call.

◆ cc_mqtt5_client_publish_set_resend_attempts()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_set_resend_attempts	(	CC_Mqtt5PublishHandle	handle,
		unsigned	attempts
	)

Configure the amount of attempts to resend "publish" operation until the acknowledgement is received.

When resending a second and further time, the DUP flags is set in the PUBLISH message to indicate duplicate.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	attempts	Amount of resend attempts.

Returns: Result code of the call.

◆ cc_mqtt5_client_publish_set_response_timeout()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_set_response_timeout	(	CC_Mqtt5PublishHandle	handle,
		unsigned	ms
	)

Configure the broker response timeout for the "publish" operation.

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_publish_prepare() function.
[in]	ms	Response timeout duration in milliseconds.

Returns: Result code of the call.

◆ cc_mqtt5_client_publish_simple()

CC_Mqtt5ErrorCode cc_mqtt5_client_publish_simple	(	CC_Mqtt5ClientHandle	handle,
		const CC_Mqtt5PublishBasicConfig *	basicConfig,
		CC_Mqtt5PublishCompleteCb	cb,
		void *	cbData
	)

Prepare, configure, and send "publish" request in one go (simple version)

Abstracts away sequence of the following functions invocation:

Parameters

[in]	handle	Handle returned by cc_mqtt5_client_alloc() function.
[in]	basicConfig	Basic configuration.
[in]	cb	Callback to be invoked when "publish" operation is complete.
[in]	cbData	Pointer to any user data structure. It will passed as one of the parameters in callback invocation. May be NULL.

Returns: Result code of the call.

◆ cc_mqtt5_client_publish_was_initiated()

bool cc_mqtt5_client_publish_was_initiated ( CC_Mqtt5PublishHandle handle )

Check whether the "publish" operation was actually initiated (PUBLISH was sent)

In case the amount of outgoing publish messages exceeds the "Receive Maximum" limit set by the broker, or due to message ordering configuration, the requested "publish" operation can be paused. This API call checks whether the PUBLISH message was already sent to the broker.

Parameters

[in] handle Handle returned by cc_mqtt5_client_publish_prepare() function.

Returns: true in case PUBLISH message has already been sent.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ CC_Mqtt5PublishCompleteCb

◆ CC_Mqtt5PublishHandle

Enumeration Type Documentation

◆ CC_Mqtt5PublishOrdering

◆ CC_Mqtt5TopicAliasPreference

Function Documentation

◆ cc_mqtt5_client_publish_add_user_prop()

◆ cc_mqtt5_client_publish_cancel()

◆ cc_mqtt5_client_publish_config_basic()

◆ cc_mqtt5_client_publish_config_extra()

◆ cc_mqtt5_client_publish_count()

◆ cc_mqtt5_client_publish_full()

◆ cc_mqtt5_client_publish_get_ordering()

◆ cc_mqtt5_client_publish_get_resend_attempts()

◆ cc_mqtt5_client_publish_get_response_timeout()

◆ cc_mqtt5_client_publish_init_config_basic()

◆ cc_mqtt5_client_publish_init_config_extra()

◆ cc_mqtt5_client_publish_prepare()

◆ cc_mqtt5_client_publish_send()

◆ cc_mqtt5_client_publish_set_ordering()

◆ cc_mqtt5_client_publish_set_resend_attempts()

◆ cc_mqtt5_client_publish_set_response_timeout()

◆ cc_mqtt5_client_publish_simple()

◆ cc_mqtt5_client_publish_was_initiated()