coreMQTT
v1.1.1
MQTT 3.1.1 Client Library
|
|
Establish an MQTT session.
uint32_t timeoutMs,
bool * pSessionPresent );
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:
- If
timeoutMs
is greater than 0: MQTTContext_t.getTime is used to ensure that the function does not wait more than timeoutMs
for CONNACK.
- 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_RETRY_TIMEOUT_MS timeout configurations MUST be set to 0.
- Parameters
-
[in] | pContext | Initialized MQTT context. |
[in] | pConnectInfo | MQTT CONNECT packet information. |
[in] | pWillInfo | Last Will and Testament. Pass NULL if Last Will and Testament is not used. |
[in] | timeoutMs | Maximum 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] | pSessionPresent | Whether a previous session was present. 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:
- 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.
- 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
bool sessionPresent;
status =
MQTT_Connect( pContext, &connectInfo, &willInfo, 100, &sessionPresent );
{
assert( sessionPresent == false );
}
uint16_t topicNameLength
Length of topic name.
Definition: core_mqtt_serializer.h:227
MQTT CONNECT packet parameters.
Definition: core_mqtt_serializer.h:134
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:1750
const void * pPayload
Message payload.
Definition: core_mqtt_serializer.h:232
const char * pClientIdentifier
MQTT client identifier. Must be unique per client.
Definition: core_mqtt_serializer.h:148
MQTTStatus_t
Return codes from MQTT functions.
Definition: core_mqtt_serializer.h:91
uint16_t keepAliveSeconds
MQTT keep alive period.
Definition: core_mqtt_serializer.h:143
const char * pPassword
MQTT password. Set to NULL if not used.
Definition: core_mqtt_serializer.h:168
uint16_t passwordLength
Length of MQTT password. Set to 0 if not used.
Definition: core_mqtt_serializer.h:173
const char * pTopicName
Topic name on which the message is published.
Definition: core_mqtt_serializer.h:222
A struct representing an MQTT connection.
Definition: core_mqtt.h:163
bool cleanSession
Whether to establish a new, clean session or resume a previous session.
Definition: core_mqtt_serializer.h:138
uint16_t clientIdentifierLength
Length of the client identifier.
Definition: core_mqtt_serializer.h:153
MQTTQoS_t qos
Quality of Service for message.
Definition: core_mqtt_serializer.h:207
@ MQTTSuccess
Definition: core_mqtt_serializer.h:92
MQTT PUBLISH packet parameters.
Definition: core_mqtt_serializer.h:203
uint16_t userNameLength
Length of MQTT user name. Set to 0 if not used.
Definition: core_mqtt_serializer.h:163
size_t payloadLength
Message payload length.
Definition: core_mqtt_serializer.h:237
@ MQTTQoS0
Definition: core_mqtt_serializer.h:111
const char * pUserName
MQTT user name. Set to NULL if not used.
Definition: core_mqtt_serializer.h:158