coreMQTT v2.1.1
MQTT 3.1.1 Client Library
core_mqtt.h
Go to the documentation of this file.
1/*
2 * coreMQTT v2.1.1
3 * Copyright (C) 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 */
24
29#ifndef CORE_MQTT_H
30#define CORE_MQTT_H
31
32/* *INDENT-OFF* */
33#ifdef __cplusplus
34 extern "C" {
35#endif
36/* *INDENT-ON* */
37
38/* Include MQTT serializer library. */
40
41/* Include transport interface. */
42#include "transport_interface.h"
43
48#define MQTT_LIBRARY_VERSION "v2.1.1"
57#define MQTT_PACKET_ID_INVALID ( ( uint16_t ) 0U )
58
59/* Structures defined in this file. */
60struct MQTTPubAckInfo;
61struct MQTTContext;
62struct MQTTDeserializedInfo;
63
74typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
75
89typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
90 struct MQTTPacketInfo * pPacketInfo,
91 struct MQTTDeserializedInfo * pDeserializedInfo );
92
97typedef enum MQTTConnectionStatus
98{
102
107typedef enum MQTTPublishState
108{
121
126typedef enum MQTTPubAckType
127{
133
138typedef enum MQTTSubAckStatus
139{
143 MQTTSubAckFailure = 0x80
145
150typedef struct MQTTPubAckInfo
151{
152 uint16_t packetId;
156
161typedef struct MQTTContext
162{
167
172
177
182
187
192
196 uint16_t nextPacketId;
197
202
207
212
217
222
228
232 size_t index;
233
234 /* Keep alive members. */
239
245typedef struct MQTTDeserializedInfo
246{
251
325/* @[declare_mqtt_init] */
327 const TransportInterface_t * pTransportInterface,
328 MQTTGetCurrentTimeFunc_t getTimeFunction,
329 MQTTEventCallback_t userCallback,
330 const MQTTFixedBuffer_t * pNetworkBuffer );
331/* @[declare_mqtt_init] */
332
398/* @[declare_mqtt_initstatefulqos] */
400 MQTTPubAckInfo_t * pOutgoingPublishRecords,
401 size_t outgoingPublishCount,
402 MQTTPubAckInfo_t * pIncomingPublishRecords,
403 size_t incomingPublishCount );
404/* @[declare_mqtt_initstatefulqos] */
405
509/* @[declare_mqtt_connect] */
511 const MQTTConnectInfo_t * pConnectInfo,
512 const MQTTPublishInfo_t * pWillInfo,
513 uint32_t timeoutMs,
514 bool * pSessionPresent );
515/* @[declare_mqtt_connect] */
516
567/* @[declare_mqtt_subscribe] */
569 const MQTTSubscribeInfo_t * pSubscriptionList,
570 size_t subscriptionCount,
571 uint16_t packetId );
572/* @[declare_mqtt_subscribe] */
573
615/* @[declare_mqtt_publish] */
617 const MQTTPublishInfo_t * pPublishInfo,
618 uint16_t packetId );
619/* @[declare_mqtt_publish] */
620
638/* @[declare_mqtt_cancelcallback] */
640 uint16_t packetId );
641/* @[declare_mqtt_cancelcallback] */
642
653/* @[declare_mqtt_ping] */
655/* @[declare_mqtt_ping] */
656
705/* @[declare_mqtt_unsubscribe] */
707 const MQTTSubscribeInfo_t * pSubscriptionList,
708 size_t subscriptionCount,
709 uint16_t packetId );
710/* @[declare_mqtt_unsubscribe] */
711
723/* @[declare_mqtt_disconnect] */
725/* @[declare_mqtt_disconnect] */
726
781/* @[declare_mqtt_processloop] */
783/* @[declare_mqtt_processloop] */
784
845/* @[declare_mqtt_receiveloop] */
847/* @[declare_mqtt_receiveloop] */
848
856/* @[declare_mqtt_getpacketid] */
857uint16_t MQTT_GetPacketId( MQTTContext_t * pContext );
858/* @[declare_mqtt_getpacketid] */
859
904MQTTStatus_t MQTT_MatchTopic( const char * pTopicName,
905 const uint16_t topicNameLength,
906 const char * pTopicFilter,
907 const uint16_t topicFilterLength,
908 bool * pIsMatch );
909
992/* @[declare_mqtt_getsubackstatuscodes] */
994 uint8_t ** pPayloadStart,
995 size_t * pPayloadSize );
996/* @[declare_mqtt_getsubackstatuscodes] */
997
1005/* @[declare_mqtt_status_strerror] */
1006const char * MQTT_Status_strerror( MQTTStatus_t status );
1007/* @[declare_mqtt_status_strerror] */
1008
1009/* *INDENT-OFF* */
1010#ifdef __cplusplus
1011 }
1012#endif
1013/* *INDENT-ON* */
1014
1015#endif /* ifndef CORE_MQTT_H */
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:3099
const char * MQTT_Status_strerror(MQTTStatus_t status)
Error code to string conversion for MQTT statuses.
Definition: core_mqtt.c:3256
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:2742
MQTTStatus_t MQTT_CancelCallback(const MQTTContext_t *pContext, uint16_t packetId)
Cancels an outgoing publish callback (only for QoS > QoS0) by removing it from the pending ACK list.
Definition: core_mqtt.c:2584
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:2698
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:3128
MQTTStatus_t MQTT_Ping(MQTTContext_t *pContext)
Sends an MQTT PINGREQ to broker.
Definition: core_mqtt.c:2850
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:2927
MQTTStatus_t MQTT_ProcessLoop(MQTTContext_t *pContext)
Loop to receive packets from the transport interface. Handles keep alive.
Definition: core_mqtt.c:3046
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:3197
MQTTStatus_t MQTT_Disconnect(MQTTContext_t *pContext)
Disconnect an MQTT session.
Definition: core_mqtt.c:2972
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:2468
MQTTStatus_t MQTT_ReceiveLoop(MQTTContext_t *pContext)
Loop to receive packets from the transport interface. Does not handle keep alive.
Definition: core_mqtt.c:3073
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:2616
MQTTStatus_t MQTT_InitStatefulQoS(MQTTContext_t *pContext, MQTTPubAckInfo_t *pOutgoingPublishRecords, size_t outgoingPublishCount, MQTTPubAckInfo_t *pIncomingPublishRecords, size_t incomingPublishCount)
Initialize an MQTT context for QoS > 0.
Definition: core_mqtt.c:2527
User-facing functions for serializing and deserializing MQTT 3.1.1 packets. This header should be inc...
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:89
uint32_t(* MQTTGetCurrentTimeFunc_t)(void)
Application provided function to query the time elapsed since a given epoch in milliseconds.
Definition: core_mqtt.h:74
MQTTPublishState_t
The state of QoS 1 or QoS 2 MQTT publishes, used in the state engine.
Definition: core_mqtt.h:108
MQTTSubAckStatus_t
The status codes in the SUBACK response to a subscription request.
Definition: core_mqtt.h:139
MQTTPubAckType_t
Packet types used in acknowledging QoS 1 or QoS 2 publishes.
Definition: core_mqtt.h:127
MQTTConnectionStatus_t
Values indicating if an MQTT connection exists.
Definition: core_mqtt.h:98
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:99
MQTTQoS_t
MQTT Quality of Service values.
Definition: core_mqtt_serializer.h:121
@ MQTTPubRecSend
The library will send a PUBREC for a received PUBLISH.
Definition: core_mqtt.h:112
@ MQTTPubRecPending
The library is awaiting a PUBREC for an outgoing PUBLISH.
Definition: core_mqtt.h:116
@ MQTTPubCompPending
The library is awaiting a PUBCOMP for an outgoing PUBLISH.
Definition: core_mqtt.h:118
@ MQTTPubRelSend
The library will send a PUBREL for a received PUBREC.
Definition: core_mqtt.h:113
@ MQTTPubAckSend
The library will send a PUBACK for a received PUBLISH.
Definition: core_mqtt.h:111
@ MQTTPubRelPending
The library is awaiting a PUBREL for an incoming PUBLISH.
Definition: core_mqtt.h:117
@ MQTTPubCompSend
The library will send a PUBCOMP for a received PUBREL.
Definition: core_mqtt.h:114
@ MQTTStateNull
An empty state with no corresponding PUBLISH.
Definition: core_mqtt.h:109
@ MQTTPublishSend
The library will send an outgoing PUBLISH packet.
Definition: core_mqtt.h:110
@ MQTTPubAckPending
The library is awaiting a PUBACK for an outgoing PUBLISH.
Definition: core_mqtt.h:115
@ MQTTPublishDone
The PUBLISH has been completed.
Definition: core_mqtt.h:119
@ MQTTSubAckSuccessQos2
Success with a maximum delivery at QoS 2.
Definition: core_mqtt.h:142
@ MQTTSubAckSuccessQos1
Success with a maximum delivery at QoS 1.
Definition: core_mqtt.h:141
@ MQTTSubAckSuccessQos0
Success with a maximum delivery at QoS 0.
Definition: core_mqtt.h:140
@ MQTTSubAckFailure
Failure.
Definition: core_mqtt.h:143
@ MQTTPuback
PUBACKs are sent in response to a QoS 1 PUBLISH.
Definition: core_mqtt.h:128
@ MQTTPubrec
PUBRECs are sent in response to a QoS 2 PUBLISH.
Definition: core_mqtt.h:129
@ MQTTPubcomp
PUBCOMPs are sent in response to a PUBREL.
Definition: core_mqtt.h:131
@ MQTTPubrel
PUBRELs are sent in response to a PUBREC.
Definition: core_mqtt.h:130
@ MQTTNotConnected
MQTT Connection is inactive.
Definition: core_mqtt.h:99
@ MQTTConnected
MQTT Connection is active.
Definition: core_mqtt.h:100
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:145
A struct representing an MQTT connection.
Definition: core_mqtt.h:162
uint32_t lastPacketTxTime
Timestamp of the last packet sent by the library.
Definition: core_mqtt.h:216
MQTTFixedBuffer_t networkBuffer
The buffer used in sending and receiving packets from the network.
Definition: core_mqtt.h:191
size_t outgoingPublishRecordMaxCount
The maximum number of outgoing publish records.
Definition: core_mqtt.h:176
size_t index
Index to keep track of the number of bytes received in network buffer.
Definition: core_mqtt.h:232
MQTTConnectionStatus_t connectStatus
Whether the context currently has a connection to the broker.
Definition: core_mqtt.h:201
MQTTPubAckInfo_t * outgoingPublishRecords
State engine records for outgoing publishes.
Definition: core_mqtt.h:166
uint32_t lastPacketRxTime
Timestamp of the last packet received by the library.
Definition: core_mqtt.h:221
MQTTEventCallback_t appCallback
Callback function used to give deserialized MQTT packets to the application.
Definition: core_mqtt.h:211
TransportInterface_t transportInterface
The transport interface used by the MQTT connection.
Definition: core_mqtt.h:186
size_t incomingPublishRecordMaxCount
The maximum number of incoming publish records.
Definition: core_mqtt.h:181
MQTTGetCurrentTimeFunc_t getTime
Function used to get millisecond timestamps.
Definition: core_mqtt.h:206
bool waitingForPingResp
If the library is currently awaiting a PINGRESP.
Definition: core_mqtt.h:237
uint32_t pingReqSendTimeMs
Timestamp of the last sent PINGREQ.
Definition: core_mqtt.h:236
uint16_t nextPacketId
The next available ID for outgoing MQTT packets.
Definition: core_mqtt.h:196
bool controlPacketSent
Whether the library sent a packet during a call of MQTT_ProcessLoop or MQTT_ReceiveLoop.
Definition: core_mqtt.h:227
MQTTPubAckInfo_t * incomingPublishRecords
State engine records for incoming publishes.
Definition: core_mqtt.h:171
uint16_t keepAliveIntervalSec
Keep Alive interval.
Definition: core_mqtt.h:235
Struct to hold deserialized packet information for an MQTTEventCallback_t callback.
Definition: core_mqtt.h:246
MQTTStatus_t deserializationResult
Return code of deserialization.
Definition: core_mqtt.h:249
MQTTPublishInfo_t * pPublishInfo
Pointer to deserialized publish info.
Definition: core_mqtt.h:248
uint16_t packetIdentifier
Packet ID of deserialized packet.
Definition: core_mqtt.h:247
Buffer passed to MQTT library.
Definition: core_mqtt_serializer.h:135
MQTT incoming packet parameters.
Definition: core_mqtt_serializer.h:256
An element of the state engine records for QoS 1 or Qos 2 publishes.
Definition: core_mqtt.h:151
MQTTQoS_t qos
The QoS of the original PUBLISH.
Definition: core_mqtt.h:153
MQTTPublishState_t publishState
The current state of the publish process.
Definition: core_mqtt.h:154
uint16_t packetId
The packet ID of the original PUBLISH.
Definition: core_mqtt.h:152
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:214
MQTT SUBSCRIBE packet parameters.
Definition: core_mqtt_serializer.h:192
The transport layer interface.
Definition: transport_interface.h:302
Transport interface definitions to send and receive data over the network.