coreMQTT v2.1.1
MQTT 3.1.1 Client Library
MQTT_Connect

Establish an MQTT session.

const MQTTConnectInfo_t * pConnectInfo,
const MQTTPublishInfo_t * pWillInfo,
uint32_t timeoutMs,
bool * pSessionPresent );
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:2616
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:99
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:145
A struct representing an MQTT connection.
Definition: core_mqtt.h:162
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:214

This function will send MQTT CONNECT packet and receive a CONNACK packet. The send and receive from the network is done through the transport interface.

The maximum time this function waits for a CONNACK is decided in one of the following ways:

  1. If timeoutMs is greater than 0: MQTTContext_t.getTime is used to ensure that the function does not wait more than timeoutMs for CONNACK.
  2. If timeoutMs is 0: The network receive for CONNACK is retried up to the number of times configured by MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
Note
If a dummy MQTTGetCurrentTimeFunc_t was passed to MQTT_Init, then a timeout value of 0 MUST be passed to the API, and the MQTT_RECV_POLLING_TIMEOUT_MS and MQTT_SEND_TIMEOUT_MS timeout configurations MUST be set to 0.
Parameters
[in]pContextInitialized MQTT context.
[in]pConnectInfoMQTT CONNECT packet information.
[in]pWillInfoLast Will and Testament. Pass NULL if Last Will and Testament is not used.
[in]timeoutMsMaximum time in milliseconds to wait for a CONNACK packet. A zero timeout makes use of the retries for receiving CONNACK as configured with MQTT_MAX_CONNACK_RECEIVE_RETRY_COUNT.
[out]pSessionPresentThis value will be set to true if a previous session was present; otherwise it will be set to false. It is only relevant if not establishing a clean session.
Returns
MQTTNoMemory if the MQTTContext_t.networkBuffer is too small to hold the MQTT packet; MQTTBadParameter if invalid parameters are passed; MQTTSendFailed if transport send failed; MQTTRecvFailed if transport receive failed for CONNACK; MQTTNoDataAvailable if no data available to receive in transport until the timeoutMs for CONNACK; MQTTSuccess otherwise.
Note
This API may spend more time than provided in the timeoutMS parameters in certain conditions as listed below:
  1. Timeouts are incorrectly configured - If the timeoutMS is less than the transport receive timeout and if a CONNACK packet is not received within the transport receive timeout, the API will spend the transport receive timeout (which is more time than the timeoutMs). It is the case of incorrect timeout configuration as the timeoutMs parameter passed to this API must be greater than the transport receive timeout. Please refer to the transport interface documentation for more details about timeout configurations.
  2. Partial CONNACK packet is received right before the expiry of the timeout - It is possible that first two bytes of CONNACK packet (packet type and remaining length) are received right before the expiry of the timeoutMS. In that case, the API makes one more network receive call in an attempt to receive the remaining 2 bytes. In the worst case, it can happen that the remaining 2 bytes are never received and this API will end up spending timeoutMs + transport receive timeout.

Example

// Variables used in this example.
MQTTStatus_t status;
MQTTConnectInfo_t connectInfo = { 0 };
MQTTPublishInfo_t willInfo = { 0 };
bool sessionPresent;
// This is assumed to have been initialized before calling this function.
MQTTContext_t * pContext;
// True for creating a new session with broker, false if we want to resume an old one.
connectInfo.cleanSession = true;
// Client ID must be unique to broker. This field is required.
connectInfo.pClientIdentifier = "someClientID";
connectInfo.clientIdentifierLength = strlen( connectInfo.pClientIdentifier );
// The following fields are optional.
// Value for keep alive.
connectInfo.keepAliveSeconds = 60;
// Optional username and password.
connectInfo.pUserName = "someUserName";
connectInfo.userNameLength = strlen( connectInfo.pUserName );
connectInfo.pPassword = "somePassword";
connectInfo.passwordLength = strlen( connectInfo.pPassword );
// The last will and testament is optional, it will be published by the broker
// should this client disconnect without sending a DISCONNECT packet.
willInfo.qos = MQTTQoS0;
willInfo.pTopicName = "/lwt/topic/name";
willInfo.topicNameLength = strlen( willInfo.pTopicName );
willInfo.pPayload = "LWT Message";
willInfo.payloadLength = strlen( "LWT Message" );
// Send the connect packet. Use 100 ms as the timeout to wait for the CONNACK packet.
status = MQTT_Connect( pContext, &connectInfo, &willInfo, 100, &sessionPresent );
if( status == MQTTSuccess )
{
// Since we requested a clean session, this must be false
assert( sessionPresent == false );
// Do something with the connection.
}
@ MQTTSuccess
Definition: core_mqtt_serializer.h:100
@ MQTTQoS0
Definition: core_mqtt_serializer.h:122
const char * pClientIdentifier
MQTT client identifier. Must be unique per client.
Definition: core_mqtt_serializer.h:159
const char * pUserName
MQTT user name. Set to NULL if not used.
Definition: core_mqtt_serializer.h:169
bool cleanSession
Whether to establish a new, clean session or resume a previous session.
Definition: core_mqtt_serializer.h:149
uint16_t userNameLength
Length of MQTT user name. Set to 0 if not used.
Definition: core_mqtt_serializer.h:174
uint16_t keepAliveSeconds
MQTT keep alive period.
Definition: core_mqtt_serializer.h:154
uint16_t clientIdentifierLength
Length of the client identifier.
Definition: core_mqtt_serializer.h:164
uint16_t passwordLength
Length of MQTT password. Set to 0 if not used.
Definition: core_mqtt_serializer.h:184
const char * pPassword
MQTT password. Set to NULL if not used.
Definition: core_mqtt_serializer.h:179
MQTTQoS_t qos
Quality of Service for message.
Definition: core_mqtt_serializer.h:218
uint16_t topicNameLength
Length of topic name.
Definition: core_mqtt_serializer.h:238
size_t payloadLength
Message payload length.
Definition: core_mqtt_serializer.h:248
const char * pTopicName
Topic name on which the message is published.
Definition: core_mqtt_serializer.h:233
const void * pPayload
Message payload.
Definition: core_mqtt_serializer.h:243