MQTT API Reference
MQTT 3.1.1 client library
IotMqtt_Connect

Establish a new MQTT connection.

const IotMqttConnectInfo_t * pConnectInfo,
uint32_t timeoutMs,
IotMqttConnection_t * const pMqttConnection );

This function opens a connection between a new MQTT client and an MQTT server (also called a broker). MQTT connections are established on top of transport layer protocols (such as TCP/IP), and optionally, application layer security protocols (such as TLS). The MQTT packet that establishes a connection is called the MQTT CONNECT packet. After IotMqtt_Init, this function must be called before any other MQTT library function.

If pConnectInfo->cleanSession is true, this function establishes a clean MQTT session. Subscriptions and unacknowledged PUBLISH messages will be discarded when the connection is closed.

If pConnectInfo->cleanSession is false, this function establishes (or re-establishes) a persistent MQTT session. The parameters pConnectInfo->pPreviousSubscriptions and pConnectInfo->previousSubscriptionCount may be used to restore subscriptions present in a re-established persistent session. Any restored subscriptions MUST have been present in the persistent session; this function does not send an MQTT SUBSCRIBE packet!

pConnectInfo->pPreviousSubscriptions and pConnectInfo->previousSubscriptionCount can also be used to pass a list of subscriptions to be stored locally without a SUBSCRIBE packet being sent to the broker. These subscriptions are useful to invoke application level callbacks for messages received on unsolicited topics from the broker.

This MQTT library is network agnostic, meaning it has no knowledge of the underlying network protocol carrying the MQTT packets. It interacts with the network through a network abstraction layer, allowing it to be used with many different network stacks. The network abstraction layer is established per-connection, allowing every IotMqttConnection_t to use a different network stack. The parameter pNetworkInterface sets up the network abstraction layer for an MQTT connection; see the documentation on IotMqttNetworkInfo_t for details on its members.

The pConnectInfo parameter provides the contents of the MQTT CONNECT packet. Most members are defined by the MQTT spec.. The pConnectInfo->pWillInfo member provides information on a Last Will and Testament (LWT) message to be published if the MQTT connection is closed without sending a DISCONNECT packet. Unlike other PUBLISH messages, a LWT message payload is limited to 65535 bytes in length. Additionally, the retry interval and limit members of IotMqttPublishInfo_t are ignored for LWT messages. The LWT message is optional; pWillInfo may be NULL.

Unlike IotMqtt_PublishAsync, IotMqtt_SubscribeAsync, and IotMqtt_UnsubscribeAsync, this function is always blocking. Additionally, because the MQTT connection acknowledgement packet (CONNACK packet) does not contain any information on which CONNECT packet it acknowledges, only one CONNECT operation may be in progress at any time. This means that parallel threads making calls to IotMqtt_Connect will be serialized to send their CONNECT packets one-by-one.

Parameters
[in]pNetworkInfoInformation on the transport-layer network connection to use with the MQTT connection.
[in]pConnectInfoMQTT connection setup parameters.
[in]timeoutMsIf the MQTT server does not accept the connection within this timeout in milliseconds, this function returns IOT_MQTT_TIMEOUT.
[out]pMqttConnectionSet to a newly-initialized MQTT connection handle if this function succeeds.
Returns
One of the following:

Example

// Callback function to receive messages from the broker on an unsolicited topic.
void unsolicitedMessageCallback( void * pArgument, IotMqttCallbackParam_t * pPublish );
// Parameters to MQTT connect.
// A local subscription to receive messages from the broker on an unsolicited topic.
// Example network abstraction types.
IotNetworkServerInfo_t serverInfo = { ... };
IotNetworkCredentials_t credentialInfo = { ... };
IotNetworkInterface_t networkInterface = { ... };
// Example using a generic network implementation.
networkInfo.createNetworkConnection = true;
networkInfo.u.setup.pNetworkServerInfo = &serverInfo;
networkInfo.u.setup.pNetworkCredentialInfo = &credentialInfo;
networkInfo.pNetworkInterface = &networkInterface;
// Set the members of the connection info (password and username not used).
connectInfo.cleanSession = true;
connectInfo.keepAliveSeconds = 30;
connectInfo.pClientIdentifier = "uniqueclientidentifier";
connectInfo.clientIdentifierLength = 22;
// Set the members of the will info (retain and retry not used).
willInfo.qos = IOT_MQTT_QOS_1;
willInfo.pTopicName = "will/topic/name";
willInfo.topicNameLength = ( uint16_t ) strlen( willInfo.pTopicName );
willInfo.pPayload = "MQTT client unexpectedly disconnected.";
willInfo.payloadLength = strlen( willInfo.pPayload );
// Set the pointer to the will info.
connectInfo.pWillInfo = &willInfo;
// [Optional] Set a local subscription to receive the broker messages on an unsolicited topic.
subscription.qos = IOT_MQTT_QOS_0;
subscription.pTopicFilter = "some/unsolicited/topic";
subscription.topicLength = ( uint16_t ) strlen( subscription.pTopicFilter );
subscription.callback.function = unsolicitedMessageCallback;
connectInfo.pPreviousSubscriptions = &subscription;
connectInfo.previousSubscriptionCount = 1;
// Call CONNECT with a 5 second block time. Should return
// IOT_MQTT_SUCCESS when successful.
IotMqttError_t result = IotMqtt_Connect( &networkInfo,
&connectInfo,
5000,
&mqttConnection );
if( result == IOT_MQTT_SUCCESS )
{
// Do something with the MQTT connection...
// Clean up and close the MQTT connection once it's no longer needed.
IotMqtt_Disconnect( mqttConnection, 0 );
}
IotMqttNetworkInfo_t::pNetworkInterface
const IotNetworkInterface_t * pNetworkInterface
The network functions used by the new MQTT connection.
Definition: iot_mqtt_types.h:1053
IOT_MQTT_CONNECT_INFO_INITIALIZER
#define IOT_MQTT_CONNECT_INFO_INITIALIZER
Initializer for IotMqttConnectInfo_t.
Definition: iot_mqtt_types.h:1124
IotMqttConnectInfo_t::keepAliveSeconds
uint16_t keepAliveSeconds
Period of keep-alive messages. Set to 0 to disable keep-alive.
Definition: iot_mqtt_types.h:667
IotMqttConnectInfo_t::cleanSession
bool cleanSession
Whether this connection is a clean session.
Definition: iot_mqtt_types.h:622
IotNetworkServerInfo_t
_IotNetworkServerInfo_t IotNetworkServerInfo_t
IotMqtt_Disconnect
void IotMqtt_Disconnect(IotMqttConnection_t mqttConnection, uint32_t flags)
Closes an MQTT connection and frees resources.
Definition: iot_mqtt_api.c:1334
IotMqttError_t
IotMqttError_t
Return codes of MQTT functions.
Definition: iot_mqtt_types.h:103
IotMqttPublishInfo_t::pPayload
const void * pPayload
Payload of PUBLISH.
Definition: iot_mqtt_types.h:396
IOT_MQTT_SUCCESS
MQTT operation completed successfully.
Definition: iot_mqtt_types.h:119
IotMqttPublishInfo_t::topicNameLength
uint16_t topicNameLength
Length of IotMqttPublishInfo_t.pTopicName.
Definition: iot_mqtt_types.h:394
IOT_MQTT_NETWORK_INFO_INITIALIZER
#define IOT_MQTT_NETWORK_INFO_INITIALIZER
Initializer for IotMqttNetworkInfo_t.
Definition: iot_mqtt_types.h:1120
IotMqttPublishInfo_t::pTopicName
const char * pTopicName
Topic name of PUBLISH.
Definition: iot_mqtt_types.h:393
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:558
IOT_MQTT_CONNECTION_INITIALIZER
#define IOT_MQTT_CONNECTION_INITIALIZER
Initializer for IotMqttConnection_t.
Definition: iot_mqtt_types.h:1132
IotMqttNetworkInfo_t
MQTT network connection details.
Definition: iot_mqtt_types.h:993
IotMqttPublishInfo_t::qos
IotMqttQos_t qos
QoS of message. Must be 0 or 1.
Definition: iot_mqtt_types.h:390
IotMqttNetworkInfo_t::u
union IotMqttNetworkInfo_t::@5 u
Valid member depends of IotMqttNetworkInfo_t.createNetworkConnection.
IotMqttConnectInfo_t::clientIdentifierLength
uint16_t clientIdentifierLength
Length of IotMqttConnectInfo_t.pClientIdentifier.
Definition: iot_mqtt_types.h:670
IotMqttConnectInfo_t::previousSubscriptionCount
size_t previousSubscriptionCount
The number of MQTT subscriptions present in a previous session, if any.
Definition: iot_mqtt_types.h:650
IOT_MQTT_QOS_0
Definition: iot_mqtt_types.h:305
IotMqttConnectInfo_t::pPreviousSubscriptions
const IotMqttSubscription_t * pPreviousSubscriptions
An array of MQTT subscriptions present in a previous session, if any.
Definition: iot_mqtt_types.h:638
IotNetworkCredentials_t
_IotNetworkCredentials_t IotNetworkCredentials_t
IotMqttSubscription_t::pTopicFilter
const char * pTopicFilter
Topic filter of subscription.
Definition: iot_mqtt_types.h:550
IotMqttSubscription_t
MQTT subscription.
Definition: iot_mqtt_types.h:541
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:397
IotMqttNetworkInfo_t::createNetworkConnection
bool createNetworkConnection
Whether a new network connection should be created.
Definition: iot_mqtt_types.h:1010
IOT_MQTT_QOS_1
Definition: iot_mqtt_types.h:306
IOT_MQTT_SUBSCRIPTION_INITIALIZER
#define IOT_MQTT_SUBSCRIPTION_INITIALIZER
Initializer for IotMqttSubscription_t.
Definition: iot_mqtt_types.h:1128
IotMqttPublishInfo_t
Information on a PUBLISH message.
Definition: iot_mqtt_types.h:388
IotMqttSubscription_t::qos
IotMqttQos_t qos
QoS of messages delivered on subscription.
Definition: iot_mqtt_types.h:548
IotMqttCallbackParam_t
Parameter to an MQTT callback function.
Definition: iot_mqtt_types.h:434
IOT_MQTT_PUBLISH_INFO_INITIALIZER
#define IOT_MQTT_PUBLISH_INFO_INITIALIZER
Initializer for IotMqttPublishInfo_t.
Definition: iot_mqtt_types.h:1126
IotMqttConnectInfo_t::pWillInfo
const IotMqttPublishInfo_t * pWillInfo
A message to publish if the new MQTT connection is unexpectedly closed.
Definition: iot_mqtt_types.h:665
IotMqttConnectInfo_t::pClientIdentifier
const char * pClientIdentifier
MQTT client identifier.
Definition: iot_mqtt_types.h:669
IotMqttCallbackInfo_t::function
void(* function)(void *, IotMqttCallbackParam_t *)
User-provided callback function signature.
Definition: iot_mqtt_types.h:520
IotMqtt_Connect
IotMqttError_t IotMqtt_Connect(const IotMqttNetworkInfo_t *pNetworkInfo, const IotMqttConnectInfo_t *pConnectInfo, uint32_t timeoutMs, IotMqttConnection_t *const pMqttConnection)
Establish a new MQTT connection.
Definition: iot_mqtt_api.c:1081
IotMqttConnectInfo_t
MQTT connection details.
Definition: iot_mqtt_types.h:576