CommsChampion Ecosystem MQTT v5 Client
MQTT v5 Client Library.
Loading...
Searching...
No Matches
Typedefs | Functions
"Client Data Types and Functions"

Typedefs

typedef void(* CC_Mqtt5BrokerDisconnectReportCb) (void *data, CC_Mqtt5BrokerDisconnectReason reason, const CC_Mqtt5DisconnectInfo *info)
 Callback used to report unsolicited disconnection of the broker.
 
typedef unsigned(* CC_Mqtt5CancelNextTickWaitCb) (void *data)
 Callback used to request termination of existing time measurement.
 
typedef struct CC_Mqtt5Client * CC_Mqtt5ClientHandle
 Handle used to access client specific data structures.
 
typedef void(* CC_Mqtt5ErrorLogCb) (void *data, const char *msg)
 Callback used to report discovered errors.
 
typedef void(* CC_Mqtt5MessageReceivedReportCb) (void *data, const CC_Mqtt5MessageInfo *info)
 Callback used to report new message received of the broker.
 
typedef void(* CC_Mqtt5NextTickProgramCb) (void *data, unsigned duration)
 Callback used to request time measurement.
 
typedef void(* CC_Mqtt5SendOutputDataCb) (void *data, const unsigned char *buf, unsigned bufLen)
 Callback used to request to send data to the broker.
 

Functions

CC_Mqtt5ClientHandle cc_mqtt5_client_alloc ()
 Allocate new client.
 
void cc_mqtt5_client_free (CC_Mqtt5ClientHandle handle)
 Free previously allocated client.
 
unsigned cc_mqtt5_client_get_default_response_timeout (CC_Mqtt5ClientHandle handle)
 Retrieved currently configured default response timeout period.
 
bool cc_mqtt5_client_get_verify_incoming_msg_subscribed (CC_Mqtt5ClientHandle handle)
 Retrieve current incoming message being correctly subscribed control.
 
bool cc_mqtt5_client_get_verify_incoming_topic_enabled (CC_Mqtt5ClientHandle handle)
 Retrieve current incoming topic format verification control.
 
bool cc_mqtt5_client_get_verify_outgoing_topic_enabled (CC_Mqtt5ClientHandle handle)
 Retrieve current outgoing topic format verification control.
 
bool cc_mqtt5_client_is_network_disconnected (CC_Mqtt5ClientHandle handle)
 Check current network disconnected status.
 
void cc_mqtt5_client_notify_network_disconnected (CC_Mqtt5ClientHandle handle)
 Report network disconnected.
 
unsigned cc_mqtt5_client_process_data (CC_Mqtt5ClientHandle handle, const unsigned char *buf, unsigned bufLen)
 Provide data (received over I/O link), to the library for processing.
 
CC_Mqtt5ErrorCode cc_mqtt5_client_pub_topic_alias_alloc (CC_Mqtt5ClientHandle handle, const char *topic, unsigned qos0RegsCount)
 Allocate alias for topic.
 
unsigned cc_mqtt5_client_pub_topic_alias_count (CC_Mqtt5ClientHandle handle)
 Get amount of allocated topic aliases.
 
CC_Mqtt5ErrorCode cc_mqtt5_client_pub_topic_alias_free (CC_Mqtt5ClientHandle handle, const char *topic)
 Free alias for topic for another use.
 
bool cc_mqtt5_client_pub_topic_alias_is_allocated (CC_Mqtt5ClientHandle handle, const char *topic)
 Check if topic alias is allocated for topic.
 
CC_Mqtt5ErrorCode cc_mqtt5_client_set_default_response_timeout (CC_Mqtt5ClientHandle handle, unsigned ms)
 Configure default response timeout period.
 
CC_Mqtt5ErrorCode cc_mqtt5_client_set_verify_incoming_msg_subscribed (CC_Mqtt5ClientHandle handle, bool enabled)
 Control verification of the incoming message being correctly subscribed.
 
CC_Mqtt5ErrorCode cc_mqtt5_client_set_verify_incoming_topic_enabled (CC_Mqtt5ClientHandle handle, bool enabled)
 Control incoming topic format verification.
 
CC_Mqtt5ErrorCode cc_mqtt5_client_set_verify_outgoing_topic_enabled (CC_Mqtt5ClientHandle handle, bool enabled)
 Control outgoing topic format verification.
 
void cc_mqtt5_client_tick (CC_Mqtt5ClientHandle handle, unsigned ms)
 Notify client about requested time expiry.
 

Detailed Description

Typedef Documentation

◆ CC_Mqtt5BrokerDisconnectReportCb

typedef void(* CC_Mqtt5BrokerDisconnectReportCb) (void *data, CC_Mqtt5BrokerDisconnectReason reason, const CC_Mqtt5DisconnectInfo *info)

Callback used to report unsolicited disconnection of the broker.

When invoked the "info" is present if and only if the broker disconnection report is due to the reception of the DISCONNECT message from the broker.

Parameters
[in]dataPointer to user data object, passed as the last parameter to the request call.
[in]reasonReson for reporting unsolicited broker disconnection.
[in]infoExtra disconnect information when reported by the broker. Can be NULL. Not null, if and only if the reason is CC_Mqtt5BrokerDisconnectReason_DisconnectMsg.
Postcondition
The data members of the reported info can NOT be accessed after the function returns.

◆ CC_Mqtt5CancelNextTickWaitCb

typedef unsigned(* CC_Mqtt5CancelNextTickWaitCb) (void *data)

Callback used to request termination of existing time measurement.

The callback is set using cc_mqtt5_client_set_cancel_next_tick_wait_callback() function.

Parameters
[in]dataPointer to user data object, passed as last parameter to cc_mqtt5_client_set_cancel_next_tick_wait_callback() function.
Returns
Number of elapsed milliseconds since last time measurement request.

◆ CC_Mqtt5ClientHandle

typedef struct CC_Mqtt5Client* CC_Mqtt5ClientHandle

Handle used to access client specific data structures.

Returned by cc_mqtt5_client_alloc() function.

◆ CC_Mqtt5ErrorLogCb

typedef void(* CC_Mqtt5ErrorLogCb) (void *data, const char *msg)

Callback used to report discovered errors.

Parameters
[in]dataPointer to user data object, passed as the last parameter to the request call.
[in]msgError log message.

◆ CC_Mqtt5MessageReceivedReportCb

typedef void(* CC_Mqtt5MessageReceivedReportCb) (void *data, const CC_Mqtt5MessageInfo *info)

Callback used to report new message received of the broker.

Parameters
[in]dataPointer to user data object, passed as the last parameter to the request call.
[in]infoMessage information. Will NOT be NULL.
Postcondition
The data members of the reported info can NOT be accessed after the function returns.

◆ CC_Mqtt5NextTickProgramCb

typedef void(* CC_Mqtt5NextTickProgramCb) (void *data, unsigned duration)

Callback used to request time measurement.

The callback is set using cc_mqtt5_client_set_next_tick_program_callback() function.

Parameters
[in]dataPointer to user data object, passed as last parameter to cc_mqtt5_client_set_next_tick_program_callback() function.
[in]durationTime duration in milliseconds. After the requested time expires, the cc_mqtt5_client_tick() function is expected to be invoked.

◆ CC_Mqtt5SendOutputDataCb

typedef void(* CC_Mqtt5SendOutputDataCb) (void *data, const unsigned char *buf, unsigned bufLen)

Callback used to request to send data to the broker.

The callback is set using cc_mqtt5_client_set_send_output_data_callback() function. The reported data resides in internal data structures of the client library, which can be updated / deleted right after the callback function returns. It means the data may need to be copied into some other buffer which will be held intact until the send over I/O link operation is complete.

Parameters
[in]dataPointer to user data object, passed as last parameter to cc_mqtt5_client_set_send_output_data_callback() function.
[in]bufPointer to the buffer containing data to send
[in]bufLenNumber of bytes in the buffer
Postcondition
The buffer data can be deallocated / overwritten after the callback function returns.

Function Documentation

◆ cc_mqtt5_client_alloc()

CC_Mqtt5ClientHandle cc_mqtt5_client_alloc ( )

Allocate new client.

When work with the client is complete, cc_mqtt5_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_mqtt5_client_free()

void cc_mqtt5_client_free ( CC_Mqtt5ClientHandle  handle)

Free previously allocated client.

The callbacks of the incomplete operations will be invoked with CC_Mqtt5AsyncOpStatus_Aborted status.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Precondition
Mustn't be called from within a callback, use next event loop iteration.
Postcondition
The client handler becomes invalid and cannot be used any longer.

◆ cc_mqtt5_client_get_default_response_timeout()

unsigned cc_mqtt5_client_get_default_response_timeout ( CC_Mqtt5ClientHandle  handle)

Retrieved currently configured default response timeout period.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Returns
Response timeout duration in milliseconds.

◆ cc_mqtt5_client_get_verify_incoming_msg_subscribed()

bool cc_mqtt5_client_get_verify_incoming_msg_subscribed ( CC_Mqtt5ClientHandle  handle)

Retrieve current incoming message being correctly subscribed control.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Returns
true when enabled, false when disabled

◆ cc_mqtt5_client_get_verify_incoming_topic_enabled()

bool cc_mqtt5_client_get_verify_incoming_topic_enabled ( CC_Mqtt5ClientHandle  handle)

Retrieve current incoming topic format verification control.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Returns
true when enabled, false when disabled

◆ cc_mqtt5_client_get_verify_outgoing_topic_enabled()

bool cc_mqtt5_client_get_verify_outgoing_topic_enabled ( CC_Mqtt5ClientHandle  handle)

Retrieve current outgoing topic format verification control.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Returns
true when enabled, false when disabled

◆ cc_mqtt5_client_is_network_disconnected()

bool cc_mqtt5_client_is_network_disconnected ( CC_Mqtt5ClientHandle  handle)

Check current network disconnected status.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Returns
true when disconnected, false when0 connected.
Note
After invocation of the cc_mqtt5_client_alloc(), this function will return false, i.e. after client allocation network is assumend connected.

◆ cc_mqtt5_client_notify_network_disconnected()

void cc_mqtt5_client_notify_network_disconnected ( CC_Mqtt5ClientHandle  handle)

Report network disconnected.

To notify the client that the network is connected again use cc_mqtt5_client_connect_prepare()

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.

◆ cc_mqtt5_client_process_data()

unsigned cc_mqtt5_client_process_data ( CC_Mqtt5ClientHandle  handle,
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 broker, report incoming application message, and (re)start time measurement.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]bufPointer to the buffer of data to process.
[in]bufLenNumber 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_mqtt5_client_pub_topic_alias_alloc()

CC_Mqtt5ErrorCode cc_mqtt5_client_pub_topic_alias_alloc ( CC_Mqtt5ClientHandle  handle,
const char *  topic,
unsigned  qos0RegsCount 
)

Allocate alias for topic.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]topicTopic string for which the alias needs to be allocated.
[in]qos0RegsCountAmount of times to report topic alias to the broker when QoS0 messages are used, mustn't be greather than 255.
Returns
Error code of the operation

◆ cc_mqtt5_client_pub_topic_alias_count()

unsigned cc_mqtt5_client_pub_topic_alias_count ( CC_Mqtt5ClientHandle  handle)

Get amount of allocated topic aliases.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
Returns
Amount of allocated topic aliases

◆ cc_mqtt5_client_pub_topic_alias_free()

CC_Mqtt5ErrorCode cc_mqtt5_client_pub_topic_alias_free ( CC_Mqtt5ClientHandle  handle,
const char *  topic 
)

Free alias for topic for another use.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]topicTopic string for which the alias was allocated before.
Returns
Error code of the operation

◆ cc_mqtt5_client_pub_topic_alias_is_allocated()

bool cc_mqtt5_client_pub_topic_alias_is_allocated ( CC_Mqtt5ClientHandle  handle,
const char *  topic 
)

Check if topic alias is allocated for topic.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]topicTopic string .
Returns
true in case of allocated, false otherwise

◆ cc_mqtt5_client_set_default_response_timeout()

CC_Mqtt5ErrorCode cc_mqtt5_client_set_default_response_timeout ( CC_Mqtt5ClientHandle  handle,
unsigned  ms 
)

Configure default response timeout period.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]msResponse timeout duration in milliseconds.
Returns
Error code of the operation

◆ cc_mqtt5_client_set_verify_incoming_msg_subscribed()

CC_Mqtt5ErrorCode cc_mqtt5_client_set_verify_incoming_msg_subscribed ( CC_Mqtt5ClientHandle  handle,
bool  enabled 
)

Control verification of the incoming message being correctly subscribed.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]enabledtrue to enable topic format verification, false to disable.
Returns
Error code of the operation

◆ cc_mqtt5_client_set_verify_incoming_topic_enabled()

CC_Mqtt5ErrorCode cc_mqtt5_client_set_verify_incoming_topic_enabled ( CC_Mqtt5ClientHandle  handle,
bool  enabled 
)

Control incoming topic format verification.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]enabledtrue to enable topic format verification, false to disable.
Returns
Error code of the operation

◆ cc_mqtt5_client_set_verify_outgoing_topic_enabled()

CC_Mqtt5ErrorCode cc_mqtt5_client_set_verify_outgoing_topic_enabled ( CC_Mqtt5ClientHandle  handle,
bool  enabled 
)

Control outgoing topic format verification.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]enabledtrue to enable topic format verification, false to disable.
Returns
Error code of the operation

◆ cc_mqtt5_client_tick()

void cc_mqtt5_client_tick ( CC_Mqtt5ClientHandle  handle,
unsigned  ms 
)

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_mqtt5_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 broker.

Parameters
[in]handleHandle returned by cc_mqtt5_client_alloc() function.
[in]msNumber of elapsed milliseconds.
Generated by doxygen 1.9.8