coreMQTT  v1.0.0
MQTT 3.1.1 Client Library
core_mqtt.h
Go to the documentation of this file.
1 /*
2  * coreMQTT v1.0.0
3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  */
22 
27 #ifndef CORE_MQTT_H
28 #define CORE_MQTT_H
29 
30 /* MQTT_DO_NOT_USE_CUSTOM_CONFIG allows building the MQTT library
31  * without a custom config. If a custom config is provided, the
32  * MQTT_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
33 #ifndef MQTT_DO_NOT_USE_CUSTOM_CONFIG
34  /* Include custom config file before other headers. */
35  #include "core_mqtt_config.h"
36 #endif
37 
38 /* Include config defaults header to get default values of configs not
39  * defined in core_mqtt_config.h file. */
41 
42 /* Include MQTT serializer library. */
43 #include "core_mqtt_serializer.h"
44 
45 /* Include transport interface. */
46 #include "transport_interface.h"
47 
54 #define MQTT_PACKET_ID_INVALID ( ( uint16_t ) 0U )
55 
56 /* Structures defined in this file. */
57 struct MQTTPubAckInfo;
58 struct MQTTContext;
59 struct MQTTDeserializedInfo;
60 
68 typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
69 
83 typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
84  struct MQTTPacketInfo * pPacketInfo,
85  struct MQTTDeserializedInfo * pDeserializedInfo );
86 
91 typedef enum MQTTConnectionStatus
92 {
96 
101 typedef enum MQTTPublishState
102 {
115 
120 typedef enum MQTTPubAckType
121 {
125  MQTTPubcomp
127 
132 typedef enum MQTTSubAckStatus
133 {
137  MQTTSubAckFailure = 0x80
139 
144 typedef struct MQTTPubAckInfo
145 {
146  uint16_t packetId;
150 
155 typedef struct MQTTContext
156 {
160  MQTTPubAckInfo_t outgoingPublishRecords[ MQTT_STATE_ARRAY_MAX_COUNT ];
161 
165  MQTTPubAckInfo_t incomingPublishRecords[ MQTT_STATE_ARRAY_MAX_COUNT ];
166 
171 
176 
180  uint16_t nextPacketId;
181 
186 
191 
196 
200  uint32_t lastPacketTime;
201 
207 
208  /* Keep alive members. */
210  uint32_t pingReqSendTimeMs;
212 } MQTTContext_t;
213 
219 typedef struct MQTTDeserializedInfo
220 {
221  uint16_t packetIdentifier;
225 
289 /* @[declare_mqtt_init] */
291  const TransportInterface_t * pTransportInterface,
292  MQTTGetCurrentTimeFunc_t getTimeFunction,
293  MQTTEventCallback_t userCallback,
294  const MQTTFixedBuffer_t * pNetworkBuffer );
295 /* @[declare_mqtt_init] */
296 
395 /* @[declare_mqtt_connect] */
397  const MQTTConnectInfo_t * pConnectInfo,
398  const MQTTPublishInfo_t * pWillInfo,
399  uint32_t timeoutMs,
400  bool * pSessionPresent );
401 /* @[declare_mqtt_connect] */
402 
452 /* @[declare_mqtt_subscribe] */
454  const MQTTSubscribeInfo_t * pSubscriptionList,
455  size_t subscriptionCount,
456  uint16_t packetId );
457 /* @[declare_mqtt_subscribe] */
458 
500 /* @[declare_mqtt_publish] */
502  const MQTTPublishInfo_t * pPublishInfo,
503  uint16_t packetId );
504 /* @[declare_mqtt_publish] */
505 
516 /* @[declare_mqtt_ping] */
517 MQTTStatus_t MQTT_Ping( MQTTContext_t * pContext );
518 /* @[declare_mqtt_ping] */
519 
568 /* @[declare_mqtt_unsubscribe] */
570  const MQTTSubscribeInfo_t * pSubscriptionList,
571  size_t subscriptionCount,
572  uint16_t packetId );
573 /* @[declare_mqtt_unsubscribe] */
574 
586 /* @[declare_mqtt_disconnect] */
588 /* @[declare_mqtt_disconnect] */
589 
633 /* @[declare_mqtt_processloop] */
635  uint32_t timeoutMs );
636 /* @[declare_mqtt_processloop] */
637 
689 /* @[declare_mqtt_receiveloop] */
691  uint32_t timeoutMs );
692 /* @[declare_mqtt_receiveloop] */
693 
701 /* @[declare_mqtt_getpacketid] */
702 uint16_t MQTT_GetPacketId( MQTTContext_t * pContext );
703 /* @[declare_mqtt_getpacketid] */
704 
747 MQTTStatus_t MQTT_MatchTopic( const char * pTopicName,
748  const uint16_t topicNameLength,
749  const char * pTopicFilter,
750  const uint16_t topicFilterLength,
751  bool * pIsMatch );
752 
835 /* @[declare_mqtt_getsubackstatuscodes] */
837  uint8_t ** pPayloadStart,
838  size_t * pPayloadSize );
839 /* @[declare_mqtt_getsubackstatuscodes] */
840 
848 /* @[declare_mqtt_status_strerror] */
849 const char * MQTT_Status_strerror( MQTTStatus_t status );
850 /* @[declare_mqtt_status_strerror] */
851 
852 #endif /* ifndef CORE_MQTT_H */
MQTTSubscribeInfo_t
MQTT SUBSCRIBE packet parameters.
Definition: core_mqtt_serializer.h:195
MQTTPublishState_t
MQTTPublishState_t
The state of QoS 1 or QoS 2 MQTT publishes, used in the state engine.
Definition: core_mqtt.h:102
MQTTConnected
@ MQTTConnected
MQTT Connection is active.
Definition: core_mqtt.h:94
MQTTEventCallback_t
void(* MQTTEventCallback_t)(struct MQTTContext *pContext, struct MQTTPacketInfo *pPacketInfo, struct MQTTDeserializedInfo *pDeserializedInfo)
Application callback for receiving incoming publishes and incoming acks.
Definition: core_mqtt.h:83
MQTTPubcomp
@ MQTTPubcomp
PUBCOMPs are sent in response to a PUBREL.
Definition: core_mqtt.h:125
MQTTConnectInfo_t
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:148
MQTT_Subscribe
MQTTStatus_t MQTT_Subscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)
Sends MQTT SUBSCRIBE for the given list of topic filters to the broker.
Definition: core_mqtt.c:1810
MQTTPubrec
@ MQTTPubrec
PUBRECs are sent in response to a QoS 2 PUBLISH.
Definition: core_mqtt.h:123
MQTTSubAckSuccessQos2
@ MQTTSubAckSuccessQos2
Success with a maximum delivery at QoS 2.
Definition: core_mqtt.h:136
MQTT_ProcessLoop
MQTTStatus_t MQTT_ProcessLoop(MQTTContext_t *pContext, uint32_t timeoutMs)
Loop to receive packets from the transport interface. Handles keep alive.
Definition: core_mqtt.c:2121
MQTTContext_t::appCallback
MQTTEventCallback_t appCallback
Callback function used to give deserialized MQTT packets to the application.
Definition: core_mqtt.h:195
core_mqtt_serializer.h
User-facing functions for serializing and deserializing MQTT 3.1.1 packets. This header should be inc...
MQTTPubRecSend
@ MQTTPubRecSend
The library will send a PUBREC for a received PUBLISH.
Definition: core_mqtt.h:106
MQTTPublishSend
@ MQTTPublishSend
The library will send an outgoing PUBLISH packet.
Definition: core_mqtt.h:104
MQTT_GetSubAckStatusCodes
MQTTStatus_t MQTT_GetSubAckStatusCodes(const MQTTPacketInfo_t *pSubackPacket, uint8_t **pPayloadStart, size_t *pPayloadSize)
Parses the payload of an MQTT SUBACK packet that contains status codes corresponding to topic filter ...
Definition: core_mqtt.c:2327
MQTTPacketInfo_t
MQTT incoming packet parameters.
Definition: core_mqtt_serializer.h:259
MQTTPuback
@ MQTTPuback
PUBACKs are sent in response to a QoS 1 PUBLISH.
Definition: core_mqtt.h:122
MQTTSubAckStatus_t
MQTTSubAckStatus_t
The status codes in the SUBACK response to a subscription request.
Definition: core_mqtt.h:133
MQTT_Connect
MQTTStatus_t MQTT_Connect(MQTTContext_t *pContext, const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, uint32_t timeoutMs, bool *pSessionPresent)
Establish an MQTT session.
Definition: core_mqtt.c:1713
MQTTFixedBuffer_t
Buffer passed to MQTT library.
Definition: core_mqtt_serializer.h:138
MQTT_Ping
MQTTStatus_t MQTT_Ping(MQTTContext_t *pContext)
Sends an MQTT PINGREQ to broker.
Definition: core_mqtt.c:1944
MQTT_GetPacketId
uint16_t MQTT_GetPacketId(MQTTContext_t *pContext)
Get a packet ID that is valid according to the MQTT 3.1.1 spec.
Definition: core_mqtt.c:2233
MQTTConnectionStatus_t
MQTTConnectionStatus_t
Values indicating if an MQTT connection exists.
Definition: core_mqtt.h:92
MQTTContext_t::lastPacketTime
uint32_t lastPacketTime
Timestamp of the last packet sent by the library.
Definition: core_mqtt.h:200
MQTTPubAckType_t
MQTTPubAckType_t
Packet types used in acknowledging QoS 1 or QoS 2 publishes.
Definition: core_mqtt.h:121
MQTTPubAckInfo_t
An element of the state engine records for QoS 1 or Qos 2 publishes.
Definition: core_mqtt.h:145
MQTTPubCompSend
@ MQTTPubCompSend
The library will send a PUBCOMP for a received PUBREL.
Definition: core_mqtt.h:108
MQTTPubCompPending
@ MQTTPubCompPending
The library is awaiting a PUBCOMP for an outgoing PUBLISH.
Definition: core_mqtt.h:112
MQTT_STATE_ARRAY_MAX_COUNT
#define MQTT_STATE_ARRAY_MAX_COUNT
Determines the maximum number of MQTT PUBLISH messages, pending acknowledgment at a time,...
Definition: core_mqtt_config_defaults.h:76
MQTTPubRelSend
@ MQTTPubRelSend
The library will send a PUBREL for a received PUBREC.
Definition: core_mqtt.h:107
MQTTPubAckSend
@ MQTTPubAckSend
The library will send a PUBACK for a received PUBLISH.
Definition: core_mqtt.h:105
MQTTSubAckSuccessQos0
@ MQTTSubAckSuccessQos0
Success with a maximum delivery at QoS 0 .
Definition: core_mqtt.h:134
MQTTGetCurrentTimeFunc_t
uint32_t(* MQTTGetCurrentTimeFunc_t)(void)
Application provided callback to retrieve the current time in milliseconds.
Definition: core_mqtt.h:68
MQTTPubAckInfo_t::packetId
uint16_t packetId
The packet ID of the original PUBLISH.
Definition: core_mqtt.h:146
MQTTDeserializedInfo_t::packetIdentifier
uint16_t packetIdentifier
Packet ID of deserialized packet.
Definition: core_mqtt.h:221
MQTTStatus_t
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:105
MQTT_MatchTopic
MQTTStatus_t MQTT_MatchTopic(const char *pTopicName, const uint16_t topicNameLength, const char *pTopicFilter, const uint16_t topicFilterLength, bool *pIsMatch)
A utility function that determines whether the passed topic filter and topic name match according to ...
Definition: core_mqtt.c:2258
MQTT_Unsubscribe
MQTTStatus_t MQTT_Unsubscribe(MQTTContext_t *pContext, const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId)
Sends MQTT UNSUBSCRIBE for the given list of topic filters to the broker.
Definition: core_mqtt.c:2005
MQTTContext_t::controlPacketSent
bool controlPacketSent
Whether the library sent a packet during a call of MQTT_ProcessLoop or MQTT_ReceiveLoop.
Definition: core_mqtt.h:206
MQTTContext_t::networkBuffer
MQTTFixedBuffer_t networkBuffer
The buffer used in sending and receiving packets from the network.
Definition: core_mqtt.h:175
MQTT_ReceiveLoop
MQTTStatus_t MQTT_ReceiveLoop(MQTTContext_t *pContext, uint32_t timeoutMs)
Loop to receive packets from the transport interface. Does not handle keep alive.
Definition: core_mqtt.c:2178
MQTTContext_t::getTime
MQTTGetCurrentTimeFunc_t getTime
Function used to get millisecond timestamps.
Definition: core_mqtt.h:190
MQTTDeserializedInfo_t::pPublishInfo
MQTTPublishInfo_t * pPublishInfo
Pointer to deserialized publish info.
Definition: core_mqtt.h:222
MQTT_Publish
MQTTStatus_t MQTT_Publish(MQTTContext_t *pContext, const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId)
Publishes a message to the given topic name.
Definition: core_mqtt.c:1870
MQTTPubAckPending
@ MQTTPubAckPending
The library is awaiting a PUBACK for an outgoing PUBLISH.
Definition: core_mqtt.h:109
MQTTContext_t
A struct representing an MQTT connection.
Definition: core_mqtt.h:156
MQTTDeserializedInfo_t::deserializationResult
MQTTStatus_t deserializationResult
Return code of deserialization.
Definition: core_mqtt.h:223
MQTT_Init
MQTTStatus_t MQTT_Init(MQTTContext_t *pContext, const TransportInterface_t *pTransportInterface, MQTTGetCurrentTimeFunc_t getTimeFunction, MQTTEventCallback_t userCallback, const MQTTFixedBuffer_t *pNetworkBuffer)
Initialize an MQTT context.
Definition: core_mqtt.c:1654
MQTTContext_t::connectStatus
MQTTConnectionStatus_t connectStatus
Whether the context currently has a connection to the broker.
Definition: core_mqtt.h:185
MQTT_Disconnect
MQTTStatus_t MQTT_Disconnect(MQTTContext_t *pContext)
Disconnect an MQTT session.
Definition: core_mqtt.c:2065
MQTTPubRecPending
@ MQTTPubRecPending
The library is awaiting a PUBREC for an outgoing PUBLISH.
Definition: core_mqtt.h:110
MQTTPublishDone
@ MQTTPublishDone
The PUBLISH has been completed.
Definition: core_mqtt.h:113
MQTTQoS_t
MQTTQoS_t
MQTT Quality of Service values.
Definition: core_mqtt_serializer.h:124
MQTTPubRelPending
@ MQTTPubRelPending
The library is awaiting a PUBREL for an incoming PUBLISH.
Definition: core_mqtt.h:111
MQTT_Status_strerror
const char * MQTT_Status_strerror(MQTTStatus_t status)
Error code to string conversion for MQTT statuses.
Definition: core_mqtt.c:2385
MQTTContext_t::transportInterface
TransportInterface_t transportInterface
The transport interface used by the MQTT connection.
Definition: core_mqtt.h:170
MQTTPubAckInfo_t::publishState
MQTTPublishState_t publishState
The current state of the publish process.
Definition: core_mqtt.h:148
MQTTSubAckSuccessQos1
@ MQTTSubAckSuccessQos1
Success with a maximum delivery at QoS 1.
Definition: core_mqtt.h:135
MQTTContext_t::keepAliveIntervalSec
uint16_t keepAliveIntervalSec
Keep Alive interval.
Definition: core_mqtt.h:209
MQTTContext_t::pingReqSendTimeMs
uint32_t pingReqSendTimeMs
Timestamp of the last sent PINGREQ.
Definition: core_mqtt.h:210
MQTTContext_t::waitingForPingResp
bool waitingForPingResp
If the library is currently awaiting a PINGRESP.
Definition: core_mqtt.h:211
MQTTContext_t::nextPacketId
uint16_t nextPacketId
The next available ID for outgoing MQTT packets.
Definition: core_mqtt.h:180
MQTTStateNull
@ MQTTStateNull
An empty state with no corresponding PUBLISH.
Definition: core_mqtt.h:103
MQTTPublishInfo_t
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:217
transport_interface.h
Transport interface definitions to send and receive data over the network.
MQTTPubAckInfo_t::qos
MQTTQoS_t qos
The QoS of the original PUBLISH.
Definition: core_mqtt.h:147
core_mqtt_config_defaults.h
This represents the default values for the configuration macros for the MQTT library.
MQTTPubrel
@ MQTTPubrel
PUBRELs are sent in response to a PUBREC.
Definition: core_mqtt.h:124
MQTTNotConnected
@ MQTTNotConnected
MQTT Connection is inactive.
Definition: core_mqtt.h:93
MQTTSubAckFailure
@ MQTTSubAckFailure
Failure.
Definition: core_mqtt.h:137
MQTTDeserializedInfo_t
Struct to hold deserialized packet information for an MQTTEventCallback_t callback.
Definition: core_mqtt.h:220
TransportInterface_t
The transport layer interface.
Definition: transport_interface.h:196