MQTT API Reference
MQTT 3.1.1 client library
IotMqttConnectInfo_t Struct Reference

Information on a new MQTT connection. More...

#include <iot_mqtt_types.h>

Data Fields

bool awsIotMqttMode
 Specifies if this MQTT connection is to an AWS IoT MQTT server. More...
 
bool cleanSession
 Whether this connection is a clean session. More...
 
const IotMqttSubscription_tpPreviousSubscriptions
 An array of MQTT subscriptions present in a previous session, if any. More...
 
size_t previousSubscriptionCount
 The number of MQTT subscriptions present in a previous session, if any. More...
 
const IotMqttPublishInfo_tpWillInfo
 A message to publish if the new MQTT connection is unexpectedly closed. More...
 
uint16_t keepAliveSeconds
 Period of keep-alive messages. Set to 0 to disable keep-alive.
 
const char * pClientIdentifier
 MQTT client identifier.
 
uint16_t clientIdentifierLength
 Length of IotMqttConnectInfo_t.pClientIdentifier.
 
const char * pUserName
 Username for MQTT connection.
 
uint16_t userNameLength
 Length of IotMqttConnectInfo_t.pUserName.
 
const char * pPassword
 Password for MQTT connection.
 
uint16_t passwordLength
 Length of IotMqttConnectInfo_t.pPassword.
 

Detailed Description

Information on a new MQTT connection.

Parameter for: IotMqtt_Connect

Passed as an argument to IotMqtt_Connect. Most members of this struct correspond to the content of an MQTT CONNECT packet.

All instances of IotMqttConnectInfo_t should be initialized with IOT_MQTT_CONNECT_INFO_INITIALIZER.

Note
The lengths of the strings in this struct should not include the NULL terminator. Strings in this struct do not need to be NULL-terminated.

Field Documentation

◆ awsIotMqttMode

bool IotMqttConnectInfo_t::awsIotMqttMode

Specifies if this MQTT connection is to an AWS IoT MQTT server.

The AWS IoT MQTT broker differs somewhat from the MQTT specification. When this member is true, the MQTT library will accommodate these differences. This setting should be false when communicating with a fully-compliant MQTT broker.

Attention
This setting MUST be true when using the AWS IoT MQTT server; it MUST be false otherwise.
Note
Currently, IOT_MQTT_CONNECT_INFO_INITIALIZER sets this this member to true.

◆ cleanSession

bool IotMqttConnectInfo_t::cleanSession

Whether this connection is a clean session.

MQTT servers can maintain and topic filter subscriptions and unacknowledged PUBLISH messages. These form part of an MQTT session, which is identified by the client identifier.

Setting this value to true establishes a clean session, which causes the MQTT server to discard any previous session data for a client identifier. When the client disconnects, the server discards all session data. If this value is true, IotMqttConnectInfo_t.pPreviousSubscriptions and IotMqttConnectInfo_t.previousSubscriptionCount are ignored.

Setting this value to false does one of the following:

  • If no previous session exists, the MQTT server will create a new persistent session. The server may maintain subscriptions and unacknowledged PUBLISH messages after a client disconnects, to be restored once the same client identifier reconnects.
  • If a previous session exists, the MQTT server restores all of the session's subscriptions for the client identifier and may immediately transmit any unacknowledged PUBLISH packets to the client.

When a client with a persistent session disconnects, the MQTT server continues to maintain all subscriptions and unacknowledged PUBLISH messages. The client must also remember the session subscriptions to restore them upon reconnecting. IotMqttConnectInfo_t.pPreviousSubscriptions and IotMqttConnectInfo_t.previousSubscriptionCount are used to restore a previous session's subscriptions client-side.

◆ pPreviousSubscriptions

const IotMqttSubscription_t* IotMqttConnectInfo_t::pPreviousSubscriptions

An array of MQTT subscriptions present in a previous session, if any.

Pointer to the start of an array of subscriptions present a previous session, if any. These subscriptions will be immediately restored upon reconnecting.

This member is ignored if it is NULL or IotMqttConnectInfo_t.cleanSession is true. If this member is not NULL, IotMqttConnectInfo_t.previousSubscriptionCount must be nonzero.

◆ previousSubscriptionCount

size_t IotMqttConnectInfo_t::previousSubscriptionCount

The number of MQTT subscriptions present in a previous session, if any.

Number of subscriptions contained in the array IotMqttConnectInfo_t.pPreviousSubscriptions.

This value is ignored if IotMqttConnectInfo_t.pPreviousSubscriptions is NULL or IotMqttConnectInfo_t.cleanSession is true. If IotMqttConnectInfo_t.pPreviousSubscriptions is not NULL, this value must be nonzero.

◆ pWillInfo

const IotMqttPublishInfo_t* IotMqttConnectInfo_t::pWillInfo

A message to publish if the new MQTT connection is unexpectedly closed.

A Last Will and Testament (LWT) message may be published if this connection is closed without sending an MQTT DISCONNECT packet. This pointer should be set to an IotMqttPublishInfo_t representing any LWT message to publish. If an LWT is not needed, this member must be set to NULL.

Unlike other PUBLISH messages, an LWT message is limited to 65535 bytes in length. Additionally, pWillInfo->retryMs and pWillInfo->retryLimit will be ignored.


The documentation for this struct was generated from the following file: