coreMQTT  v1.1.2
MQTT 3.1.1 Client Library
core_mqtt_serializer.h
Go to the documentation of this file.
1 /*
2  * coreMQTT v1.1.2
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 
30 #ifndef CORE_MQTT_SERIALIZER_H
31 #define CORE_MQTT_SERIALIZER_H
32 
33 #include <stddef.h>
34 #include <stdint.h>
35 #include <stdbool.h>
36 
37 /* *INDENT-OFF* */
38 #ifdef __cplusplus
39  extern "C" {
40 #endif
41 /* *INDENT-ON */
42 
43 /* MQTT_DO_NOT_USE_CUSTOM_CONFIG allows building the MQTT library
44  * without a custom config. If a custom config is provided, the
45  * MQTT_DO_NOT_USE_CUSTOM_CONFIG macro should not be defined. */
46 #ifndef MQTT_DO_NOT_USE_CUSTOM_CONFIG
47  /* Include custom config file before other headers. */
48  #include "core_mqtt_config.h"
49 #endif
50 
51 /* Include config defaults header to get default values of configs not
52  * defined in core_mqtt_config.h file. */
54 
55 #include "transport_interface.h"
56 
57 /* MQTT packet types. */
58 
63 #define MQTT_PACKET_TYPE_CONNECT ( ( uint8_t ) 0x10U )
64 #define MQTT_PACKET_TYPE_CONNACK ( ( uint8_t ) 0x20U )
65 #define MQTT_PACKET_TYPE_PUBLISH ( ( uint8_t ) 0x30U )
66 #define MQTT_PACKET_TYPE_PUBACK ( ( uint8_t ) 0x40U )
67 #define MQTT_PACKET_TYPE_PUBREC ( ( uint8_t ) 0x50U )
68 #define MQTT_PACKET_TYPE_PUBREL ( ( uint8_t ) 0x62U )
69 #define MQTT_PACKET_TYPE_PUBCOMP ( ( uint8_t ) 0x70U )
70 #define MQTT_PACKET_TYPE_SUBSCRIBE ( ( uint8_t ) 0x82U )
71 #define MQTT_PACKET_TYPE_SUBACK ( ( uint8_t ) 0x90U )
72 #define MQTT_PACKET_TYPE_UNSUBSCRIBE ( ( uint8_t ) 0xA2U )
73 #define MQTT_PACKET_TYPE_UNSUBACK ( ( uint8_t ) 0xB0U )
74 #define MQTT_PACKET_TYPE_PINGREQ ( ( uint8_t ) 0xC0U )
75 #define MQTT_PACKET_TYPE_PINGRESP ( ( uint8_t ) 0xD0U )
76 #define MQTT_PACKET_TYPE_DISCONNECT ( ( uint8_t ) 0xE0U )
83 #define MQTT_PUBLISH_ACK_PACKET_SIZE ( 4UL )
84 
85 /* Structures defined in this file. */
86 struct MQTTFixedBuffer;
87 struct MQTTConnectInfo;
88 struct MQTTSubscribeInfo;
89 struct MQTTPublishInfo;
90 struct MQTTPacketInfo;
91 
96 typedef enum MQTTStatus
97 {
110 
115 typedef enum MQTTQoS
116 {
117  MQTTQoS0 = 0,
118  MQTTQoS1 = 1,
119  MQTTQoS2 = 2
121 
129 typedef struct MQTTFixedBuffer
130 {
131  uint8_t * pBuffer;
132  size_t size;
134 
139 typedef struct MQTTConnectInfo
140 {
145 
150 
154  const char * pClientIdentifier;
155 
160 
164  const char * pUserName;
165 
169  uint16_t userNameLength;
170 
174  const char * pPassword;
175 
179  uint16_t passwordLength;
181 
186 typedef struct MQTTSubscribeInfo
187 {
192 
196  const char * pTopicFilter;
197 
203 
208 typedef struct MQTTPublishInfo
209 {
214 
218  bool retain;
219 
223  bool dup;
224 
228  const char * pTopicName;
229 
233  uint16_t topicNameLength;
234 
238  const void * pPayload;
239 
245 
250 typedef struct MQTTPacketInfo
251 {
255  uint8_t type;
256 
260  uint8_t * pRemainingData;
261 
267 
315 /* @[declare_mqtt_getconnectpacketsize] */
317  const MQTTPublishInfo_t * pWillInfo,
318  size_t * pRemainingLength,
319  size_t * pPacketSize );
320 /* @[declare_mqtt_getconnectpacketsize] */
321 
371 /* @[declare_mqtt_serializeconnect] */
373  const MQTTPublishInfo_t * pWillInfo,
374  size_t remainingLength,
375  const MQTTFixedBuffer_t * pFixedBuffer );
376 /* @[declare_mqtt_serializeconnect] */
377 
429 /* @[declare_mqtt_getsubscribepacketsize] */
431  size_t subscriptionCount,
432  size_t * pRemainingLength,
433  size_t * pPacketSize );
434 /* @[declare_mqtt_getsubscribepacketsize] */
435 
495 /* @[declare_mqtt_serializesubscribe] */
496 MQTTStatus_t MQTT_SerializeSubscribe( const MQTTSubscribeInfo_t * pSubscriptionList,
497  size_t subscriptionCount,
498  uint16_t packetId,
499  size_t remainingLength,
500  const MQTTFixedBuffer_t * pFixedBuffer );
501 /* @[declare_mqtt_serializesubscribe] */
502 
546 /* @[declare_mqtt_getunsubscribepacketsize] */
548  size_t subscriptionCount,
549  size_t * pRemainingLength,
550  size_t * pPacketSize );
551 /* @[declare_mqtt_getunsubscribepacketsize] */
552 
612 /* @[declare_mqtt_serializeunsubscribe] */
614  size_t subscriptionCount,
615  uint16_t packetId,
616  size_t remainingLength,
617  const MQTTFixedBuffer_t * pFixedBuffer );
618 /* @[declare_mqtt_serializeunsubscribe] */
619 
666 /* @[declare_mqtt_getpublishpacketsize] */
668  size_t * pRemainingLength,
669  size_t * pPacketSize );
670 /* @[declare_mqtt_getpublishpacketsize] */
671 
734 /* @[declare_mqtt_serializepublish] */
736  uint16_t packetId,
737  size_t remainingLength,
738  const MQTTFixedBuffer_t * pFixedBuffer );
739 /* @[declare_mqtt_serializepublish] */
740 
814 /* @[declare_mqtt_serializepublishheader] */
816  uint16_t packetId,
817  size_t remainingLength,
818  const MQTTFixedBuffer_t * pFixedBuffer,
819  size_t * pHeaderSize );
820 /* @[declare_mqtt_serializepublishheader] */
821 
863 /* @[declare_mqtt_serializeack] */
864 MQTTStatus_t MQTT_SerializeAck( const MQTTFixedBuffer_t * pFixedBuffer,
865  uint8_t packetType,
866  uint16_t packetId );
867 /* @[declare_mqtt_serializeack] */
868 
893 /* @[declare_mqtt_getdisconnectpacketsize] */
894 MQTTStatus_t MQTT_GetDisconnectPacketSize( size_t * pPacketSize );
895 /* @[declare_mqtt_getdisconnectpacketsize] */
896 
934 /* @[declare_mqtt_serializedisconnect] */
936 /* @[declare_mqtt_serializedisconnect] */
937 
962 /* @[declare_mqtt_getpingreqpacketsize] */
963 MQTTStatus_t MQTT_GetPingreqPacketSize( size_t * pPacketSize );
964 /* @[declare_mqtt_getpingreqpacketsize] */
965 
1003 /* @[declare_mqtt_serializepingreq] */
1004 MQTTStatus_t MQTT_SerializePingreq( const MQTTFixedBuffer_t * pFixedBuffer );
1005 /* @[declare_mqtt_serializepingreq] */
1006 
1064 /* @[declare_mqtt_deserializepublish] */
1065 MQTTStatus_t MQTT_DeserializePublish( const MQTTPacketInfo_t * pIncomingPacket,
1066  uint16_t * pPacketId,
1067  MQTTPublishInfo_t * pPublishInfo );
1068 /* @[declare_mqtt_deserializepublish] */
1069 
1108 /* @[declare_mqtt_deserializeack] */
1109 MQTTStatus_t MQTT_DeserializeAck( const MQTTPacketInfo_t * pIncomingPacket,
1110  uint16_t * pPacketId,
1111  bool * pSessionPresent );
1112 /* @[declare_mqtt_deserializeack] */
1113 
1174 /* @[declare_mqtt_getincomingpackettypeandlength] */
1176  NetworkContext_t * pNetworkContext,
1177  MQTTPacketInfo_t * pIncomingPacket );
1178 /* @[declare_mqtt_getincomingpackettypeandlength] */
1179 
1180 /* *INDENT-OFF* */
1181 #ifdef __cplusplus
1182  }
1183 #endif
1184 /* *INDENT-ON* */
1185 
1186 #endif /* ifndef CORE_MQTT_SERIALIZER_H */
MQTTSubscribeInfo_t
MQTT SUBSCRIBE packet parameters.
Definition: core_mqtt_serializer.h:187
MQTT_GetPingreqPacketSize
MQTTStatus_t MQTT_GetPingreqPacketSize(size_t *pPacketSize)
Get the size of an MQTT PINGREQ packet.
Definition: core_mqtt_serializer.c:2174
MQTTPacketInfo_t::pRemainingData
uint8_t * pRemainingData
Remaining serialized data in the MQTT packet.
Definition: core_mqtt_serializer.h:260
MQTTPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of topic name.
Definition: core_mqtt_serializer.h:233
MQTTConnectInfo_t
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:140
MQTT_GetPublishPacketSize
MQTTStatus_t MQTT_GetPublishPacketSize(const MQTTPublishInfo_t *pPublishInfo, size_t *pRemainingLength, size_t *pPacketSize)
Get the packet size and remaining length of an MQTT PUBLISH packet.
Definition: core_mqtt_serializer.c:1847
MQTT_SerializeDisconnect
MQTTStatus_t MQTT_SerializeDisconnect(const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT DISCONNECT packet into the given buffer.
Definition: core_mqtt_serializer.c:2131
MQTTFixedBuffer_t::pBuffer
uint8_t * pBuffer
Pointer to buffer.
Definition: core_mqtt_serializer.h:131
MQTT_SerializeAck
MQTTStatus_t MQTT_SerializeAck(const MQTTFixedBuffer_t *pFixedBuffer, uint8_t packetType, uint16_t packetId)
Serialize an MQTT PUBACK, PUBREC, PUBREL, or PUBCOMP into the given buffer.
Definition: core_mqtt_serializer.c:2056
MQTTNoDataAvailable
@ MQTTNoDataAvailable
Definition: core_mqtt_serializer.h:105
TransportRecv_t
int32_t(* TransportRecv_t)(NetworkContext_t *pNetworkContext, void *pBuffer, size_t bytesToRecv)
Transport interface for receiving data on the network.
Definition: transport_interface.h:219
MQTTPacketInfo_t
MQTT incoming packet parameters.
Definition: core_mqtt_serializer.h:251
MQTTPublishInfo_t::retain
bool retain
Whether this is a retained message.
Definition: core_mqtt_serializer.h:218
MQTTNoMemory
@ MQTTNoMemory
Definition: core_mqtt_serializer.h:100
MQTTSubscribeInfo_t::pTopicFilter
const char * pTopicFilter
Topic filter to subscribe to.
Definition: core_mqtt_serializer.h:196
NetworkContext_t
struct NetworkContext NetworkContext_t
The NetworkContext is an incomplete type. An implementation of this interface must define struct Netw...
Definition: transport_interface.h:189
MQTTFixedBuffer_t
Buffer passed to MQTT library.
Definition: core_mqtt_serializer.h:130
MQTTPublishInfo_t::pPayload
const void * pPayload
Message payload.
Definition: core_mqtt_serializer.h:238
MQTTFixedBuffer_t::size
size_t size
Size of buffer.
Definition: core_mqtt_serializer.h:132
MQTT_SerializePingreq
MQTTStatus_t MQTT_SerializePingreq(const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT PINGREQ packet into the given buffer.
Definition: core_mqtt_serializer.c:2194
MQTT_DeserializeAck
MQTTStatus_t MQTT_DeserializeAck(const MQTTPacketInfo_t *pIncomingPacket, uint16_t *pPacketId, bool *pSessionPresent)
Deserialize an MQTT CONNACK, SUBACK, UNSUBACK, PUBACK, PUBREC, PUBREL, PUBCOMP, or PINGRESP.
Definition: core_mqtt_serializer.c:2274
MQTTKeepAliveTimeout
@ MQTTKeepAliveTimeout
Definition: core_mqtt_serializer.h:108
MQTT_GetConnectPacketSize
MQTTStatus_t MQTT_GetConnectPacketSize(const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, size_t *pRemainingLength, size_t *pPacketSize)
Get the size and Remaining Length of an MQTT CONNECT packet.
Definition: core_mqtt_serializer.c:1508
MQTT_GetSubscribePacketSize
MQTTStatus_t MQTT_GetSubscribePacketSize(const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, size_t *pRemainingLength, size_t *pPacketSize)
Get packet size and Remaining Length of an MQTT SUBSCRIBE packet.
Definition: core_mqtt_serializer.c:1666
MQTTQoS2
@ MQTTQoS2
Definition: core_mqtt_serializer.h:119
MQTTConnectInfo_t::pClientIdentifier
const char * pClientIdentifier
MQTT client identifier. Must be unique per client.
Definition: core_mqtt_serializer.h:154
MQTTStatus_t
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:97
MQTTConnectInfo_t::keepAliveSeconds
uint16_t keepAliveSeconds
MQTT keep alive period.
Definition: core_mqtt_serializer.h:149
MQTTConnectInfo_t::pPassword
const char * pPassword
MQTT password. Set to NULL if not used.
Definition: core_mqtt_serializer.h:174
MQTTBadParameter
@ MQTTBadParameter
Definition: core_mqtt_serializer.h:99
MQTTRecvFailed
@ MQTTRecvFailed
Definition: core_mqtt_serializer.h:102
MQTT_SerializeConnect
MQTTStatus_t MQTT_SerializeConnect(const MQTTConnectInfo_t *pConnectInfo, const MQTTPublishInfo_t *pWillInfo, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT CONNECT packet in the given fixed buffer pFixedBuffer.
Definition: core_mqtt_serializer.c:1608
MQTT_SerializeUnsubscribe
MQTTStatus_t MQTT_SerializeUnsubscribe(const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT UNSUBSCRIBE packet in the given buffer.
Definition: core_mqtt_serializer.c:1796
MQTTConnectInfo_t::passwordLength
uint16_t passwordLength
Length of MQTT password. Set to 0 if not used.
Definition: core_mqtt_serializer.h:179
MQTT_GetUnsubscribePacketSize
MQTTStatus_t MQTT_GetUnsubscribePacketSize(const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, size_t *pRemainingLength, size_t *pPacketSize)
Get packet size and Remaining Length of an MQTT UNSUBSCRIBE packet.
Definition: core_mqtt_serializer.c:1758
MQTTPublishInfo_t::pTopicName
const char * pTopicName
Topic name on which the message is published.
Definition: core_mqtt_serializer.h:228
MQTT_DeserializePublish
MQTTStatus_t MQTT_DeserializePublish(const MQTTPacketInfo_t *pIncomingPacket, uint16_t *pPacketId, MQTTPublishInfo_t *pPublishInfo)
Deserialize an MQTT PUBLISH packet.
Definition: core_mqtt_serializer.c:2237
MQTTIllegalState
@ MQTTIllegalState
Definition: core_mqtt_serializer.h:106
MQTT_SerializePublishHeader
MQTTStatus_t MQTT_SerializePublishHeader(const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer, size_t *pHeaderSize)
Serialize an MQTT PUBLISH packet header in the given buffer.
Definition: core_mqtt_serializer.c:1973
MQTT_SerializePublish
MQTTStatus_t MQTT_SerializePublish(const MQTTPublishInfo_t *pPublishInfo, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT PUBLISH packet in the given buffer.
Definition: core_mqtt_serializer.c:1888
MQTT_GetIncomingPacketTypeAndLength
MQTTStatus_t MQTT_GetIncomingPacketTypeAndLength(TransportRecv_t readFunc, NetworkContext_t *pNetworkContext, MQTTPacketInfo_t *pIncomingPacket)
Extract the MQTT packet type and length from incoming packet.
Definition: core_mqtt_serializer.c:2351
MQTTQoS_t
MQTTQoS_t
MQTT Quality of Service values.
Definition: core_mqtt_serializer.h:116
MQTTConnectInfo_t::cleanSession
bool cleanSession
Whether to establish a new, clean session or resume a previous session.
Definition: core_mqtt_serializer.h:144
MQTTSubscribeInfo_t::topicFilterLength
uint16_t topicFilterLength
Length of subscription topic filter.
Definition: core_mqtt_serializer.h:201
MQTTServerRefused
@ MQTTServerRefused
Definition: core_mqtt_serializer.h:104
MQTTSubscribeInfo_t::qos
MQTTQoS_t qos
Quality of Service for subscription.
Definition: core_mqtt_serializer.h:191
MQTTStateCollision
@ MQTTStateCollision
Definition: core_mqtt_serializer.h:107
MQTTSendFailed
@ MQTTSendFailed
Definition: core_mqtt_serializer.h:101
MQTTConnectInfo_t::clientIdentifierLength
uint16_t clientIdentifierLength
Length of the client identifier.
Definition: core_mqtt_serializer.h:159
MQTTQoS1
@ MQTTQoS1
Definition: core_mqtt_serializer.h:118
MQTTPacketInfo_t::type
uint8_t type
Type of incoming MQTT packet.
Definition: core_mqtt_serializer.h:255
MQTTPublishInfo_t::qos
MQTTQoS_t qos
Quality of Service for message.
Definition: core_mqtt_serializer.h:213
MQTTSuccess
@ MQTTSuccess
Definition: core_mqtt_serializer.h:98
MQTTPublishInfo_t
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:209
MQTT_GetDisconnectPacketSize
MQTTStatus_t MQTT_GetDisconnectPacketSize(size_t *pPacketSize)
Get the size of an MQTT DISCONNECT packet.
Definition: core_mqtt_serializer.c:2111
MQTTBadResponse
@ MQTTBadResponse
Definition: core_mqtt_serializer.h:103
transport_interface.h
Transport interface definitions to send and receive data over the network.
core_mqtt_config_defaults.h
This represents the default values for the configuration macros for the MQTT library.
MQTTConnectInfo_t::userNameLength
uint16_t userNameLength
Length of MQTT user name. Set to 0 if not used.
Definition: core_mqtt_serializer.h:169
MQTTPacketInfo_t::remainingLength
size_t remainingLength
Length of remaining serialized data.
Definition: core_mqtt_serializer.h:265
MQTTPublishInfo_t::payloadLength
size_t payloadLength
Message payload length.
Definition: core_mqtt_serializer.h:243
MQTTPublishInfo_t::dup
bool dup
Whether this is a duplicate publish message.
Definition: core_mqtt_serializer.h:223
MQTTQoS0
@ MQTTQoS0
Definition: core_mqtt_serializer.h:117
MQTT_SerializeSubscribe
MQTTStatus_t MQTT_SerializeSubscribe(const MQTTSubscribeInfo_t *pSubscriptionList, size_t subscriptionCount, uint16_t packetId, size_t remainingLength, const MQTTFixedBuffer_t *pFixedBuffer)
Serialize an MQTT SUBSCRIBE packet in the given buffer.
Definition: core_mqtt_serializer.c:1704
MQTTConnectInfo_t::pUserName
const char * pUserName
MQTT user name. Set to NULL if not used.
Definition: core_mqtt_serializer.h:164