David Fletcher / Mbed 2 deprecated cc3100_Test_mqtt_CM4F

TI's MQTT Demo with freertos CM4F

Dependencies:   mbed

Embed: (wiki syntax)

« Back to documentation index

mqtt_server_msg_cbs Struct Reference
Data Fields

mqtt_server_msg_cbs Struct Reference
[The Server Library API(s)]

Working Principle for implementing the call-back services: Implementation of the call-back services should report in return value, only about errors found in the RX processing. More...

#include <server_pkts.h>

Data Fields

uint16_t(* connect_rx )(void *ctx_cl, uint8_t conn_flags, struct utf8_string *const *utf8_vec, void **usr)
 Indicate the CONNECT Message from the client This routine provides, to the application, information about the connection request that a remote client has made.
bool(* sub_msg_rx )(void *usr_cl, const struct utf8_strqos *qos_topics, uint32_t n_topics, uint16_t msg_id, uint8_t *acks)
 Indicate the SUBSCRIBE Message from the client This routine provides, to the application, information about the topics that the remote client intends to subscribe to.
bool(* un_sub_msg )(void *usr_cl, const struct utf8_string *topics, uint32_t n_topics, uint16_t msg_id)
 Indicate the UNSUBSCRIBE Message from the client This routine provides, to the application, information about the topics that the remote client intends to unsubscribe.
bool(* pub_msg_rx )(void *usr_cl, const struct utf8_string *topic, const uint8_t *data_buf, uint32_t data_len, uint16_t msg_id, bool dup, enum mqtt_qos qos, bool retain)
 Indicate the PUBLISH Message from the client.
bool(* ack_notify )(void *usr_cl, uint8_t msg_type, uint16_t msg_id)
 Notify the acknowledgement that was received from the remote client.
void(* on_cl_net_close )(void *usr_cl, bool due2err)
 Notify that network connection to client has been closed.
void(* on_connack_send )(void *usr_cl, bool clean_session)
 Notify that CONNACK has been sent to the specified client.

Detailed Description

Working Principle for implementing the call-back services: Implementation of the call-back services should report in return value, only about errors found in the RX processing.

Specifically, the status of TX as a follow-up to RX message (represented as a call-back service) need not be reported to the server packet library.

Error observed in TX (supported by appropriate API(s) / services in the service packet library) is recorded in the 'context' and shall be dealt in the next iteration of RX loop.

Definition at line 221 of file server_pkts.h.

Field Documentation

bool(* ack_notify)(void *usr_cl, uint8_t msg_type, uint16_t msg_id)

Notify the acknowledgement that was received from the remote client.

Following are the messages that are notified by the server LIB.

PUBACK, PUBREC, PUBREL, PUBCOMP

On return from this routine, if the application has found problem in processing the ACK message, then the LIB will simply terminate the associated network connection

Parameters:
[in]usr_clhandle to connection context in the application
[in]msg_typerefers to the type of ACK message
[in]msg_idthe associated message ID provided by the client
Returns:
application should return false if the ACK was not expected by it or no reference was found for it. Otherwise true.

Definition at line 351 of file server_pkts.h.

uint16_t(* connect_rx)(void *ctx_cl, uint8_t conn_flags, struct utf8_string *const *utf8_vec, void **usr)

Indicate the CONNECT Message from the client This routine provides, to the application, information about the connection request that a remote client has made.

The application should utilize the credential and other data presented by the LIB to authenticate, analyze and finally, approve or deny the request.

Application at its discretion can also imply deployment specific policies to make decision about allowing or refusing the request.

The return value of this routine is a 16bit value that commensurates with the 'variable header' of the CONNACK message. Specifically, the LSB of the 16bit return value corresponds to the 8bit 'return code' parameter in the CONNACK message and the MSB to the 'acknowledge flags'. The application must set a valid return value.

The LIB uses the return value to compose the CONNACK message to the remote client. If the LSB of return value is a 'non zero' value, then the LIB, after sending the CONNACK message to the remote client, will terminate the network connection.

Parameters:
[in]ctx_clhandle to the underlying network context in the LIB
[in]conn_flagsoptions received in CONNECT message from server
[in]utf8_vecvector / array of pointers to UTF8 information. The order of UTF8 information is client-id, will topic, will-message, user-name and pass-word. A NULL in vector element indicates absence of that particular UTF8 information.
[out]usrplace holder for application to provide connection specific handle. In subsequent calls from the implementation this handle will be passed as a parameter to enable application to refer to the particular active connection.
Returns:
16bit value for the variable header of the CONNACK message, MSB is CONNACK-Flags, LSB is CONNACK-RC

Definition at line 257 of file server_pkts.h.

void(* on_cl_net_close)(void *usr_cl, bool due2err)

Notify that network connection to client has been closed.

This routine is invoked by the LIB to declare to the application that the network connection to a particular client has been terminated and follow-up, if needed, can now commence. If configured, removal of the client session and / or dispatch of the WILL message, will be typical aspects, among others, to follow-up. The routine aids the application by indicating if an error condition had caused the closure.

This routine is invoked by the LIB irrespective of the source entity, server or client, that has caused the closure of the network.

Parameters:
[in]usr_clhandle to connection context in the application
[in]due2errhas the connection been closed due to an error?

Definition at line 367 of file server_pkts.h.

void(* on_connack_send)(void *usr_cl, bool clean_session)

Notify that CONNACK has been sent to the specified client.

This routine is invoked by the LIB to enable the application to make progress and follow-up on the session information for the particular client. Specifically, this routine facilitates the application to either delete the session or re-send / sync-up the pending messages associated with the client. The follow-up action is depenedent upon the 'clean_session' option in the CONNECT message from the client.

Parameters:
[in]usr_clhandle to connection context in the application
[in]clean_sessionwas a clean session requested in CONNECT?

Definition at line 379 of file server_pkts.h.

bool(* pub_msg_rx)(void *usr_cl, const struct utf8_string *topic, const uint8_t *data_buf, uint32_t data_len, uint16_t msg_id, bool dup, enum mqtt_qos qos, bool retain)

Indicate the PUBLISH Message from the client.

This routine provides, to the application, the binary data along-with its qualifiers and the topic to which a remote client has published data.

On return from this routine, if the application has found a problem in processing of the contents of the PUBLISH message, the LIB will simply terminate the associated network connection. Otherwise, depending upon the QoS level of the PUBLISH message, the LIB shall dispatch the ACK (PUBACK or PUBREC) to the client, thereby, relieveing the application from this support.

Parameters:
[in]usr_clhandle to connection context in the application
[in]topicUTF8 Topic Name for which data has been published
[in]data_bufthe published binary data for the topic
[in]data_lenthe length of the binary data
[in]msg_idthe associated message ID provided by the client
[in]duphas client indicated this as a duplicate message
[in]qosquality of service of the message
[in]retainshould the server retain the data?
Returns:
The application should return false, if it encounters any problem in the processing of data, topic and related resources. Otherwise, true.

Definition at line 332 of file server_pkts.h.

bool(* sub_msg_rx)(void *usr_cl, const struct utf8_strqos *qos_topics, uint32_t n_topics, uint16_t msg_id, uint8_t *acks)

Indicate the SUBSCRIBE Message from the client This routine provides, to the application, information about the topics that the remote client intends to subscribe to.

On return from this routine, if the application has found a problem in the processing of message, then the LIB will simply terminate the associated network connection.

Parameters:
[in]usr_clhandle to connection context in the application
[in]qos_topicsan array of topic along-with its qos
[in]n_topicsthe count / number of elements in the array
[in]msg_idthe associated message ID provided by the client
[in]acksplace holder array for the application to provide finalized qos for each of the subscribed topic. The order of ack is same as that of qos_topics
Returns:
The application should return false, if it encounters any problem in the processing of topic. Otherwise, true.
Note:
The memory space pointed by the 'buffer' field in the elements of 'qos_topics' array has an additional byte available beyond the size of memory indicated by the 'length' field. This extra byte can be used by the application to NUL terminate the buffer. This quirk is applicable to this routine only.

Definition at line 285 of file server_pkts.h.

bool(* un_sub_msg)(void *usr_cl, const struct utf8_string *topics, uint32_t n_topics, uint16_t msg_id)

Indicate the UNSUBSCRIBE Message from the client This routine provides, to the application, information about the topics that the remote client intends to unsubscribe.

On return from this routine, if the application has found a problem in the processing of message, then the LIB will simply terminate the associated network connection.

Parameters:
[in]usr_clhandle to connection context in the application
[in]topicsan array of topic in the message
[in]n_topicsthe count / number of elements in the array
[in]msg_idthe associated message ID provided by the client
Returns:
The application should return false, if it encounters any problem in the processing of topic. Otherwise, true.

Definition at line 304 of file server_pkts.h.

Generated on Wed Jul 13 2022 09:55:39 by  doxygen 1.7.2