Azure IoT MQTT is the MQTT interface that AzureIoT middleware depends upon. More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include "azure_iot_mqtt_port.h"
#include "azure_iot_transport_interface.h"

Go to the source code of this file.

Data Structures
struct	AzureIoTMQTTConnectInfo
	Connection info for the MQTT client. More...

struct	AzureIoTMQTTSubscribeInfo
	Subscription info for the MQTT client. More...

struct	AzureIoTMQTTPublishInfo
	Publish info for the MQTT client. More...

struct	AzureIoTMQTTDeserializedInfo
	MQTT packet deserialized info for the MQTT client. More...

struct	AzureIoTMQTTPacketInfo
	MQTT packet info for the MQTT client. More...

Macros
#define	azureiotmqttPACKET_TYPE_CONNECT ( ( uint8_t ) 0x10U )
	CONNECT (client-to-server).

#define	azureiotmqttPACKET_TYPE_CONNACK ( ( uint8_t ) 0x20U )
	CONNACK (server-to-client).

#define	azureiotmqttPACKET_TYPE_PUBLISH ( ( uint8_t ) 0x30U )
	PUBLISH (bidirectional).

#define	azureiotmqttPACKET_TYPE_PUBACK ( ( uint8_t ) 0x40U )
	PUBACK (bidirectional).

#define	azureiotmqttPACKET_TYPE_PUBREC ( ( uint8_t ) 0x50U )
	PUBREC (bidirectional).

#define	azureiotmqttPACKET_TYPE_PUBREL ( ( uint8_t ) 0x62U )
	PUBREL (bidirectional).

#define	azureiotmqttPACKET_TYPE_PUBCOMP ( ( uint8_t ) 0x70U )
	PUBCOMP (bidirectional).

#define	azureiotmqttPACKET_TYPE_SUBSCRIBE ( ( uint8_t ) 0x82U )
	SUBSCRIBE (client-to-server).

#define	azureiotmqttPACKET_TYPE_SUBACK ( ( uint8_t ) 0x90U )
	SUBACK (server-to-client).

#define	azureiotmqttPACKET_TYPE_UNSUBSCRIBE ( ( uint8_t ) 0xA2U )
	UNSUBSCRIBE (client-to-server).

#define	azureiotmqttPACKET_TYPE_UNSUBACK ( ( uint8_t ) 0xB0U )
	UNSUBACK (server-to-client).

#define	azureiotmqttPACKET_TYPE_PINGREQ ( ( uint8_t ) 0xC0U )
	PINGREQ (client-to-server).

#define	azureiotmqttPACKET_TYPE_PINGRESP ( ( uint8_t ) 0xD0U )
	PINGRESP (server-to-client).

#define	azureiotmqttPACKET_TYPE_DISCONNECT ( ( uint8_t ) 0xE0U )
	DISCONNECT (client-to-server).

#define	azureiotmqttGET_PACKET_TYPE(ucType) ( ( ucType ) & 0xF0U )
	Get the packet type according to the MQTT spec.

Typedefs
typedef enum AzureIoTMQTTQoS	AzureIoTMQTTQoS_t
	Quality of service values.

typedef enum AzureIoTMQTTSubAckStatus	AzureIoTMQTTSubAckStatus_t
	MQTT suback ack status states.

typedef enum AzureIoTMQTTResult	AzureIoTMQTTResult_t
	Result values used for Azure IoT MQTT functions.

typedef struct AzureIoTMQTTConnectInfo	AzureIoTMQTTConnectInfo_t
	Connection info for the MQTT client.

typedef struct AzureIoTMQTTSubscribeInfo	AzureIoTMQTTSubscribeInfo_t
	Subscription info for the MQTT client.

typedef struct AzureIoTMQTTPublishInfo	AzureIoTMQTTPublishInfo_t
	Publish info for the MQTT client.

typedef struct AzureIoTMQTTDeserializedInfo	AzureIoTMQTTDeserializedInfo_t
	MQTT packet deserialized info for the MQTT client.

typedef struct AzureIoTMQTTPacketInfo	AzureIoTMQTTPacketInfo_t
	MQTT packet info for the MQTT client.

typedef AzureIoTMQTT_t *	AzureIoTMQTTHandle_t
	Typedef of the MQTT client which is defined by the MQTT port.

typedef uint32_t(*	AzureIoTMQTTGetCurrentTimeFunc_t) (void)
	The time function to be used for MQTT functionality. More...

typedef void(*	AzureIoTMQTTEventCallback_t) (AzureIoTMQTTHandle_t pContext, struct AzureIoTMQTTPacketInfo pxPacketInfo, struct AzureIoTMQTTDeserializedInfo pxDeserializedInfo)
	The callback function which will be invoked on receipt of an MQTT message.

Enumerations
enum	AzureIoTMQTTQoS { eAzureIoTMQTTQoS0 = 0 , eAzureIoTMQTTQoS1 = 1 , eAzureIoTMQTTQoS2 = 2 }
	Quality of service values. More...

enum	AzureIoTMQTTSubAckStatus { eMQTTSubAckSuccessQos0 = 0x00 , eMQTTSubAckSuccessQos1 = 0x01 , eMQTTSubAckSuccessQos2 = 0x02 , eMQTTSubAckFailure = 0x80 }
	MQTT suback ack status states. More...

enum	AzureIoTMQTTResult { eAzureIoTMQTTSuccess = 0 , eAzureIoTMQTTBadParameter , eAzureIoTMQTTNoMemory , eAzureIoTMQTTSendFailed , eAzureIoTMQTTRecvFailed , eAzureIoTMQTTBadResponse , eAzureIoTMQTTServerRefused , eAzureIoTMQTTNoDataAvailable , eAzureIoTMQTTIllegalState , eAzureIoTMQTTStateCollision , eAzureIoTMQTTKeepAliveTimeout , eAzureIoTMQTTFailed }
	Result values used for Azure IoT MQTT functions. More...

Functions
AzureIoTMQTTResult_t	AzureIoTMQTT_Init (AzureIoTMQTTHandle_t xContext, const AzureIoTTransportInterface_t pxTransportInterface, AzureIoTMQTTGetCurrentTimeFunc_t xGetTimeFunction, AzureIoTMQTTEventCallback_t xUserCallback, uint8_t pucNetworkBuffer, size_t xNetworkBufferLength)
	Initialize an AzureIoTMQTT context. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_Connect (AzureIoTMQTTHandle_t xContext, const AzureIoTMQTTConnectInfo_t pxConnectInfo, const AzureIoTMQTTPublishInfo_t pxWillInfo, uint32_t ulMilliseconds, bool *pxSessionPresent)
	Establish an MQTT session. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_Subscribe (AzureIoTMQTTHandle_t xContext, const AzureIoTMQTTSubscribeInfo_t *pxSubscriptionList, size_t xSubscriptionCount, uint16_t usPacketId)
	Sends MQTT SUBSCRIBE for the given list of topic filters to the broker. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_Publish (AzureIoTMQTTHandle_t xContext, const AzureIoTMQTTPublishInfo_t *pxPublishInfo, uint16_t usPacketId)
	Publishes a message to the given topic name. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_Ping (AzureIoTMQTTHandle_t xContext)
	Sends a MQTT PINGREQ to broker. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_Unsubscribe (AzureIoTMQTTHandle_t xContext, const AzureIoTMQTTSubscribeInfo_t *pxSubscriptionList, size_t xSubscriptionCount, uint16_t usPacketId)
	Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_Disconnect (AzureIoTMQTTHandle_t xContext)
	Disconnect a MQTT session. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_ProcessLoop (AzureIoTMQTTHandle_t xContext, uint32_t ulMilliseconds)
	Loop to receive packets from the transport interface. Handles keep alive. More...

uint16_t	AzureIoTMQTT_GetPacketId (AzureIoTMQTTHandle_t xContext)
	Get a packet ID. More...

AzureIoTMQTTResult_t	AzureIoTMQTT_GetSubAckStatusCodes (const AzureIoTMQTTPacketInfo_t pxSubackPacket, uint8_t ppucPayloadStart, size_t pxPayloadSize)
	Parses the payload of a MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet. More...

Detailed Description

Azure IoT MQTT is the MQTT interface that AzureIoT middleware depends upon.

Note: This interface is private and subjected to change. Currently, there is only one implementation for this interface, which uses coreMQTT as underlying MQTT stack.

Typedef Documentation

◆ AzureIoTMQTTGetCurrentTimeFunc_t

typedef uint32_t( * AzureIoTMQTTGetCurrentTimeFunc_t) (void)

The time function to be used for MQTT functionality.

Note: Must return the time since Unix epoch.

Enumeration Type Documentation

◆ AzureIoTMQTTQoS

enum AzureIoTMQTTQoS

Quality of service values.

Enumerator
eAzureIoTMQTTQoS1	Delivery at most once.
eAzureIoTMQTTQoS2	Delivery at least once.

◆ AzureIoTMQTTResult

enum AzureIoTMQTTResult

Result values used for Azure IoT MQTT functions.

Enumerator
eAzureIoTMQTTBadParameter	Function completed successfully.
eAzureIoTMQTTNoMemory	At least one parameter was invalid.
eAzureIoTMQTTSendFailed	A provided buffer was too small.
eAzureIoTMQTTRecvFailed	The transport send function failed.
eAzureIoTMQTTBadResponse	The transport receive function failed.
eAzureIoTMQTTServerRefused	An invalid packet was received from the server.
eAzureIoTMQTTNoDataAvailable	The server refused a CONNECT or SUBSCRIBE.
eAzureIoTMQTTIllegalState	No data available from the transport interface.
eAzureIoTMQTTStateCollision	An illegal state in the state record.
eAzureIoTMQTTKeepAliveTimeout	A collision with an existing state record entry.
eAzureIoTMQTTFailed	Timeout while waiting for PINGRESP. Function failed with Unknown Error.

◆ AzureIoTMQTTSubAckStatus

enum AzureIoTMQTTSubAckStatus

MQTT suback ack status states.

Enumerator
eMQTTSubAckSuccessQos1	Success with a maximum delivery at QoS 0.
eMQTTSubAckSuccessQos2	Success with a maximum delivery at QoS 1.
eMQTTSubAckFailure	Success with a maximum delivery at QoS 2.

Function Documentation

◆ AzureIoTMQTT_Connect()

AzureIoTMQTTResult_t AzureIoTMQTT_Connect	(	AzureIoTMQTTHandle_t	xContext,
		const AzureIoTMQTTConnectInfo_t *	pxConnectInfo,
		const AzureIoTMQTTPublishInfo_t *	pxWillInfo,
		uint32_t	ulMilliseconds,
		bool *	pxSessionPresent
	)

Establish an MQTT session.

Note: Last Will and Testament is not used with Azure IoT Hub.

This function will send MQTT CONNECT packet and receive a CONNACK packet. The send and receive from the network is done through the transport interface.

Parameters

[in]	xContext	Initialized AzureIoTMQTT context.
[in]	pxConnectInfo	MQTT CONNECT packet information.
[in]	pxWillInfo	Last Will and Testament. Pass NULL if Last Will and Testament is not used.
[in]	ulMilliseconds	Maximum time in milliseconds to wait for a CONNACK packet.
[out]	pxSessionPresent	Whether a previous session was present. Only relevant if not establishing a clean session.

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_Disconnect()

AzureIoTMQTTResult_t AzureIoTMQTT_Disconnect ( AzureIoTMQTTHandle_t xContext )

Disconnect a MQTT session.

Parameters

[in] xContext Initialized AzureIoTMQTT context.

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_GetPacketId()

uint16_t AzureIoTMQTT_GetPacketId ( AzureIoTMQTTHandle_t xContext )

Get a packet ID.

Parameters

[in] xContext Initialized AzureIoTMQTT context.

Returns: A non-zero number.

◆ AzureIoTMQTT_GetSubAckStatusCodes()

AzureIoTMQTTResult_t AzureIoTMQTT_GetSubAckStatusCodes	(	const AzureIoTMQTTPacketInfo_t *	pxSubackPacket,
		uint8_t **	ppucPayloadStart,
		size_t *	pxPayloadSize
	)

Parses the payload of a MQTT SUBACK packet that contains status codes corresponding to topic filter subscription requests from the original subscribe packet.

Each return code in the SUBACK packet corresponds to a topic filter in the SUBSCRIBE Packet being acknowledged. The status codes can be one of the following:

0x00 - Success - Maximum QoS 0
0x01 - Success - Maximum QoS 1
0x02 - Success - Maximum QoS 2
0x80 - Failure Refer to AzureIoTMQTTSubAckStatus_t for the status codes.

Parameters

[in]	pxSubackPacket	The SUBACK packet whose payload is to be parsed.
[out]	ppucPayloadStart	This is populated with the starting address of the payload (or return codes for topic filters) in the SUBACK packet.
[out]	pxPayloadSize	This is populated with the size of the payload in the SUBACK packet. It represents the number of topic filters whose SUBACK status is present in the packet.

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_Init()

AzureIoTMQTTResult_t AzureIoTMQTT_Init	(	AzureIoTMQTTHandle_t	xContext,
		const AzureIoTTransportInterface_t *	pxTransportInterface,
		AzureIoTMQTTGetCurrentTimeFunc_t	xGetTimeFunction,
		AzureIoTMQTTEventCallback_t	xUserCallback,
		uint8_t *	pucNetworkBuffer,
		size_t	xNetworkBufferLength
	)

Initialize an AzureIoTMQTT context.

Note: This function is for integration of the Azure IoT middleware and the underlying MQTT stack and should in general not be invoked by applications directly.

Parameters

[in]	xContext	The AzureIoTMQTT context to initialize.
[in]	pxTransportInterface	The transport interface to use with the context.
[in]	xGetTimeFunction	The time utility function to use with the context.
[in]	xUserCallback	The user callback to use with the context to notify about incoming packet events.
[in]	pucNetworkBuffer	Network buffer provided for the context.
[in]	xNetworkBufferLength	Length of network buffer.

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_Ping()

AzureIoTMQTTResult_t AzureIoTMQTT_Ping ( AzureIoTMQTTHandle_t xContext )

Sends a MQTT PINGREQ to broker.

Parameters

[in] xContext Initialized AzureIoTMQTT context.

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_ProcessLoop()

AzureIoTMQTTResult_t AzureIoTMQTT_ProcessLoop	(	AzureIoTMQTTHandle_t	xContext,
		uint32_t	ulMilliseconds
	)

Loop to receive packets from the transport interface. Handles keep alive.

Parameters

[in]	xContext	Initialized AzureIoTMQTT context.
[in]	ulMilliseconds	Minimum time in milliseconds that the process loop will run, unless an error occurs.

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_Publish()

AzureIoTMQTTResult_t AzureIoTMQTT_Publish	(	AzureIoTMQTTHandle_t	xContext,
		const AzureIoTMQTTPublishInfo_t *	pxPublishInfo,
		uint16_t	usPacketId
	)

Publishes a message to the given topic name.

Parameters

[in]	xContext	Initialized AzureIoTMQTT context.
[in]	pxPublishInfo	MQTT PUBLISH packet parameters.
[in]	usPacketId	packet ID ( generated by AzureIoTMQTT_GetPacketId ).

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_Subscribe()

AzureIoTMQTTResult_t AzureIoTMQTT_Subscribe	(	AzureIoTMQTTHandle_t	xContext,
		const AzureIoTMQTTSubscribeInfo_t *	pxSubscriptionList,
		size_t	xSubscriptionCount,
		uint16_t	usPacketId
	)

Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.

Parameters

[in]	xContext	Initialized AzureIoTMQTT context.
[in]	pxSubscriptionList	List of MQTT subscription infos.
[in]	xSubscriptionCount	The number of elements in pxSubscriptionList.
[in]	usPacketId	Packet ID ( generated by AzureIoTMQTT_GetPacketId ).

Returns: An AzureIoTMQTTResult_t with the result of the operation.

◆ AzureIoTMQTT_Unsubscribe()

AzureIoTMQTTResult_t AzureIoTMQTT_Unsubscribe	(	AzureIoTMQTTHandle_t	xContext,
		const AzureIoTMQTTSubscribeInfo_t *	pxSubscriptionList,
		size_t	xSubscriptionCount,
		uint16_t	usPacketId
	)

Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker.

Parameters

[in]	xContext	Initialized AzureIoTMQTT context.
[in]	pxSubscriptionList	List of MQTT subscription infos.
[in]	xSubscriptionCount	The number of elements in pxSubscriptionList.
[in]	usPacketId	packet ID ( generated by AzureIoTMQTT_GetPacketId ).

Returns: An AzureIoTMQTTResult_t with the result of the operation.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ AzureIoTMQTTGetCurrentTimeFunc_t

Enumeration Type Documentation

◆ AzureIoTMQTTQoS

◆ AzureIoTMQTTResult

◆ AzureIoTMQTTSubAckStatus

Function Documentation

◆ AzureIoTMQTT_Connect()

◆ AzureIoTMQTT_Disconnect()

◆ AzureIoTMQTT_GetPacketId()

◆ AzureIoTMQTT_GetSubAckStatusCodes()

◆ AzureIoTMQTT_Init()

◆ AzureIoTMQTT_Ping()

◆ AzureIoTMQTT_ProcessLoop()

◆ AzureIoTMQTT_Publish()

◆ AzureIoTMQTT_Subscribe()

◆ AzureIoTMQTT_Unsubscribe()