MQTT API Reference
MQTT 3.1.1 client library
iot_mqtt_types.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2019 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy of
5  * this software and associated documentation files (the "Software"), to deal in
6  * the Software without restriction, including without limitation the rights to
7  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
8  * the Software, and to permit persons to whom the Software is furnished to do so,
9  * subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in all
12  * copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
16  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
17  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
18  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
19  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20  */
21 
27 #ifndef IOT_MQTT_TYPES_H_
28 #define IOT_MQTT_TYPES_H_
29 
30 /* The config header is always included first. */
31 #include "iot_config.h"
32 
33 /* Standard includes. */
34 #include <stdbool.h>
35 #include <stdint.h>
36 #include <stddef.h>
37 
38 /* Type includes. */
41 
42 /* Platform network include. */
43 #include "platform/iot_network.h"
44 
45 /*---------------------------- MQTT handle types ----------------------------*/
46 
66 typedef struct _mqttConnection * IotMqttConnection_t;
67 
88 typedef struct _mqttOperation * IotMqttOperation_t;
89 
90 /*-------------------------- MQTT enumerated types --------------------------*/
91 
103 typedef enum IotMqttError
104 {
120 
130 
138 
150 
161 
178 
189 
206 
218 
239 
253 
269 
277 typedef enum IotMqttOperationType
278 {
287 
303 typedef enum IotMqttQos
304 {
308 } IotMqttQos_t;
309 
320 typedef enum IotMqttDisconnectReason
321 {
326 
327 /*------------------------- MQTT parameter structs --------------------------*/
328 
397 typedef struct IotMqttPublishInfo
398 {
400  bool retain;
402  const char * pTopicName;
403  uint16_t topicNameLength;
405  const void * pPayload;
406  size_t payloadLength;
408  uint32_t retryMs;
409  uint32_t retryLimit;
411 
443 typedef struct IotMqttCallbackParam
444 {
456 
457  union
458  {
459  /* Valid for completed operations. */
460  struct
461  {
465  } operation;
466 
467  /* Valid for incoming PUBLISH messages. */
468  struct
469  {
470  const char * pTopicFilter;
471  uint16_t topicFilterLength;
473  } message;
474 
475  /* Valid when a connection is disconnected. */
477  } u;
479 
516 typedef struct IotMqttCallbackInfo
517 {
529  void ( * function )( void *,
532 
550 typedef struct IotMqttSubscription
551 {
558 
559  const char * pTopicFilter;
560  uint16_t topicFilterLength;
569 
585 typedef struct IotMqttConnectInfo
586 {
602 
633 
645 
658 
673 
674  uint16_t keepAliveSeconds;
676  const char * pClientIdentifier;
679  /* These credentials are not used by AWS IoT and may be ignored if
680  * awsIotMqttMode is true. */
681  const char * pUserName;
682  uint16_t userNameLength;
683  const char * pPassword;
684  uint16_t passwordLength;
686 
687 #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1
688 
695  struct _mqttPacket;
715  typedef struct IotMqttSerializer
716  {
726  uint8_t ( * getPacketType )( void * /* pNetworkConnection */,
727  const IotNetworkInterface_t * /* pNetworkInterface */ );
728 
738  size_t ( * getRemainingLength )( void * pNetworkConnection,
739  const IotNetworkInterface_t * pNetworkInterface );
740 
749  void ( * freePacket )( uint8_t * /* pPacket */ );
750 
751  struct
752  {
761  IotMqttError_t ( * connect )( const IotMqttConnectInfo_t * /* pConnectInfo */,
762  uint8_t ** /* pConnectPacket */,
763  size_t * /* pPacketSize */ );
764 
776  IotMqttError_t ( * publish )( const IotMqttPublishInfo_t * /* pPublishInfo */,
777  uint8_t ** /* pPublishPacket */,
778  size_t * /* pPacketSize */,
779  uint16_t * /* pPacketIdentifier */,
780  uint8_t ** /* pPacketIdentifierHigh */ );
781 
790  void ( *publishSetDup )( uint8_t * /* pPublishPacket */,
791  uint8_t * /* pPacketIdentifierHigh */,
792  uint16_t * /* pNewPacketIdentifier */ );
793 
802  IotMqttError_t ( * puback )( uint16_t /* packetIdentifier */,
803  uint8_t ** /* pPubackPacket */,
804  size_t * /* pPacketSize */ );
805 
816  IotMqttError_t ( * subscribe )( const IotMqttSubscription_t * /* pSubscriptionList */,
817  size_t /* subscriptionCount */,
818  uint8_t ** /* pSubscribePacket */,
819  size_t * /* pPacketSize */,
820  uint16_t * /* pPacketIdentifier */ );
821 
832  IotMqttError_t ( * unsubscribe )( const IotMqttSubscription_t * /* pSubscriptionList */,
833  size_t /* subscriptionCount */,
834  uint8_t ** /* pUnsubscribePacket */,
835  size_t * /* pPacketSize */,
836  uint16_t * /* pPacketIdentifier */ );
837 
845  IotMqttError_t ( * pingreq )( uint8_t ** /* pPingreqPacket */,
846  size_t * /* pPacketSize */ );
847 
855  IotMqttError_t ( * disconnect )( uint8_t ** /* pDisconnectPacket */,
856  size_t * /* pPacketSize */ );
857  } serialize;
859  struct
860  {
867  IotMqttError_t ( * connack )( struct _mqttPacket * /* pConnack */ );
868 
875  IotMqttError_t ( * publish )( struct _mqttPacket * /* pPublish */ );
876 
883  IotMqttError_t ( * puback )( struct _mqttPacket * pPuback );
884 
891  IotMqttError_t ( * suback )( struct _mqttPacket * /* pSuback */ );
892 
899  IotMqttError_t ( * unsuback )( struct _mqttPacket * /* pUnsuback */ );
900 
907  IotMqttError_t ( * pingresp )( struct _mqttPacket * /* pPingresp */ );
908  } deserialize;
910 #else /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */
911 
912 /* When MQTT packet serializer overrides are disabled, this struct is an
913  * incomplete type. */
914  typedef struct IotMqttSerializer IotMqttSerializer_t;
915 
916 #endif /* if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1 */
917 
930 typedef struct IotMqttNetworkInfo
931 {
948 
949  union
950  {
951  struct
952  {
962 
972  } setup;
973 
982  } u ;
983 
991 
996 
997  #if IOT_MQTT_ENABLE_SERIALIZER_OVERRIDES == 1
998 
1006  #endif
1008 
1009 /*------------------------- MQTT defined constants --------------------------*/
1010 
1055 /* @[define_mqtt_initializers] */
1057 #define IOT_MQTT_NETWORK_INFO_INITIALIZER { .createNetworkConnection = true }
1058 
1059 #define IOT_MQTT_SERIALIZER_INITIALIZER { 0 }
1060 
1061 #define IOT_MQTT_CONNECT_INFO_INITIALIZER { .cleanSession = true }
1062 
1063 #define IOT_MQTT_PUBLISH_INFO_INITIALIZER { .qos = IOT_MQTT_QOS_0 }
1064 
1065 #define IOT_MQTT_SUBSCRIPTION_INITIALIZER { .qos = IOT_MQTT_QOS_0 }
1066 
1067 #define IOT_MQTT_CALLBACK_INFO_INITIALIZER { 0 }
1068 
1069 #define IOT_MQTT_CONNECTION_INITIALIZER NULL
1070 
1071 #define IOT_MQTT_OPERATION_INITIALIZER NULL
1072 /* @[define_mqtt_initializers] */
1073 
1087 #define IOT_MQTT_FLAG_WAITABLE ( 0x00000001 )
1088 
1097 #define IOT_MQTT_FLAG_CLEANUP_ONLY ( 0x00000001 )
1098 
1099 #endif /* ifndef IOT_MQTT_TYPES_H_ */
IOT_MQTT_STATUS_PENDING
MQTT operation queued, awaiting result.
Definition: iot_mqtt_types.h:129
IotMqttNetworkInfo_t::pNetworkInterface
const IotNetworkInterface_t * pNetworkInterface
The network functions used by the new MQTT connection.
Definition: iot_mqtt_types.h:990
IOT_MQTT_KEEP_ALIVE_TIMEOUT
Definition: iot_mqtt_types.h:324
IOT_MQTT_UNSUBSCRIBE
Definition: iot_mqtt_types.h:283
IOT_MQTT_TIMEOUT
A blocking MQTT operation timed out.
Definition: iot_mqtt_types.h:217
IOT_MQTT_SUBSCRIBE
Definition: iot_mqtt_types.h:282
IotMqttCallbackParam_t::disconnectReason
IotMqttDisconnectReason_t disconnectReason
Why the MQTT connection was disconnected.
Definition: iot_mqtt_types.h:476
IotMqttConnectInfo_t::keepAliveSeconds
uint16_t keepAliveSeconds
Period of keep-alive messages. Set to 0 to disable keep-alive.
Definition: iot_mqtt_types.h:674
IOT_MQTT_BAD_PARAMETER
At least one parameter is invalid.
Definition: iot_mqtt_types.h:149
IotMqttConnectInfo_t::cleanSession
bool cleanSession
Whether this connection is a clean session.
Definition: iot_mqtt_types.h:632
IotMqttPublishInfo_t::retryLimit
uint32_t retryLimit
How many times to attempt retransmission.
Definition: iot_mqtt_types.h:409
IOT_MQTT_SERVER_REFUSED
A CONNECT or at least one subscription was refused by the server.
Definition: iot_mqtt_types.h:238
IotMqttQos_t
IotMqttQos_t
Quality of service levels for MQTT PUBLISH messages.
Definition: iot_mqtt_types.h:303
IotMqttError_t
IotMqttError_t
Return codes of MQTT functions.
Definition: iot_mqtt_types.h:103
IotMqttCallbackInfo_t
Information on a user-provided MQTT callback function.
Definition: iot_mqtt_types.h:516
IotMqttCallbackParam_t::reference
IotMqttOperation_t reference
Reference to the operation that completed.
Definition: iot_mqtt_types.h:463
iot_platform_types.h
IotMqttNetworkInfo_t::disconnectCallback
IotMqttCallbackInfo_t disconnectCallback
A callback function to invoke when this MQTT connection is disconnected.
Definition: iot_mqtt_types.h:995
IotMqttPublishInfo_t::pPayload
const void * pPayload
Payload of PUBLISH.
Definition: iot_mqtt_types.h:405
IotMqttOperation_t
struct _mqttOperation * IotMqttOperation_t
Opaque handle that references an in-progress MQTT operation.
Definition: iot_mqtt_types.h:88
IotMqttConnectInfo_t::awsIotMqttMode
bool awsIotMqttMode
Specifies if this MQTT connection is to an AWS IoT MQTT server.
Definition: iot_mqtt_types.h:601
IotMqttPublishInfo_t::retain
bool retain
MQTT message retain flag.
Definition: iot_mqtt_types.h:400
IotMqttConnectInfo_t::pPassword
const char * pPassword
Password for MQTT connection.
Definition: iot_mqtt_types.h:683
IOT_MQTT_CONNECT
Definition: iot_mqtt_types.h:279
IOT_MQTT_SUCCESS
MQTT operation completed successfully.
Definition: iot_mqtt_types.h:119
IotMqttCallbackParam_t::mqttConnection
IotMqttConnection_t mqttConnection
The MQTT connection associated with this completed operation, incoming PUBLISH, or disconnect.
Definition: iot_mqtt_types.h:455
IotMqttDisconnectReason_t
IotMqttDisconnectReason_t
The reason that an MQTT connection (and its associated network connection) was disconnected.
Definition: iot_mqtt_types.h:320
IOT_MQTT_NO_MEMORY
MQTT operation failed because of memory allocation failure.
Definition: iot_mqtt_types.h:160
iot_taskpool_types.h
IotMqttPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of IotMqttPublishInfo_t.pTopicName.
Definition: iot_mqtt_types.h:403
IOT_MQTT_PINGREQ
Definition: iot_mqtt_types.h:284
IotMqttPublishInfo_t::pTopicName
const char * pTopicName
Topic name of PUBLISH.
Definition: iot_mqtt_types.h:402
IotMqttNetworkInfo_t::pNetworkConnection
void * pNetworkConnection
An established transport-layer network connection.
Definition: iot_mqtt_types.h:981
IOT_MQTT_PUBLISH_TO_SERVER
Definition: iot_mqtt_types.h:280
IotMqttPublishInfo_t::retryMs
uint32_t retryMs
If no response is received within this time, the message is retransmitted.
Definition: iot_mqtt_types.h:408
IotMqttCallbackParam_t::topicFilterLength
uint16_t topicFilterLength
Length of pTopicFilter.
Definition: iot_mqtt_types.h:471
IotMqttConnection_t
struct _mqttConnection * IotMqttConnection_t
Opaque handle of an MQTT connection.
Definition: iot_mqtt_types.h:66
IotMqttSubscription_t::callback
IotMqttCallbackInfo_t callback
Callback to invoke when a message is received.
Definition: iot_mqtt_types.h:567
IotMqttNetworkInfo_t
Infomation on the transport-layer network connection for the new MQTT connection.
Definition: iot_mqtt_types.h:930
IotMqttSerializer_t
Function pointers for MQTT packet serializer overrides.
Definition: iot_mqtt_types.h:715
IOT_MQTT_RETRY_NO_RESPONSE
A QoS 1 PUBLISH received no response and the retry limit was reached.
Definition: iot_mqtt_types.h:252
IotMqttPublishInfo_t::qos
IotMqttQos_t qos
QoS of message. Must be 0 or 1.
Definition: iot_mqtt_types.h:399
IOT_MQTT_NOT_INITIALIZED
An API function was called before IotMqtt_Init.
Definition: iot_mqtt_types.h:267
IOT_MQTT_QOS_2
Definition: iot_mqtt_types.h:307
IotMqttCallbackParam_t::result
IotMqttError_t result
Result of operation, e.g. succeeded or failed.
Definition: iot_mqtt_types.h:464
IotMqttConnectInfo_t::clientIdentifierLength
uint16_t clientIdentifierLength
Length of IotMqttConnectInfo_t.pClientIdentifier.
Definition: iot_mqtt_types.h:677
IOT_MQTT_NETWORK_ERROR
MQTT operation failed because the network was unusable.
Definition: iot_mqtt_types.h:177
IotMqttConnectInfo_t::previousSubscriptionCount
size_t previousSubscriptionCount
The number of MQTT subscriptions present in a previous session, if any.
Definition: iot_mqtt_types.h:657
IOT_MQTT_QOS_0
Definition: iot_mqtt_types.h:305
IotMqttOperationType_t
IotMqttOperationType_t
Types of MQTT operations.
Definition: iot_mqtt_types.h:277
IotMqttConnectInfo_t::pPreviousSubscriptions
const IotMqttSubscription_t * pPreviousSubscriptions
An array of MQTT subscriptions present in a previous session, if any.
Definition: iot_mqtt_types.h:644
IotMqttSubscription_t::pTopicFilter
const char * pTopicFilter
Topic filter of subscription.
Definition: iot_mqtt_types.h:559
IOT_MQTT_BAD_PACKET_RECEIVED
Definition: iot_mqtt_types.h:323
IotMqttConnectInfo_t::pUserName
const char * pUserName
Username for MQTT connection.
Definition: iot_mqtt_types.h:681
IotMqttSubscription_t
Information on an MQTT subscription.
Definition: iot_mqtt_types.h:550
IOT_MQTT_INIT_FAILED
Initialization failed.
Definition: iot_mqtt_types.h:137
iot_network.h
IotNetworkInterface_t
IotMqttPublishInfo_t::payloadLength
size_t payloadLength
Length of IotMqttPublishInfo_t.pPayload. For LWT messages, this is limited to 65535.
Definition: iot_mqtt_types.h:406
IotMqttNetworkInfo_t::createNetworkConnection
bool createNetworkConnection
Whether a new network connection should be created.
Definition: iot_mqtt_types.h:947
IOT_MQTT_QOS_1
Definition: iot_mqtt_types.h:306
IotMqttSubscription_t::topicFilterLength
uint16_t topicFilterLength
Length of IotMqttSubscription_t.pTopicFilter.
Definition: iot_mqtt_types.h:560
IotMqttCallbackParam_t::info
IotMqttPublishInfo_t info
PUBLISH message received from the server.
Definition: iot_mqtt_types.h:472
IotMqttCallbackParam_t::pTopicFilter
const char * pTopicFilter
Topic filter that matched the message.
Definition: iot_mqtt_types.h:470
IotMqttPublishInfo_t
Information on a PUBLISH message.
Definition: iot_mqtt_types.h:397
IotMqttNetworkInfo_t::pNetworkCredentialInfo
void * pNetworkCredentialInfo
Credentials for the MQTT server, passed as pCredentialInfo to IotNetworkInterface_t::create.
Definition: iot_mqtt_types.h:971
IotMqttSubscription_t::qos
IotMqttQos_t qos
QoS of messages delivered on subscription.
Definition: iot_mqtt_types.h:557
IotMqttCallbackParam_t
Parameter to an MQTT callback function.
Definition: iot_mqtt_types.h:443
IOT_MQTT_BAD_RESPONSE
MQTT response packet received from the network is malformed.
Definition: iot_mqtt_types.h:205
IotMqttConnectInfo_t::passwordLength
uint16_t passwordLength
Length of IotMqttConnectInfo_t.pPassword.
Definition: iot_mqtt_types.h:684
IOT_MQTT_SCHEDULING_ERROR
MQTT operation could not be scheduled, i.e. enqueued for sending.
Definition: iot_mqtt_types.h:188
IOT_MQTT_DISCONNECT_CALLED
Definition: iot_mqtt_types.h:322
IotMqttNetworkInfo_t::pMqttSerializer
const IotMqttSerializer_t * pMqttSerializer
MQTT packet serializer overrides used by the new MQTT connection.
Definition: iot_mqtt_types.h:1005
IOT_MQTT_DISCONNECT
Definition: iot_mqtt_types.h:285
IotMqttConnectInfo_t::pWillInfo
const IotMqttPublishInfo_t * pWillInfo
A message to publish if the new MQTT connection is unexpectedly closed.
Definition: iot_mqtt_types.h:672
IotMqttConnectInfo_t::userNameLength
uint16_t userNameLength
Length of IotMqttConnectInfo_t.pUserName.
Definition: iot_mqtt_types.h:682
IOT_MQTT_PUBACK
Definition: iot_mqtt_types.h:281
IotMqttCallbackInfo_t::pCallbackContext
void * pCallbackContext
The first parameter to pass to the callback function to provide context.
Definition: iot_mqtt_types.h:518
IotMqttConnectInfo_t::pClientIdentifier
const char * pClientIdentifier
MQTT client identifier.
Definition: iot_mqtt_types.h:676
IotMqttConnectInfo_t
Information on a new MQTT connection.
Definition: iot_mqtt_types.h:585
IotMqttCallbackParam_t::type
IotMqttOperationType_t type
Type of operation that completed.
Definition: iot_mqtt_types.h:462
IotMqttNetworkInfo_t::pNetworkServerInfo
void * pNetworkServerInfo
Information on the MQTT server, passed as pConnectionInfo to IotNetworkInterface_t::create.
Definition: iot_mqtt_types.h:961