coreMQTT v1.2.0
MQTT 3.1.1 Client Library
core_mqtt.h
Go to the documentation of this file.
1/*
2 * coreMQTT v1.2.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/* *INDENT-OFF* */
31#ifdef __cplusplus
32 extern "C" {
33#endif
34/* *INDENT-ON* */
35
36/* MQTT_DO_NOT_USE_CUSTOM_CONFIG allows building the MQTT library
37 * without a custom config. If a custom config is provided, the
38 * MQTT_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
39#ifndef MQTT_DO_NOT_USE_CUSTOM_CONFIG
40 /* Include custom config file before other headers. */
41 #include "core_mqtt_config.h"
42#endif
43
44/* Include config defaults header to get default values of configs not
45 * defined in core_mqtt_config.h file. */
47
48/* Include MQTT serializer library. */
50
51/* Include transport interface. */
52#include "transport_interface.h"
53
58#define MQTT_LIBRARY_VERSION "v1.2.0"
67#define MQTT_PACKET_ID_INVALID ( ( uint16_t ) 0U )
68
69/* Structures defined in this file. */
70struct MQTTPubAckInfo;
71struct MQTTContext;
72struct MQTTDeserializedInfo;
73
81typedef uint32_t (* MQTTGetCurrentTimeFunc_t )( void );
82
96typedef void (* MQTTEventCallback_t )( struct MQTTContext * pContext,
97 struct MQTTPacketInfo * pPacketInfo,
98 struct MQTTDeserializedInfo * pDeserializedInfo );
99
104typedef enum MQTTConnectionStatus
105{
109
114typedef enum MQTTPublishState
115{
128
133typedef enum MQTTPubAckType
134{
140
145typedef enum MQTTSubAckStatus
146{
150 MQTTSubAckFailure = 0x80
152
157typedef struct MQTTPubAckInfo
158{
159 uint16_t packetId;
163
168typedef struct MQTTContext
169{
174
179
184
189
193 uint16_t nextPacketId;
194
199
204
209
214
220
221 /* Keep alive members. */
226
232typedef struct MQTTDeserializedInfo
233{
238
304/* @[declare_mqtt_init] */
306 const TransportInterface_t * pTransportInterface,
307 MQTTGetCurrentTimeFunc_t getTimeFunction,
308 MQTTEventCallback_t userCallback,
309 const MQTTFixedBuffer_t * pNetworkBuffer );
310/* @[declare_mqtt_init] */
311
414/* @[declare_mqtt_connect] */
416 const MQTTConnectInfo_t * pConnectInfo,
417 const MQTTPublishInfo_t * pWillInfo,
418 uint32_t timeoutMs,
419 bool * pSessionPresent );
420/* @[declare_mqtt_connect] */
421
471/* @[declare_mqtt_subscribe] */
473 const MQTTSubscribeInfo_t * pSubscriptionList,
474 size_t subscriptionCount,
475 uint16_t packetId );
476/* @[declare_mqtt_subscribe] */
477
519/* @[declare_mqtt_publish] */
521 const MQTTPublishInfo_t * pPublishInfo,
522 uint16_t packetId );
523/* @[declare_mqtt_publish] */
524
535/* @[declare_mqtt_ping] */
537/* @[declare_mqtt_ping] */
538
587/* @[declare_mqtt_unsubscribe] */
589 const MQTTSubscribeInfo_t * pSubscriptionList,
590 size_t subscriptionCount,
591 uint16_t packetId );
592/* @[declare_mqtt_unsubscribe] */
593
605/* @[declare_mqtt_disconnect] */
607/* @[declare_mqtt_disconnect] */
608
666/* @[declare_mqtt_processloop] */
668 uint32_t timeoutMs );
669/* @[declare_mqtt_processloop] */
670
733/* @[declare_mqtt_receiveloop] */
735 uint32_t timeoutMs );
736/* @[declare_mqtt_receiveloop] */
737
745/* @[declare_mqtt_getpacketid] */
746uint16_t MQTT_GetPacketId( MQTTContext_t * pContext );
747/* @[declare_mqtt_getpacketid] */
748
791MQTTStatus_t MQTT_MatchTopic( const char * pTopicName,
792 const uint16_t topicNameLength,
793 const char * pTopicFilter,
794 const uint16_t topicFilterLength,
795 bool * pIsMatch );
796
879/* @[declare_mqtt_getsubackstatuscodes] */
881 uint8_t ** pPayloadStart,
882 size_t * pPayloadSize );
883/* @[declare_mqtt_getsubackstatuscodes] */
884
892/* @[declare_mqtt_status_strerror] */
893const char * MQTT_Status_strerror( MQTTStatus_t status );
894/* @[declare_mqtt_status_strerror] */
895
896/* *INDENT-OFF* */
897#ifdef __cplusplus
898 }
899#endif
900/* *INDENT-ON* */
901
902#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:2279
const char * MQTT_Status_strerror(MQTTStatus_t status)
Error code to string conversion for MQTT statuses.
Definition: core_mqtt.c:2432
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:1916
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:2224
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:1856
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:2304
MQTTStatus_t MQTT_Ping(MQTTContext_t *pContext)
Sends an MQTT PINGREQ to broker.
Definition: core_mqtt.c:1990
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:2051
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:2373
MQTTStatus_t MQTT_Disconnect(MQTTContext_t *pContext)
Disconnect an MQTT session.
Definition: core_mqtt.c:2111
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:2167
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:1700
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:1759
This represents the default values for the configuration macros for the MQTT library.
#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:82
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:96
uint32_t(* MQTTGetCurrentTimeFunc_t)(void)
Application provided function to query the current time in milliseconds.
Definition: core_mqtt.h:81
MQTTPublishState_t
The state of QoS 1 or QoS 2 MQTT publishes, used in the state engine.
Definition: core_mqtt.h:115
MQTTSubAckStatus_t
The status codes in the SUBACK response to a subscription request.
Definition: core_mqtt.h:146
MQTTPubAckType_t
Packet types used in acknowledging QoS 1 or QoS 2 publishes.
Definition: core_mqtt.h:134
MQTTConnectionStatus_t
Values indicating if an MQTT connection exists.
Definition: core_mqtt.h:105
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:97
MQTTQoS_t
MQTT Quality of Service values.
Definition: core_mqtt_serializer.h:116
@ MQTTPubRecSend
The library will send a PUBREC for a received PUBLISH.
Definition: core_mqtt.h:119
@ MQTTPubRecPending
The library is awaiting a PUBREC for an outgoing PUBLISH.
Definition: core_mqtt.h:123
@ MQTTPubCompPending
The library is awaiting a PUBCOMP for an outgoing PUBLISH.
Definition: core_mqtt.h:125
@ MQTTPubRelSend
The library will send a PUBREL for a received PUBREC.
Definition: core_mqtt.h:120
@ MQTTPubAckSend
The library will send a PUBACK for a received PUBLISH.
Definition: core_mqtt.h:118
@ MQTTPubRelPending
The library is awaiting a PUBREL for an incoming PUBLISH.
Definition: core_mqtt.h:124
@ MQTTPubCompSend
The library will send a PUBCOMP for a received PUBREL.
Definition: core_mqtt.h:121
@ MQTTStateNull
An empty state with no corresponding PUBLISH.
Definition: core_mqtt.h:116
@ MQTTPublishSend
The library will send an outgoing PUBLISH packet.
Definition: core_mqtt.h:117
@ MQTTPubAckPending
The library is awaiting a PUBACK for an outgoing PUBLISH.
Definition: core_mqtt.h:122
@ MQTTPublishDone
The PUBLISH has been completed.
Definition: core_mqtt.h:126
@ MQTTSubAckSuccessQos2
Success with a maximum delivery at QoS 2.
Definition: core_mqtt.h:149
@ MQTTSubAckSuccessQos1
Success with a maximum delivery at QoS 1.
Definition: core_mqtt.h:148
@ MQTTSubAckSuccessQos0
Success with a maximum delivery at QoS 0.
Definition: core_mqtt.h:147
@ MQTTSubAckFailure
Failure.
Definition: core_mqtt.h:150
@ MQTTPuback
PUBACKs are sent in response to a QoS 1 PUBLISH.
Definition: core_mqtt.h:135
@ MQTTPubrec
PUBRECs are sent in response to a QoS 2 PUBLISH.
Definition: core_mqtt.h:136
@ MQTTPubcomp
PUBCOMPs are sent in response to a PUBREL.
Definition: core_mqtt.h:138
@ MQTTPubrel
PUBRELs are sent in response to a PUBREC.
Definition: core_mqtt.h:137
@ MQTTNotConnected
MQTT Connection is inactive.
Definition: core_mqtt.h:106
@ MQTTConnected
MQTT Connection is active.
Definition: core_mqtt.h:107
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:140
A struct representing an MQTT connection.
Definition: core_mqtt.h:169
MQTTFixedBuffer_t networkBuffer
The buffer used in sending and receiving packets from the network.
Definition: core_mqtt.h:188
MQTTConnectionStatus_t connectStatus
Whether the context currently has a connection to the broker.
Definition: core_mqtt.h:198
MQTTEventCallback_t appCallback
Callback function used to give deserialized MQTT packets to the application.
Definition: core_mqtt.h:208
TransportInterface_t transportInterface
The transport interface used by the MQTT connection.
Definition: core_mqtt.h:183
MQTTGetCurrentTimeFunc_t getTime
Function used to get millisecond timestamps.
Definition: core_mqtt.h:203
uint32_t lastPacketTime
Timestamp of the last packet sent by the library.
Definition: core_mqtt.h:213
bool waitingForPingResp
If the library is currently awaiting a PINGRESP.
Definition: core_mqtt.h:224
uint32_t pingReqSendTimeMs
Timestamp of the last sent PINGREQ.
Definition: core_mqtt.h:223
uint16_t nextPacketId
The next available ID for outgoing MQTT packets.
Definition: core_mqtt.h:193
bool controlPacketSent
Whether the library sent a packet during a call of MQTT_ProcessLoop or MQTT_ReceiveLoop.
Definition: core_mqtt.h:219
uint16_t keepAliveIntervalSec
Keep Alive interval.
Definition: core_mqtt.h:222
Struct to hold deserialized packet information for an MQTTEventCallback_t callback.
Definition: core_mqtt.h:233
MQTTStatus_t deserializationResult
Return code of deserialization.
Definition: core_mqtt.h:236
MQTTPublishInfo_t * pPublishInfo
Pointer to deserialized publish info.
Definition: core_mqtt.h:235
uint16_t packetIdentifier
Packet ID of deserialized packet.
Definition: core_mqtt.h:234
Buffer passed to MQTT library.
Definition: core_mqtt_serializer.h:130
MQTT incoming packet parameters.
Definition: core_mqtt_serializer.h:251
An element of the state engine records for QoS 1 or Qos 2 publishes.
Definition: core_mqtt.h:158
MQTTQoS_t qos
The QoS of the original PUBLISH.
Definition: core_mqtt.h:160
MQTTPublishState_t publishState
The current state of the publish process.
Definition: core_mqtt.h:161
uint16_t packetId
The packet ID of the original PUBLISH.
Definition: core_mqtt.h:159
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:209
MQTT SUBSCRIBE packet parameters.
Definition: core_mqtt_serializer.h:187
The transport layer interface.
Definition: transport_interface.h:252
Transport interface definitions to send and receive data over the network.