wolfmqtt/wolfmqttmqtt_client.h

Classes

	Name
struct	_MqttPkRead
struct	_MqttSk
struct	_MqttClient

Types

	Name
enum	MqttClientFlags { MQTT_CLIENT_FLAG_IS_CONNECTED = 0x01, MQTT_CLIENT_FLAG_IS_TLS = 0x02}
enum	_MqttPkStat { MQTT_PK_BEGIN, MQTT_PK_READ_HEAD, MQTT_PK_READ}
typedef int()(struct _MqttClient client, MqttMessage *message, byte msg_new, byte msg_done)	MqttMsgCb Mqtt Message Callback. If the message payload is larger than the maximum RX buffer then this callback is called multiple times. If msg_new = 1 its a new message. The topic_name and topic_name length are only valid when msg_new = 1. If msg_new = 0 then we are receiving additional payload. Each callback populates the payload in MqttMessage.buffer. The MqttMessage.buffer_len is the size of the buffer payload. The MqttMessage.buffer_pos is the location in the total payload. The MqttMessage.total_len is the length of the complete payload message. If msg_done = 1 the entire publish payload has been received.
typedef int()(MqttPublish publish)	MqttPublishCb Mqtt Publish Callback. If the publish payload is larger than the maximum TX buffer then this callback is called multiple times. This callback is executed from within a call to MqttPublish. It is expected to provide a buffer and it's size and return >=0 for success. Each callback populates the payload in MqttPublish.buffer. The MqttPublish.buffer_len is the size of the buffer payload. The MqttPublish.total_len is the length of the complete payload message.
typedef enum _MqttPkStat	MqttPkStat
typedef struct _MqttPkRead	MqttPkRead
typedef struct _MqttSk	MqttSk
typedef int()(struct _MqttClient client, int error_code, void *ctx)	MqttDisconnectCb
typedef int()(struct _MqttClient client, MqttProp head, void ctx)	MqttPropertyCb
typedef int()(word16 topicId, const char topicName, void *reg_ctx)	SN_ClientRegisterCb Mqtt-SN Register Callback. A GW sends a REGISTER message to a client if it wants to inform that client about the topic name and the assigned topic id that it will use later on when sending PUBLISH messages of the corresponding topic name. This callback allows the client to accept and save the new ID, or reject it if the ID is unknown. If the callback is not defined, then the regack will contain the "unsupported" return code.
typedef struct _MqttClient	MqttClient

Functions

	Name
WOLFMQTT_API int	MqttClient_Init(MqttClient * client, MqttNet * net, MqttMsgCb msg_cb, byte * tx_buf, int tx_buf_len, byte * rx_buf, int rx_buf_len, int cmd_timeout_ms) Initializes the MqttClient structure.
WOLFMQTT_API void	MqttClient_DeInit(MqttClient * client) Cleans up resources allocated to the MqttClient structure.
WOLFMQTT_API int	MqttClient_SetDisconnectCallback(MqttClient * client, MqttDisconnectCb discb, void * ctx) Sets a disconnect callback with custom context.
WOLFMQTT_API int	MqttClient_SetPropertyCallback(MqttClient * client, MqttPropertyCb propCb, void * ctx) Sets a property callback with custom context.
WOLFMQTT_API int	MqttClient_Connect(MqttClient * client, MqttConnect * connect) Encodes and sends the MQTT Connect packet and waits for the Connect Acknowledgment packet.
WOLFMQTT_API int	MqttClient_Publish(MqttClient * client, MqttPublish * publish) Encodes and sends the MQTT Publish packet and waits for the Publish response (if QoS > 0). If the total size of the payload is larger than the buffer size, it can be called successively to transmit the full payload. (if QoS > 0)
WOLFMQTT_API int	MqttClient_Publish_ex(MqttClient * client, MqttPublish * publish, MqttPublishCb pubCb) Encodes and sends the MQTT Publish packet and waits for the Publish response (if QoS > 0). The callback function is used to copy the payload data, allowing the use of transmit buffers smaller than the total size of the payload.
WOLFMQTT_API int	MqttClient_Publish_WriteOnly(MqttClient * client, MqttPublish * publish, MqttPublishCb pubCb) Same as MqttClient_Publish_ex, however this API will only perform writes and requires another thread to handle the read ACK processing using MqttClient_WaitMessage_ex.
WOLFMQTT_API int	MqttClient_Subscribe(MqttClient * client, MqttSubscribe * subscribe) Encodes and sends the MQTT Subscribe packet and waits for the Subscribe Acknowledgment packet.
WOLFMQTT_API int	MqttClient_Unsubscribe(MqttClient * client, MqttUnsubscribe * unsubscribe) Encodes and sends the MQTT Unsubscribe packet and waits for the Unsubscribe Acknowledgment packet.
WOLFMQTT_API int	MqttClient_Ping(MqttClient * client) Encodes and sends the MQTT Ping Request packet and waits for the Ping Response packet.
WOLFMQTT_API int	MqttClient_Ping_ex(MqttClient * client, MqttPing * ping) Encodes and sends the MQTT Ping Request packet and waits for the Ping Response packet. This version takes a MqttPing structure and can be used with non-blocking applications.
WOLFMQTT_API int	MqttClient_Auth(MqttClient * client, MqttAuth * auth) Encodes and sends the MQTT Authentication Request packet and waits for the Ping Response packet.
WOLFMQTT_API MqttProp *	MqttClient_PropsAdd(MqttProp ** head) Add a new property. Allocate a property structure and add it to the head of the list pointed to by head. To be used prior to calling packet command.
WOLFMQTT_API int	MqttClient_PropsFree(MqttProp * head) Free property list. Deallocate the list pointed to by head. Must be used after the packet command that used MqttClient_Prop_Add.
WOLFMQTT_API int	MqttClient_Disconnect(MqttClient * client) Encodes and sends the MQTT Disconnect packet (no response)
WOLFMQTT_API int	MqttClient_Disconnect_ex(MqttClient * client, MqttDisconnect * disconnect) Encodes and sends the MQTT Disconnect packet (no response)
WOLFMQTT_API int	MqttClient_WaitMessage(MqttClient * client, int timeout_ms) Waits for packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init.
WOLFMQTT_API int	MqttClient_WaitMessage_ex(MqttClient * client, MqttObject * msg, int timeout_ms) Waits for packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init.
WOLFMQTT_API int	MqttClient_CancelMessage(MqttClient * client, MqttObject * msg) In a multi-threaded and non-blocking mode this allows you to cancel an MQTT object that was previously submitted.
WOLFMQTT_API int	MqttClient_IsMessageActive(MqttClient * client, MqttObject * msg) In a non_blocking mode this checks if the message has a read or write pending (state is not MQTT_MSG_BEGIN).
WOLFMQTT_API int	MqttClient_NetConnect(MqttClient * client, const char * host, word16 port, int timeout_ms, int use_tls, MqttTlsCb cb) Performs network connect with TLS (if use_tls is non_zero value) Will perform the MqttTlsCb callback if use_tls is non-zero value.
WOLFMQTT_API int	MqttClient_NetDisconnect(MqttClient * client) Performs a network disconnect.
WOLFMQTT_API int	MqttClient_GetProtocolVersion(MqttClient * client) Gets number version of connected protocol version.
WOLFMQTT_API const char *	MqttClient_GetProtocolVersionString(MqttClient * client) Gets string version of connected protocol version.
WOLFMQTT_API const char *	MqttClient_ReturnCodeToString(int return_code) Performs lookup of the WOLFMQTT_API return values.
WOLFMQTT_API int	SN_Client_SearchGW(MqttClient * client, SN_SearchGw * search) Encodes and sends the a message to search for a gateway and waits for the gateway info response message.
WOLFMQTT_API int	SN_Client_Connect(MqttClient * client, SN_Connect * connect) Encodes and sends the Connect packet and waits for the Connect Acknowledgment packet. If Will is enabled, the gateway prompts for LWT Topic and Message. Sending an empty will topic indicates that the client wishes to delete the Will topic and the Will message stored in the server.
WOLFMQTT_API int	SN_Client_WillTopicUpdate(MqttClient * client, SN_Will * will) Encodes and sends the MQTT-SN Will Topic Update packet. Sending a NULL 'will' indicates that the client wishes to delete the Will topic and the Will message stored in the server.
WOLFMQTT_API int	SN_Client_WillMsgUpdate(MqttClient * client, SN_Will * will) Encodes and sends the MQTT-SN Will Message Update packet.
WOLFMQTT_API int	SN_Client_Register(MqttClient * client, SN_Register * regist) Encodes and sends the MQTT-SN Register packet and waits for the Register Acknowledge packet. The Register packet is sent by a client to a GW for requesting a topic id value for the included topic name. It is also sent by a GW to inform a client about the topic id value it has assigned to the included topic name.
WOLFMQTT_API int	SN_Client_SetRegisterCallback(MqttClient * client, SN_ClientRegisterCb regCb, void * ctx) Sets a register callback with custom context.
WOLFMQTT_API int	SN_Client_Publish(MqttClient * client, SN_Publish * publish) Encodes and sends the MQTT_SN Publish packet and waits for the Publish response (if QoS > 0).
WOLFMQTT_API int	SN_Client_Subscribe(MqttClient * client, SN_Subscribe * subscribe) Encodes and sends the MQTT-SN Subscribe packet and waits for the Subscribe Acknowledgment packet containing the assigned topic ID.
WOLFMQTT_API int	SN_Client_Unsubscribe(MqttClient * client, SN_Unsubscribe * unsubscribe) Encodes and sends the MQTT-SN Unsubscribe packet and waits for the Unsubscribe Acknowledgment packet.
WOLFMQTT_API int	SN_Client_Disconnect(MqttClient * client) Encodes and sends the MQTT-SN Disconnect packet. Client may send the disconnect with a duration to indicate the client is entering the "asleep" state.
WOLFMQTT_API int	SN_Client_Disconnect_ex(MqttClient * client, SN_Disconnect * disconnect) Encodes and sends the MQTT-SN Disconnect packet. Client may send the disconnect with a duration to indicate the client is entering the "asleep" state.
WOLFMQTT_API int	SN_Client_Ping(MqttClient * client, SN_PingReq * ping) Encodes and sends the MQTT-SN Ping Request packet and waits for the Ping Response packet. If client is in the "asleep" state and wants to notify the gateway that it is entering the "awake" state, it should add it's client ID to the ping request.
WOLFMQTT_API int	SN_Client_WaitMessage(MqttClient * client, int timeout_ms) Waits for packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init.
WOLFMQTT_API int	SN_Client_WaitMessage_ex(MqttClient * client, SN_Object * packet_obj, int timeout_ms)

Attributes

	Name
	C

Types Documentation

enum MqttClientFlags

Enumerator	Value	Description
MQTT_CLIENT_FLAG_IS_CONNECTED	0x01
MQTT_CLIENT_FLAG_IS_TLS	0x02

enum _MqttPkStat

Enumerator	Value	Description
MQTT_PK_BEGIN
MQTT_PK_READ_HEAD
MQTT_PK_READ

typedef MqttMsgCb

typedef int(* MqttMsgCb) (struct _MqttClient *client, MqttMessage *message, byte msg_new, byte msg_done);

Mqtt Message Callback. If the message payload is larger than the maximum RX buffer then this callback is called multiple times. If msg_new = 1 its a new message. The topic_name and topic_name length are only valid when msg_new = 1. If msg_new = 0 then we are receiving additional payload. Each callback populates the payload in MqttMessage.buffer. The MqttMessage.buffer_len is the size of the buffer payload. The MqttMessage.buffer_pos is the location in the total payload. The MqttMessage.total_len is the length of the complete payload message. If msg_done = 1 the entire publish payload has been received.

Parameters:

client Pointer to MqttClient structure
message Pointer to MqttMessage structure that has been initialized with the payload properties
msg_new If non-zero value then message is new and topic name / len is provided and valid.
msg_done If non-zero value then we have received the entire message and payload.

Return: MQTT_CODE_SUCCESS to remain connected (other values will cause net disconnect - see enum MqttPacketResponseCodes)

typedef MqttPublishCb

typedef int(* MqttPublishCb) (MqttPublish *publish);

Mqtt Publish Callback. If the publish payload is larger than the maximum TX buffer then this callback is called multiple times. This callback is executed from within a call to MqttPublish. It is expected to provide a buffer and it's size and return >=0 for success. Each callback populates the payload in MqttPublish.buffer. The MqttPublish.buffer_len is the size of the buffer payload. The MqttPublish.total_len is the length of the complete payload message.

Parameters:

publish Pointer to MqttPublish structure

Return: >= 0 Indicates success

typedef MqttPkStat

typedef enum _MqttPkStat MqttPkStat;

typedef MqttPkRead

typedef struct _MqttPkRead MqttPkRead;

typedef MqttSk

typedef struct _MqttSk MqttSk;

typedef MqttDisconnectCb

typedef int(* MqttDisconnectCb) (struct _MqttClient *client, int error_code, void *ctx);

typedef MqttPropertyCb

typedef int(* MqttPropertyCb) (struct _MqttClient *client, MqttProp *head, void *ctx);

typedef SN_ClientRegisterCb

typedef int(* SN_ClientRegisterCb) (word16 topicId, const char *topicName, void *reg_ctx);

Mqtt-SN Register Callback. A GW sends a REGISTER message to a client if it wants to inform that client about the topic name and the assigned topic id that it will use later on when sending PUBLISH messages of the corresponding topic name. This callback allows the client to accept and save the new ID, or reject it if the ID is unknown. If the callback is not defined, then the regack will contain the "unsupported" return code.

Parameters:

topicId New topic ID value
topicName Pointer to topic name
reg_ctx Pointer to user context

Return: >= 0 Indicates acceptance

typedef MqttClient

typedef struct _MqttClient MqttClient;

Functions Documentation

function MqttClient_Init

WOLFMQTT_API int MqttClient_Init(
    MqttClient * client,
    MqttNet * net,
    MqttMsgCb msg_cb,
    byte * tx_buf,
    int tx_buf_len,
    byte * rx_buf,
    int rx_buf_len,
    int cmd_timeout_ms
)

Initializes the MqttClient structure.

Parameters:

client Pointer to MqttClient structure (uninitialized is okay)
net Pointer to MqttNet structure that has been initialized with callback pointers and context
msg_cb Pointer to message callback function
tx_buf Pointer to transmit buffer used during encoding
tx_buf_len Maximum length of the transmit buffer
rx_buf Pointer to receive buffer used during decoding
rx_buf_len Maximum length of the receive buffer
cmd_timeout_ms Maximum command wait timeout in milliseconds

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_BAD_ARG (see enum MqttPacketResponseCodes)

function MqttClient_DeInit

WOLFMQTT_API void MqttClient_DeInit(
    MqttClient * client
)

Cleans up resources allocated to the MqttClient structure.

Parameters:

client Pointer to MqttClient structure

Return: none

function MqttClient_SetDisconnectCallback

WOLFMQTT_API int MqttClient_SetDisconnectCallback(
    MqttClient * client,
    MqttDisconnectCb discb,
    void * ctx
)

Sets a disconnect callback with custom context.

Parameters:

client Pointer to MqttClient structure (uninitialized is okay)
discb Pointer to disconnect callback function
ctx Pointer to your own context

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_BAD_ARG (see enum MqttPacketResponseCodes)

function MqttClient_SetPropertyCallback

WOLFMQTT_API int MqttClient_SetPropertyCallback(
    MqttClient * client,
    MqttPropertyCb propCb,
    void * ctx
)

Sets a property callback with custom context.

Parameters:

client Pointer to MqttClient structure (uninitialized is okay)
propCb Pointer to property callback function
ctx Pointer to your own context

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_BAD_ARG (see enum MqttPacketResponseCodes)

function MqttClient_Connect

WOLFMQTT_API int MqttClient_Connect(
    MqttClient * client,
    MqttConnect * connect
)

Encodes and sends the MQTT Connect packet and waits for the Connect Acknowledgment packet.

Parameters:

client Pointer to MqttClient structure
connect Pointer to MqttConnect structure initialized with connect parameters

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_Publish

WOLFMQTT_API int MqttClient_Publish(
    MqttClient * client,
    MqttPublish * publish
)

Encodes and sends the MQTT Publish packet and waits for the Publish response (if QoS > 0). If the total size of the payload is larger than the buffer size, it can be called successively to transmit the full payload. (if QoS > 0)

Parameters:

client Pointer to MqttClient structure
publish Pointer to MqttPublish structure initialized with message data Note: MqttPublish and MqttMessage are same structure.

See:

Return: MQTT_CODE_SUCCESS, MQTT_CODE_CONTINUE (for non-blocking) or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This function that will wait for MqttNet.read to complete, timeout or MQTT_CODE_CONTINUE if non-blocking. If QoS level = 1 then will wait for PUBLISH_ACK. If QoS level = 2 then will wait for PUBLISH_REC then send PUBLISH_REL and wait for PUBLISH_COMP.

function MqttClient_Publish_ex

WOLFMQTT_API int MqttClient_Publish_ex(
    MqttClient * client,
    MqttPublish * publish,
    MqttPublishCb pubCb
)

Encodes and sends the MQTT Publish packet and waits for the Publish response (if QoS > 0). The callback function is used to copy the payload data, allowing the use of transmit buffers smaller than the total size of the payload.

Parameters:

client Pointer to MqttClient structure
publish Pointer to MqttPublish structure initialized with message data Note: MqttPublish and MqttMessage are same structure.
pubCb Function pointer to callback routine

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This function that will wait for MqttNet.read to complete, timeout or MQTT_CODE_CONTINUE if non-blocking. If QoS level = 1 then will wait for PUBLISH_ACK. If QoS level = 2 then will wait for PUBLISH_REC then send PUBLISH_REL and wait for PUBLISH_COMP.

function MqttClient_Publish_WriteOnly

WOLFMQTT_API int MqttClient_Publish_WriteOnly(
    MqttClient * client,
    MqttPublish * publish,
    MqttPublishCb pubCb
)

Same as MqttClient_Publish_ex, however this API will only perform writes and requires another thread to handle the read ACK processing using MqttClient_WaitMessage_ex.

Parameters:

client Pointer to MqttClient structure
publish Pointer to MqttPublish structure initialized with message data Note: MqttPublish and MqttMessage are same structure.

See:

Return: MQTT_CODE_SUCCESS, MQTT_CODE_CONTINUE (for non-blocking) or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This function that will wait for MqttNet.read to complete, timeout or MQTT_CODE_CONTINUE if non-blocking. If QoS level = 1 then will wait for PUBLISH_ACK. If QoS level = 2 then will wait for PUBLISH_REC then send PUBLISH_REL and wait for PUBLISH_COMP.

function MqttClient_Subscribe

WOLFMQTT_API int MqttClient_Subscribe(
    MqttClient * client,
    MqttSubscribe * subscribe
)

Encodes and sends the MQTT Subscribe packet and waits for the Subscribe Acknowledgment packet.

Parameters:

client Pointer to MqttClient structure
subscribe Pointer to MqttSubscribe structure initialized with subscription topic list and desired QoS.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_Unsubscribe

WOLFMQTT_API int MqttClient_Unsubscribe(
    MqttClient * client,
    MqttUnsubscribe * unsubscribe
)

Encodes and sends the MQTT Unsubscribe packet and waits for the Unsubscribe Acknowledgment packet.

Parameters:

client Pointer to MqttClient structure
unsubscribe Pointer to MqttUnsubscribe structure initialized with topic list.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_Ping

WOLFMQTT_API int MqttClient_Ping(
    MqttClient * client
)

Encodes and sends the MQTT Ping Request packet and waits for the Ping Response packet.

Parameters:

client Pointer to MqttClient structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_Ping_ex

WOLFMQTT_API int MqttClient_Ping_ex(
    MqttClient * client,
    MqttPing * ping
)

Encodes and sends the MQTT Ping Request packet and waits for the Ping Response packet. This version takes a MqttPing structure and can be used with non-blocking applications.

Parameters:

client Pointer to MqttClient structure
ping Pointer to MqttPing structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_Auth

WOLFMQTT_API int MqttClient_Auth(
    MqttClient * client,
    MqttAuth * auth
)

Encodes and sends the MQTT Authentication Request packet and waits for the Ping Response packet.

Parameters:

client Pointer to MqttClient structure
auth Pointer to MqttAuth structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_PropsAdd

WOLFMQTT_API MqttProp * MqttClient_PropsAdd(
    MqttProp ** head
)

Add a new property. Allocate a property structure and add it to the head of the list pointed to by head. To be used prior to calling packet command.

Parameters:

head Pointer-pointer to a property structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_BAD_ARG

function MqttClient_PropsFree

WOLFMQTT_API int MqttClient_PropsFree(
    MqttProp * head
)

Free property list. Deallocate the list pointed to by head. Must be used after the packet command that used MqttClient_Prop_Add.

Parameters:

head Pointer-pointer to a property structure

Return: MQTT_CODE_SUCCESS or -1 on error (and sets errno)

function MqttClient_Disconnect

WOLFMQTT_API int MqttClient_Disconnect(
    MqttClient * client
)

Encodes and sends the MQTT Disconnect packet (no response)

Parameters:

client Pointer to MqttClient structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a non-blocking function that will try and send using MqttNet.write

function MqttClient_Disconnect_ex

WOLFMQTT_API int MqttClient_Disconnect_ex(
    MqttClient * client,
    MqttDisconnect * disconnect
)

Encodes and sends the MQTT Disconnect packet (no response)

Parameters:

client Pointer to MqttClient structure
disconnect Pointer to MqttDisconnect structure. NULL is valid.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a non-blocking function that will try and send using MqttNet.write

function MqttClient_WaitMessage

WOLFMQTT_API int MqttClient_WaitMessage(
    MqttClient * client,
    int timeout_ms
)

Waits for packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init.

Parameters:

client Pointer to MqttClient structure
timeout_ms Milliseconds until read timeout

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_WaitMessage_ex

WOLFMQTT_API int MqttClient_WaitMessage_ex(
    MqttClient * client,
    MqttObject * msg,
    int timeout_ms
)

Waits for packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init.

Parameters:

client Pointer to MqttClient structure
msg Pointer to MqttObject structure
timeout_ms Milliseconds until read timeout

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_CancelMessage

WOLFMQTT_API int MqttClient_CancelMessage(
    MqttClient * client,
    MqttObject * msg
)

In a multi-threaded and non-blocking mode this allows you to cancel an MQTT object that was previously submitted.

Parameters:

client Pointer to MqttClient structure
msg Pointer to MqttObject structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function MqttClient_IsMessageActive

WOLFMQTT_API int MqttClient_IsMessageActive(
    MqttClient * client,
    MqttObject * msg
)

In a non-blocking mode this checks if the message has a read or write pending (state is not MQTT_MSG_BEGIN).

Parameters:

client Pointer to MqttClient structure
msg Pointer to MqttObject structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This function assumes caller owns the object

function MqttClient_NetConnect

WOLFMQTT_API int MqttClient_NetConnect(
    MqttClient * client,
    const char * host,
    word16 port,
    int timeout_ms,
    int use_tls,
    MqttTlsCb cb
)

Performs network connect with TLS (if use_tls is non-zero value) Will perform the MqttTlsCb callback if use_tls is non-zero value.

Parameters:

client Pointer to MqttClient structure
host Address of the broker server
port Optional custom port. If zero will use defaults
use_tls If non-zero value will connect with and use TLS for encryption of data
cb A function callback for configuration of the SSL context certificate checking
timeout_ms Milliseconds until read timeout

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

function MqttClient_NetDisconnect

WOLFMQTT_API int MqttClient_NetDisconnect(
    MqttClient * client
)

Performs a network disconnect.

Parameters:

client Pointer to MqttClient structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

function MqttClient_GetProtocolVersion

WOLFMQTT_API int MqttClient_GetProtocolVersion(
    MqttClient * client
)

Gets number version of connected protocol version.

Parameters:

client Pointer to MqttClient structure

Return: 4 (v3.1.1) or 5 (v5)

function MqttClient_GetProtocolVersionString

WOLFMQTT_API const char * MqttClient_GetProtocolVersionString(
    MqttClient * client
)

Gets string version of connected protocol version.

Parameters:

client Pointer to MqttClient structure

Return: String v3.1.1 or v5

function MqttClient_ReturnCodeToString

WOLFMQTT_API const char * MqttClient_ReturnCodeToString(
    int return_code
)

Performs lookup of the WOLFMQTT_API return values.

Parameters:

return_code The return value from a WOLFMQTT_API function

Return: String representation of the return code

function SN_Client_SearchGW

WOLFMQTT_API int SN_Client_SearchGW(
    MqttClient * client,
    SN_SearchGw * search
)

Encodes and sends the a message to search for a gateway and waits for the gateway info response message.

Parameters:

client Pointer to MqttClient structure
search Pointer to SN_SearchGW structure initialized with hop radius.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_Connect

WOLFMQTT_API int SN_Client_Connect(
    MqttClient * client,
    SN_Connect * connect
)

Encodes and sends the Connect packet and waits for the Connect Acknowledgment packet. If Will is enabled, the gateway prompts for LWT Topic and Message. Sending an empty will topic indicates that the client wishes to delete the Will topic and the Will message stored in the server.

Parameters:

client Pointer to MqttClient structure
connect Pointer to SN_Connect structure initialized with connect parameters

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_WillTopicUpdate

WOLFMQTT_API int SN_Client_WillTopicUpdate(
    MqttClient * client,
    SN_Will * will
)

Encodes and sends the MQTT-SN Will Topic Update packet. Sending a NULL 'will' indicates that the client wishes to delete the Will topic and the Will message stored in the server.

Parameters:

client Pointer to MqttClient structure
will Pointer to SN_Will structure initialized with topic and message parameters. NULL is valid.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_WillMsgUpdate

WOLFMQTT_API int SN_Client_WillMsgUpdate(
    MqttClient * client,
    SN_Will * will
)

Encodes and sends the MQTT-SN Will Message Update packet.

Parameters:

client Pointer to MqttClient structure
will Pointer to SN_Will structure initialized with topic and message parameters. NULL is valid.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_Register

WOLFMQTT_API int SN_Client_Register(
    MqttClient * client,
    SN_Register * regist
)

Encodes and sends the MQTT-SN Register packet and waits for the Register Acknowledge packet. The Register packet is sent by a client to a GW for requesting a topic id value for the included topic name. It is also sent by a GW to inform a client about the topic id value it has assigned to the included topic name.

Parameters:

client Pointer to MqttClient structure
regist Pointer to SN_Register structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_SetRegisterCallback

WOLFMQTT_API int SN_Client_SetRegisterCallback(
    MqttClient * client,
    SN_ClientRegisterCb regCb,
    void * ctx
)

Sets a register callback with custom context.

Parameters:

client Pointer to MqttClient structure (uninitialized is okay)
regCb Pointer to register callback function
ctx Pointer to your own context

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_BAD_ARG

function SN_Client_Publish

WOLFMQTT_API int SN_Client_Publish(
    MqttClient * client,
    SN_Publish * publish
)

Encodes and sends the MQTT-SN Publish packet and waits for the Publish response (if QoS > 0).

Parameters:

client Pointer to MqttClient structure
publish Pointer to SN_Publish structure initialized with message data Note: SN_Publish and MqttMessage are same structure.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read If QoS level = 1 then will wait for PUBLISH_ACK. If QoS level = 2 then will wait for PUBLISH_REC then send PUBLISH_REL and wait for PUBLISH_COMP.

function SN_Client_Subscribe

WOLFMQTT_API int SN_Client_Subscribe(
    MqttClient * client,
    SN_Subscribe * subscribe
)

Encodes and sends the MQTT-SN Subscribe packet and waits for the Subscribe Acknowledgment packet containing the assigned topic ID.

Parameters:

client Pointer to MqttClient structure
subscribe Pointer to SN_Subscribe structure initialized with subscription topic list and desired QoS.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_Unsubscribe

WOLFMQTT_API int SN_Client_Unsubscribe(
    MqttClient * client,
    SN_Unsubscribe * unsubscribe
)

Encodes and sends the MQTT-SN Unsubscribe packet and waits for the Unsubscribe Acknowledgment packet.

Parameters:

client Pointer to MqttClient structure
unsubscribe Pointer to SN_Unsubscribe structure initialized with topic ID.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_Disconnect

WOLFMQTT_API int SN_Client_Disconnect(
    MqttClient * client
)

Encodes and sends the MQTT-SN Disconnect packet. Client may send the disconnect with a duration to indicate the client is entering the "asleep" state.

Parameters:

client Pointer to MqttClient structure

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a non-blocking function that will try and send using MqttNet.write

function SN_Client_Disconnect_ex

WOLFMQTT_API int SN_Client_Disconnect_ex(
    MqttClient * client,
    SN_Disconnect * disconnect
)

Encodes and sends the MQTT-SN Disconnect packet. Client may send the disconnect with a duration to indicate the client is entering the "asleep" state.

Parameters:

client Pointer to MqttClient structure
disconnect Pointer to SN_Disconnect structure. NULL is valid.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a non-blocking function that will try and send using MqttNet.write

function SN_Client_Ping

WOLFMQTT_API int SN_Client_Ping(
    MqttClient * client,
    SN_PingReq * ping
)

Encodes and sends the MQTT-SN Ping Request packet and waits for the Ping Response packet. If client is in the "asleep" state and wants to notify the gateway that it is entering the "awake" state, it should add it's client ID to the ping request.

Parameters:

client Pointer to MqttClient structure
ping Pointer to SN_PingReq structure. NULL is valid.

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_WaitMessage

WOLFMQTT_API int SN_Client_WaitMessage(
    MqttClient * client,
    int timeout_ms
)

Waits for packets to arrive. Incoming publish messages will arrive via callback provided in MqttClient_Init.

Parameters:

client Pointer to MqttClient structure
timeout_ms Milliseconds until read timeout

Return: MQTT_CODE_SUCCESS or MQTT_CODE_ERROR_* (see enum MqttPacketResponseCodes)

Note: This is a blocking function that will wait for MqttNet.read

function SN_Client_WaitMessage_ex

WOLFMQTT_API int SN_Client_WaitMessage_ex(
    MqttClient * client,
    SN_Object * packet_obj,
    int timeout_ms
)

Attributes Documentation

variable C

C {
#endif


#if !defined(WOLFMQTT_USER_SETTINGS) && \
    !defined(_WIN32) && !defined(USE_WINDOWS_API)

    #include <wolfmqtt/options.h>
#endif
#include "wolfmqttmqtt_types.h"
#include "wolfmqttmqtt_packet.h"
#include "wolfmqttmqtt_socket.h"


#ifndef WOLFMQTT_USE_CB_ON_DISCONNECT
    #undef WOLFMQTT_USE_CB_ON_DISCONNECT

#endif

#if defined(WOLFMQTT_PROPERTY_CB) && !defined(WOLFMQTT_V5)
    #error "WOLFMQTT_V5 must be defined to use WOLFMQTT_PROPERTY_CB"
#endif

struct _MqttClient;

Source code

/* mqtt_client.h
 *
 * Copyright (C) 2006-2023 wolfSSL Inc.
 *
 * This file is part of wolfMQTT.
 *
 * wolfMQTT is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * wolfMQTT is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1335, USA
 */

/* Implementation by: David Garske
 * Based on specification for MQTT v3.1.1
 * See http://mqtt.org/documentation for additional MQTT documentation.
 */

#ifndef WOLFMQTT_CLIENT_H
#define WOLFMQTT_CLIENT_H

#ifdef __cplusplus
    extern "C" {
#endif

/* Windows uses the vs_settings.h file included vis mqtt_types.h */
#if !defined(WOLFMQTT_USER_SETTINGS) && \
    !defined(_WIN32) && !defined(USE_WINDOWS_API)
    /* If options.h is missing use the "./configure" script. Otherwise, copy
     * the template "wolfmqtt/options.h.in" into "wolfmqtt/options.h" */
    #include <wolfmqtt/options.h>
#endif
#include "wolfmqttmqtt_types.h"
#include "wolfmqttmqtt_packet.h"
#include "wolfmqttmqtt_socket.h"

/* This macro allows the disconnect callback to be triggered when
 * MqttClient_Disconnect_ex is called. Normally the CB is only used to handle
 * errors from MqttPacket_HandleNetError.
 */
#ifndef WOLFMQTT_USE_CB_ON_DISCONNECT
    #undef WOLFMQTT_USE_CB_ON_DISCONNECT
    /* #define WOLFMQTT_USE_CB_ON_DISCONNECT */
#endif

#if defined(WOLFMQTT_PROPERTY_CB) && !defined(WOLFMQTT_V5)
    #error "WOLFMQTT_V5 must be defined to use WOLFMQTT_PROPERTY_CB"
#endif

struct _MqttClient;

typedef int (*MqttMsgCb)(struct _MqttClient *client, MqttMessage *message,
    byte msg_new, byte msg_done);

typedef int (*MqttPublishCb)(MqttPublish* publish);

/* Client flags */
enum MqttClientFlags {
    MQTT_CLIENT_FLAG_IS_CONNECTED = 0x01,
    MQTT_CLIENT_FLAG_IS_TLS = 0x02
};

typedef enum _MqttPkStat {
    MQTT_PK_BEGIN,
    MQTT_PK_READ_HEAD,
    MQTT_PK_READ
} MqttPkStat;

typedef struct _MqttPkRead {
    MqttPkStat stat;
    int header_len;
    int remain_len;
    int buf_len;
} MqttPkRead;

typedef struct _MqttSk {
    int pos;
    int len;
} MqttSk;

#ifdef WOLFMQTT_DISCONNECT_CB
    typedef int (*MqttDisconnectCb)(struct _MqttClient* client, int error_code, void* ctx);
#endif
#ifdef WOLFMQTT_PROPERTY_CB
    typedef int (*MqttPropertyCb)(struct _MqttClient* client, MqttProp* head, void* ctx);
#endif
#ifdef WOLFMQTT_SN
    typedef int (*SN_ClientRegisterCb)(word16 topicId, const char* topicName, void *reg_ctx);
#endif

/* Client structure */
typedef struct _MqttClient {
    word32       flags; /* MqttClientFlags */
    int          cmd_timeout_ms;

    byte        *tx_buf;
    int          tx_buf_len;
    byte        *rx_buf;
    int          rx_buf_len;

    MqttNet     *net;   /* Pointer to network callbacks and context */
#ifdef ENABLE_MQTT_TLS
    MqttTls      tls;   /* WolfSSL context for TLS */
#endif

    MqttPkRead   packet; /* publish packet state - protected by read lock */
    MqttPublishResp packetAck; /* publish ACK - protected by write lock */
    MqttSk       read;   /* read socket state - protected by read lock */
    MqttSk       write;  /* write socket state - protected by write lock */

    MqttMsgCb    msg_cb;
    MqttObject   msg;   /* generic incoming message used by MqttClient_WaitType */
#ifdef WOLFMQTT_SN
    SN_Object    msgSN;
    SN_ClientRegisterCb reg_cb;
    void               *reg_ctx;
#endif
    void*        ctx;   /* user supplied context for publish callbacks */

#ifdef WOLFMQTT_V5
    word32 packet_sz_max; /* Server property */
    byte   max_qos;       /* Server property */
    byte   retain_avail;  /* Server property */
    byte   enable_eauth;  /* Enhanced authentication */
    byte   protocol_level;
#endif

#ifdef WOLFMQTT_DISCONNECT_CB
    MqttDisconnectCb disconnect_cb;
    void            *disconnect_ctx;
#endif
#ifdef WOLFMQTT_PROPERTY_CB
    MqttPropertyCb property_cb;
    void          *property_ctx;
#endif
#ifdef WOLFMQTT_MULTITHREAD
    wm_Sem lockSend;
    wm_Sem lockRecv;
    wm_Sem lockClient;
    struct _MqttPendResp* firstPendResp; /* protected with client lock */
    struct _MqttPendResp* lastPendResp;  /* protected with client lock */
#endif
#if defined(WOLFMQTT_NONBLOCK) && defined(WOLFMQTT_DEBUG_CLIENT)
    int lastRc;
#endif
} MqttClient;


/* Application Interfaces */

WOLFMQTT_API int MqttClient_Init(
    MqttClient *client,
    MqttNet *net,
    MqttMsgCb msg_cb,
    byte *tx_buf, int tx_buf_len,
    byte *rx_buf, int rx_buf_len,
    int cmd_timeout_ms);

WOLFMQTT_API void MqttClient_DeInit(MqttClient *client);

#ifdef WOLFMQTT_DISCONNECT_CB
WOLFMQTT_API int MqttClient_SetDisconnectCallback(
    MqttClient *client,
    MqttDisconnectCb discb,
    void* ctx);
#endif

#ifdef WOLFMQTT_PROPERTY_CB
WOLFMQTT_API int MqttClient_SetPropertyCallback(
    MqttClient *client,
    MqttPropertyCb propCb,
    void* ctx);
#endif

WOLFMQTT_API int MqttClient_Connect(
    MqttClient *client,
    MqttConnect *connect);

WOLFMQTT_API int MqttClient_Publish(
    MqttClient *client,
    MqttPublish *publish);

WOLFMQTT_API int MqttClient_Publish_ex(
    MqttClient *client,
    MqttPublish *publish,
    MqttPublishCb pubCb);


#ifdef WOLFMQTT_MULTITHREAD
WOLFMQTT_API int MqttClient_Publish_WriteOnly(
    MqttClient *client,
    MqttPublish *publish,
    MqttPublishCb pubCb);
#endif

WOLFMQTT_API int MqttClient_Subscribe(
    MqttClient *client,
    MqttSubscribe *subscribe);

WOLFMQTT_API int MqttClient_Unsubscribe(
    MqttClient *client,
    MqttUnsubscribe *unsubscribe);

WOLFMQTT_API int MqttClient_Ping(
    MqttClient *client);

WOLFMQTT_API int MqttClient_Ping_ex(MqttClient *client, MqttPing* ping);

#ifdef WOLFMQTT_V5
WOLFMQTT_API int MqttClient_Auth(
    MqttClient *client,
    MqttAuth *auth);


WOLFMQTT_API MqttProp* MqttClient_PropsAdd(
    MqttProp **head);

WOLFMQTT_API int MqttClient_PropsFree(
    MqttProp *head);
#endif


WOLFMQTT_API int MqttClient_Disconnect(
    MqttClient *client);


WOLFMQTT_API int MqttClient_Disconnect_ex(
    MqttClient *client,
    MqttDisconnect *disconnect);


WOLFMQTT_API int MqttClient_WaitMessage(
    MqttClient *client,
    int timeout_ms);

WOLFMQTT_API int MqttClient_WaitMessage_ex(
    MqttClient *client,
    MqttObject *msg,
    int timeout_ms);

#if defined(WOLFMQTT_MULTITHREAD) || defined(WOLFMQTT_NONBLOCK)
WOLFMQTT_API int MqttClient_CancelMessage(
    MqttClient *client,
    MqttObject *msg);
#endif

#ifdef WOLFMQTT_NONBLOCK
WOLFMQTT_API int MqttClient_IsMessageActive(
    MqttClient *client,
    MqttObject *msg);
#endif /* WOLFMQTT_NONBLOCK */

WOLFMQTT_API int MqttClient_NetConnect(
    MqttClient *client,
    const char *host,
    word16 port,
    int timeout_ms,
    int use_tls,
    MqttTlsCb cb);

WOLFMQTT_API int MqttClient_NetDisconnect(
    MqttClient *client);

WOLFMQTT_API int MqttClient_GetProtocolVersion(MqttClient *client);

WOLFMQTT_API const char* MqttClient_GetProtocolVersionString(MqttClient *client);

#ifndef WOLFMQTT_NO_ERROR_STRINGS
WOLFMQTT_API const char* MqttClient_ReturnCodeToString(
    int return_code);
#else
    #define MqttClient_ReturnCodeToString(x) \
                                        "not compiled in"
#endif /* WOLFMQTT_NO_ERROR_STRINGS */

#ifdef WOLFMQTT_SN
WOLFMQTT_API int SN_Client_SearchGW(
        MqttClient *client,
        SN_SearchGw *search);

WOLFMQTT_API int SN_Client_Connect(
    MqttClient *client,
    SN_Connect *connect);

WOLFMQTT_API int SN_Client_WillTopicUpdate(MqttClient *client, SN_Will *will);

WOLFMQTT_API int SN_Client_WillMsgUpdate(MqttClient *client, SN_Will *will);

WOLFMQTT_API int SN_Client_Register(
    MqttClient *client,
    SN_Register *regist);


WOLFMQTT_API int SN_Client_SetRegisterCallback(
    MqttClient *client,
    SN_ClientRegisterCb regCb,
    void* ctx);


WOLFMQTT_API int SN_Client_Publish(
    MqttClient *client,
    SN_Publish *publish);

WOLFMQTT_API int SN_Client_Subscribe(
    MqttClient *client,
    SN_Subscribe *subscribe);

WOLFMQTT_API int SN_Client_Unsubscribe(
    MqttClient *client,
    SN_Unsubscribe *unsubscribe);

WOLFMQTT_API int SN_Client_Disconnect(
    MqttClient *client);

WOLFMQTT_API int SN_Client_Disconnect_ex(
    MqttClient *client,
    SN_Disconnect *disconnect);


WOLFMQTT_API int SN_Client_Ping(
    MqttClient *client,
    SN_PingReq *ping);

WOLFMQTT_API int SN_Client_WaitMessage(
    MqttClient *client,
    int timeout_ms);

WOLFMQTT_API int SN_Client_WaitMessage_ex(MqttClient *client, SN_Object* packet_obj,
    int timeout_ms);

#endif /* WOLFMQTT_SN */

#ifdef __cplusplus
    } /* extern "C" */
#endif

#endif /* WOLFMQTT_CLIENT_H */

Updated on 2023-06-04 at 08:33:10 +0000