CommsChampion Ecosystem MQTT v3.1.1 Client
MQTT v3.1.1 Client Library.
Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations | Functions
"Subscribe Operation Data Type and Functions"

Classes

struct  CC_Mqtt311SubscribeResponse
 Response information from broker to "subscribe" request. More...
 
struct  CC_Mqtt311SubscribeTopicConfig
 Topic filter configuration structure of the "subscribe" operation. More...
 

Typedefs

typedef void(* CC_Mqtt311SubscribeCompleteCb) (void *data, CC_Mqtt311SubscribeHandle handle, CC_Mqtt311AsyncOpStatus status, const CC_Mqtt311SubscribeResponse *response)
 Callback used to report completion of the "subscribe" operation.
 
typedef struct CC_Mqtt311Subscribe * CC_Mqtt311SubscribeHandle
 Handle for "subscribe" operation.
 

Enumerations

enum  CC_Mqtt311SubscribeReturnCode { CC_Mqtt311SubscribeReturnCode_SuccessQos0 = 0x00 , CC_Mqtt311SubscribeReturnCode_SuccessQos1 = 0x01 , CC_Mqtt311SubscribeReturnCode_SuccessQos2 = 0x02 , CC_Mqtt311SubscribeReturnCode_Failure = 0x80 }
 "Subscribe Return Code" as defined in MQTT v3.1.1 specification More...
 

Functions

CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe (CC_Mqtt311ClientHandle handle, const CC_Mqtt311SubscribeTopicConfig *topicConfigs, unsigned topicConfigsCount, CC_Mqtt311SubscribeCompleteCb cb, void *cbData)
 Prepare, configure, and send "subscribe" request in one go.
 
CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_cancel (CC_Mqtt311SubscribeHandle handle)
 Cancel the allocated "subscribe" operation.
 
CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_config_topic (CC_Mqtt311SubscribeHandle handle, const CC_Mqtt311SubscribeTopicConfig *config)
 Add topic configuration of the "subscribe" operation.
 
unsigned cc_mqtt311_client_subscribe_get_response_timeout (CC_Mqtt311SubscribeHandle handle)
 Retrieve the configured the broker response timeout for the "subscribe" operation.
 
void cc_mqtt311_client_subscribe_init_config_topic (CC_Mqtt311SubscribeTopicConfig *config)
 Intialize the CC_Mqtt311SubscribeTopicConfig configuration structure.
 
CC_Mqtt311SubscribeHandle cc_mqtt311_client_subscribe_prepare (CC_Mqtt311ClientHandle handle, CC_Mqtt311ErrorCode *ec)
 Prepare "subscribe" operation.
 
CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_send (CC_Mqtt311SubscribeHandle handle, CC_Mqtt311SubscribeCompleteCb cb, void *cbData)
 Send the configured "subscribe" operation to broker.
 
CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_set_response_timeout (CC_Mqtt311SubscribeHandle handle, unsigned ms)
 Configure the broker response timeout for the "subscribe" operation.
 

Detailed Description

Typedef Documentation

◆ CC_Mqtt311SubscribeCompleteCb

typedef void(* CC_Mqtt311SubscribeCompleteCb) (void *data, CC_Mqtt311SubscribeHandle handle, CC_Mqtt311AsyncOpStatus status, const CC_Mqtt311SubscribeResponse *response)

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

Parameters
[in]dataPointer to user data object passed as last parameter to the cc_mqtt311_client_subscribe_send().
[in]handleHandle returned by cc_mqtt311_client_subscribe_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 "subscribe" operation and use the same callback function in parallel requests.
[in]statusStatus of the "subscribe" operation.
[in]responseResponse information from the broker. Not-NULL is reported if and onfly if the "status" is equal to CC_Mqtt311AsyncOpStatus_Complete.
Postcondition
The data members of the reported response can NOT be accessed after the function returns.

◆ CC_Mqtt311SubscribeHandle

typedef struct CC_Mqtt311Subscribe* CC_Mqtt311SubscribeHandle

Handle for "subscribe" operation.

Returned by cc_mqtt311_client_subscribe_prepare() function.

Enumeration Type Documentation

◆ CC_Mqtt311SubscribeReturnCode

enum CC_Mqtt311SubscribeReturnCode

"Subscribe Return Code" as defined in MQTT v3.1.1 specification

Enumerator
CC_Mqtt311SubscribeReturnCode_SuccessQos0 

value Maximum QoS 0.

CC_Mqtt311SubscribeReturnCode_SuccessQos1 

value Maximum QoS 1.

CC_Mqtt311SubscribeReturnCode_SuccessQos2 

value Maximum QoS 2.

CC_Mqtt311SubscribeReturnCode_Failure 

value Failure.

Function Documentation

◆ cc_mqtt311_client_subscribe()

CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe ( CC_Mqtt311ClientHandle  handle,
const CC_Mqtt311SubscribeTopicConfig *  topicConfigs,
unsigned  topicConfigsCount,
CC_Mqtt311SubscribeCompleteCb  cb,
void *  cbData 
)

Prepare, configure, and send "subscribe" request in one go.

Abstracts away sequence of the following functions invocation:

Parameters
[in]handleHandle returned by cc_mqtt311_client_alloc() function.
[in]topicConfigsPointer to array of the topic configurations.
[in]topicConfigsCountAmount of the topic configurations in the array.
[in]cbCallback to be invoked when "subscribe" operation is complete.
[in]cbDataPointer 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_mqtt311_client_subscribe_cancel()

CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_cancel ( CC_Mqtt311SubscribeHandle  handle)

Cancel the allocated "subscribe" operation.

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

Parameters
[in]handleHandle returned by cc_mqtt311_client_subscribe_prepare() function.
Returns
Result code of the call.
Postcondition
The handle of the "subscribe" operation is no longer valid and must be discarded.

◆ cc_mqtt311_client_subscribe_config_topic()

CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_config_topic ( CC_Mqtt311SubscribeHandle  handle,
const CC_Mqtt311SubscribeTopicConfig *  config 
)

Add topic configuration of the "subscribe" operation.

Parameters
[in]handleHandle returned by cc_mqtt311_client_subscribe_prepare() function.
[in]configTopic configuration structure. Must NOT be NULL. Does not need to be preserved after invocation.
Returns
Result code of the call.

◆ cc_mqtt311_client_subscribe_get_response_timeout()

unsigned cc_mqtt311_client_subscribe_get_response_timeout ( CC_Mqtt311SubscribeHandle  handle)

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

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

◆ cc_mqtt311_client_subscribe_init_config_topic()

void cc_mqtt311_client_subscribe_init_config_topic ( CC_Mqtt311SubscribeTopicConfig *  config)

Intialize the CC_Mqtt311SubscribeTopicConfig configuration structure.

Parameters
[out]configConfiguration structure. Must not be NULL.

◆ cc_mqtt311_client_subscribe_prepare()

CC_Mqtt311SubscribeHandle cc_mqtt311_client_subscribe_prepare ( CC_Mqtt311ClientHandle  handle,
CC_Mqtt311ErrorCode *  ec 
)

Prepare "subscribe" operation.

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

Parameters
[in]handleHandle returned by cc_mqtt311_client_alloc() function.
[out]ecError code reporting result of the operation. Can be NULL.
Returns
Handle of the "subscribe" operation, will be NULL in case of failure. To analyze the reason failure use "ec" output parameter.
Postcondition
The "subscribe" operation is allocated, use either cc_mqtt311_client_subscribe_send() or cc_mqtt311_client_subscribe_cancel() to prevent memory leaks.

◆ cc_mqtt311_client_subscribe_send()

CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_send ( CC_Mqtt311SubscribeHandle  handle,
CC_Mqtt311SubscribeCompleteCb  cb,
void *  cbData 
)

Send the configured "subscribe" operation to broker.

Parameters
[in]handleHandle returned by cc_mqtt311_client_subscribe_prepare() function.
[in]cbCallback to be invoked when "subscribe" operation is complete.
[in]cbDataPointer 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.
Precondition
At least one topic has been configured using cc_mqtt311_client_subscribe_config_topic.
Postcondition
The handle of the "subscribe" operation can be discarded.
The provided callback will be invoked when the "subscribe" operation is complete if and only if the function returns CC_Mqtt311ErrorCode_Success.

◆ cc_mqtt311_client_subscribe_set_response_timeout()

CC_Mqtt311ErrorCode cc_mqtt311_client_subscribe_set_response_timeout ( CC_Mqtt311SubscribeHandle  handle,
unsigned  ms 
)

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

Parameters
[in]handleHandle returned by cc_mqtt311_client_subscribe_prepare() function.
[in]msResponse timeout duration in milliseconds.
Returns
Result code of the call.
Generated by doxygen 1.9.8