AWS IoT Device SDK C:
MQTT
MQTT 3.1.1 client library
|
Return to main page ↑ |
User-facing functions of the MQTT 3.1.1 library. More...
Go to the source code of this file.
Functions | |
IotMqttError_t | IotMqtt_Init (void) |
One-time initialization function for the MQTT library. More... | |
void | IotMqtt_Cleanup (void) |
One-time deinitialization function for the MQTT library. More... | |
void | IotMqtt_ReceiveCallback (IotNetworkConnection_t pNetworkConnection, void *pReceiveContext) |
Network receive callback for the MQTT library. More... | |
IotMqttError_t | IotMqtt_Connect (const IotMqttNetworkInfo_t *pNetworkInfo, const IotMqttConnectInfo_t *pConnectInfo, uint32_t timeoutMs, IotMqttConnection_t *const pMqttConnection) |
Establish a new MQTT connection. More... | |
void | IotMqtt_Disconnect (IotMqttConnection_t mqttConnection, uint32_t flags) |
Closes an MQTT connection and frees resources. More... | |
IotMqttError_t | IotMqtt_SubscribeAsync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pSubscribeOperation) |
Subscribes to the given array of topic filters and optionally receive an asynchronous notification when the subscribe completes. More... | |
IotMqttError_t | IotMqtt_SubscribeSync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, uint32_t timeoutMs) |
Subscribes to the given array of topic filters with a timeout. More... | |
IotMqttError_t | IotMqtt_UnsubscribeAsync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pUnsubscribeOperation) |
Unsubscribes from the given array of topic filters and optionally receive an asynchronous notification when the unsubscribe completes. More... | |
IotMqttError_t | IotMqtt_UnsubscribeSync (IotMqttConnection_t mqttConnection, const IotMqttSubscription_t *pSubscriptionList, size_t subscriptionCount, uint32_t flags, uint32_t timeoutMs) |
Unsubscribes from a given array of topic filters with a timeout. More... | |
IotMqttError_t | IotMqtt_PublishAsync (IotMqttConnection_t mqttConnection, const IotMqttPublishInfo_t *pPublishInfo, uint32_t flags, const IotMqttCallbackInfo_t *pCallbackInfo, IotMqttOperation_t *const pPublishOperation) |
Publishes a message to the given topic name and optionally receive an asynchronous notification when the publish completes. More... | |
IotMqttError_t | IotMqtt_PublishSync (IotMqttConnection_t mqttConnection, const IotMqttPublishInfo_t *pPublishInfo, uint32_t flags, uint32_t timeoutMs) |
Publish a message to the given topic name with a timeout. More... | |
IotMqttError_t | IotMqtt_Wait (IotMqttOperation_t operation, uint32_t timeoutMs) |
Waits for an operation to complete. More... | |
const char * | IotMqtt_strerror (IotMqttError_t status) |
Returns a string that describes an IotMqttError_t. More... | |
const char * | IotMqtt_OperationType (IotMqttOperationType_t operation) |
Returns a string that describes an IotMqttOperationType_t. More... | |
bool | IotMqtt_IsSubscribed (IotMqttConnection_t mqttConnection, const char *pTopicFilter, uint16_t topicFilterLength, IotMqttSubscription_t *const pCurrentSubscription) |
Check if an MQTT connection has a subscription for a topic filter. More... | |
User-facing functions of the MQTT 3.1.1 library.
IotMqttError_t IotMqtt_Init | ( | void | ) |
One-time initialization function for the MQTT library.
This function performs setup of the MQTT library. It must be called once (and only once) before calling any other MQTT function. Calling this function more than once without first calling IotMqtt_Cleanup may result in a crash.
void IotMqtt_Cleanup | ( | void | ) |
One-time deinitialization function for the MQTT library.
This function frees resources taken in IotMqtt_Init. It should be called after closing all MQTT connections to clean up the MQTT library. After this function returns, IotMqtt_Init must be called again before calling any other MQTT function.
void IotMqtt_ReceiveCallback | ( | IotNetworkConnection_t | pNetworkConnection, |
void * | pReceiveContext | ||
) |
Network receive callback for the MQTT library.
This function should be called by the system whenever data is available for the MQTT library.
[in] | pNetworkConnection | The network connection associated with the MQTT connection, passed by the network stack. |
[in] | pReceiveContext | A pointer to the MQTT connection handle for which the packet was received. |
IotMqttError_t IotMqtt_Connect | ( | const IotMqttNetworkInfo_t * | pNetworkInfo, |
const IotMqttConnectInfo_t * | pConnectInfo, | ||
uint32_t | timeoutMs, | ||
IotMqttConnection_t *const | pMqttConnection | ||
) |
Establish a new MQTT connection.
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.
MQTT keep-alive is configured by IotMqttConnectInfo_t::keepAliveSeconds. Keep-alive is used to detect half-open or otherwise unusable network connections. An MQTT client will send periodic ping requests (PINGREQ) to the server if the connection is idle. The MQTT server must respond to ping requests with a ping response (PINGRESP). The standard does not specify how long the server has to respond to a ping request, noting only a "reasonable amount of time". In this library, the amount of time a server has to respond to a ping request is set with IOT_MQTT_RESPONSE_WAIT_MS.
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.
[in] | pNetworkInfo | Information on the transport-layer network connection to use with the MQTT connection. |
[in] | pConnectInfo | MQTT connection setup parameters. |
[in] | timeoutMs | If the MQTT server does not accept the connection within this timeout in milliseconds, this function returns IOT_MQTT_TIMEOUT. |
[out] | pMqttConnection | Set to a newly-initialized MQTT connection handle if this function succeeds. |
Example
void IotMqtt_Disconnect | ( | IotMqttConnection_t | mqttConnection, |
uint32_t | flags | ||
) |
Closes an MQTT connection and frees resources.
This function closes an MQTT connection and should only be called once the MQTT connection is no longer needed. Its exact behavior depends on the flags
parameter.
Normally, flags
should be 0
. This gracefully shuts down an MQTT connection by sending an MQTT DISCONNECT packet. Any network close function provided when the connection was established will also be called. Note that because the MQTT server will not acknowledge a DISCONNECT packet, the client has no way of knowing if the server received the DISCONNECT packet. In the case where the DISCONNECT packet is lost in transport, any Last Will and Testament (LWT) message established with the connection may be published. However, if the DISCONNECT reaches the MQTT server, the LWT message will be discarded and not published.
Should the underlying network connection become unusable, this function should be called with flags
set to IOT_MQTT_FLAG_CLEANUP_ONLY. In this case, no DISCONNECT packet will be sent, though the network close function will still be called. This function will only free the resources used by the MQTT connection; it still must be called even if the network is offline to avoid leaking resources.
IotMqtt_Disconnect modifies mqttConnection
, so it shouldn't be used after calling this function.
[in] | mqttConnection | The MQTT connection to close and clean up. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. |
IotMqttError_t IotMqtt_SubscribeAsync | ( | IotMqttConnection_t | mqttConnection, |
const IotMqttSubscription_t * | pSubscriptionList, | ||
size_t | subscriptionCount, | ||
uint32_t | flags, | ||
const IotMqttCallbackInfo_t * | pCallbackInfo, | ||
IotMqttOperation_t *const | pSubscribeOperation | ||
) |
Subscribes to the given array of topic filters and optionally receive an asynchronous notification when the subscribe completes.
This function sends an MQTT SUBSCRIBE packet to the server. A SUBSCRIBE packet notifies the server to send any matching PUBLISH messages to this client. A single SUBSCRIBE packet may carry more than one topic filter, hence the parameters to this function include an array of subscriptions.
An MQTT subscription has two pieces:
The helper function IotMqtt_IsSubscribed can be used to check if a callback function is registered for a particular topic filter.
To modify an already-registered subscription callback, call this function with a new pSubscriptionList
. Any topic filters in pSubscriptionList
that already have a registered callback will be replaced with the new values in pSubscriptionList
.
[in] | mqttConnection | The MQTT connection to use for the subscription. |
[in] | pSubscriptionList | Pointer to the first element in the array of subscriptions. |
[in] | subscriptionCount | The number of elements in pSubscriptionList. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. |
[in] | pCallbackInfo | Asynchronous notification of this function's completion (NULL to disable). |
[out] | pSubscribeOperation | Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the subscription operation completes. |
Example
IotMqttError_t IotMqtt_SubscribeSync | ( | IotMqttConnection_t | mqttConnection, |
const IotMqttSubscription_t * | pSubscriptionList, | ||
size_t | subscriptionCount, | ||
uint32_t | flags, | ||
uint32_t | timeoutMs | ||
) |
Subscribes to the given array of topic filters with a timeout.
This function sends an MQTT SUBSCRIBE packet to the server, then waits for a server response to the packet. Internally, this function is a call to IotMqtt_SubscribeAsync followed by IotMqtt_Wait. See IotMqtt_SubscribeAsync for more information about the MQTT SUBSCRIBE operation.
[in] | mqttConnection | The MQTT connection to use for the subscription. |
[in] | pSubscriptionList | Pointer to the first element in the array of subscriptions. |
[in] | subscriptionCount | The number of elements in pSubscriptionList. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. Currently, flags are ignored by this function; this parameter is for future-compatibility. |
[in] | timeoutMs | If the MQTT server does not acknowledge the subscriptions within this timeout in milliseconds, this function returns IOT_MQTT_TIMEOUT. |
IotMqttError_t IotMqtt_UnsubscribeAsync | ( | IotMqttConnection_t | mqttConnection, |
const IotMqttSubscription_t * | pSubscriptionList, | ||
size_t | subscriptionCount, | ||
uint32_t | flags, | ||
const IotMqttCallbackInfo_t * | pCallbackInfo, | ||
IotMqttOperation_t *const | pUnsubscribeOperation | ||
) |
Unsubscribes from the given array of topic filters and optionally receive an asynchronous notification when the unsubscribe completes.
This function sends an MQTT UNSUBSCRIBE packet to the server. An UNSUBSCRIBE packet removes registered topic filters from the server. After unsubscribing, the server will no longer send messages on these topic filters to the client.
Corresponding subscription callback functions are also removed from the MQTT connection. These subscription callback functions will be removed even if the MQTT UNSUBSCRIBE packet fails to send.
[in] | mqttConnection | The MQTT connection used for the subscription. |
[in] | pSubscriptionList | Pointer to the first element in the array of subscriptions. |
[in] | subscriptionCount | The number of elements in pSubscriptionList. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. |
[in] | pCallbackInfo | Asynchronous notification of this function's completion (NULL to disable). |
[out] | pUnsubscribeOperation | Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the unsubscribe operation completes. |
IotMqttError_t IotMqtt_UnsubscribeSync | ( | IotMqttConnection_t | mqttConnection, |
const IotMqttSubscription_t * | pSubscriptionList, | ||
size_t | subscriptionCount, | ||
uint32_t | flags, | ||
uint32_t | timeoutMs | ||
) |
Unsubscribes from a given array of topic filters with a timeout.
This function sends an MQTT UNSUBSCRIBE packet to the server, then waits for a server response to the packet. Internally, this function is a call to IotMqtt_UnsubscribeAsync followed by IotMqtt_Wait. See IotMqtt_UnsubscribeAsync for more information about the MQTT UNSUBSCRIBE operation.
[in] | mqttConnection | The MQTT connection used for the subscription. |
[in] | pSubscriptionList | Pointer to the first element in the array of subscriptions. |
[in] | subscriptionCount | The number of elements in pSubscriptionList. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. Flags are currently ignored but reserved for future use. |
[in] | timeoutMs | If the MQTT server does not acknowledge the UNSUBSCRIBE within this timeout in milliseconds, this function returns IOT_MQTT_TIMEOUT. |
IotMqttError_t IotMqtt_PublishAsync | ( | IotMqttConnection_t | mqttConnection, |
const IotMqttPublishInfo_t * | pPublishInfo, | ||
uint32_t | flags, | ||
const IotMqttCallbackInfo_t * | pCallbackInfo, | ||
IotMqttOperation_t *const | pPublishOperation | ||
) |
Publishes a message to the given topic name and optionally receive an asynchronous notification when the publish completes.
This function sends an MQTT PUBLISH packet to the server. A PUBLISH packet contains a payload and a topic name. Any clients with a subscription on a topic filter matching the PUBLISH topic name will receive a copy of the PUBLISH packet from the server.
If a PUBLISH packet fails to reach the server and it is not a QoS 0 message, it will be retransmitted. See IotMqttPublishInfo_t for a description of the retransmission strategy.
[in] | mqttConnection | The MQTT connection to use for the publish. |
[in] | pPublishInfo | MQTT publish parameters. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. |
[in] | pCallbackInfo | Asynchronous notification of this function's completion (NULL to disable). |
[out] | pPublishOperation | Set to a handle by which this operation may be referenced after this function returns. This reference is invalidated once the publish operation completes. |
pCallbackInfo
and pPublishOperation
should only be used for QoS 1 publishes. For QoS 0, they should both be NULL
.Example
IotMqttError_t IotMqtt_PublishSync | ( | IotMqttConnection_t | mqttConnection, |
const IotMqttPublishInfo_t * | pPublishInfo, | ||
uint32_t | flags, | ||
uint32_t | timeoutMs | ||
) |
Publish a message to the given topic name with a timeout.
This function sends an MQTT PUBLISH packet to the server, then waits for a server response to the packet. Internally, this function is a call to IotMqtt_PublishAsync followed by IotMqtt_Wait. See IotMqtt_PublishAsync for more information about the MQTT PUBLISH operation.
[in] | mqttConnection | The MQTT connection to use for the publish. |
[in] | pPublishInfo | MQTT publish parameters. |
[in] | flags | Flags which modify the behavior of this function. See MQTT Function Flags. Currently, flags are ignored by this function; this parameter is for future-compatibility. |
[in] | timeoutMs | If the MQTT server does not acknowledge a QoS 1 PUBLISH within this timeout in milliseconds, this function returns IOT_MQTT_TIMEOUT. This parameter is ignored for QoS 0 PUBLISH messages. |
IotMqttError_t IotMqtt_Wait | ( | IotMqttOperation_t | operation, |
uint32_t | timeoutMs | ||
) |
Waits for an operation to complete.
This function blocks to wait for a subscribe, unsubscribe, or publish to complete. These operations are by default asynchronous; the function calls queue an operation for processing, and a callback is invoked once the operation is complete.
To use this function, the flag IOT_MQTT_FLAG_WAITABLE must have been set in the operation's function call. Additionally, this function must always be called with any waitable operation to clean up resources.
Regardless of its return value, this function always clean up resources used by the waitable operation. This means reference
is invalidated as soon as this function returns, even if it returns IOT_MQTT_TIMEOUT or another error.
[in] | operation | Reference to the operation to wait for. The flag IOT_MQTT_FLAG_WAITABLE must have been set for this operation. |
[in] | timeoutMs | How many milliseconds to wait before returning IOT_MQTT_TIMEOUT. |
reference
. See IotMqttError_t for possible return values.Example
const char* IotMqtt_strerror | ( | IotMqttError_t | status | ) |
Returns a string that describes an IotMqttError_t.
Like the POSIX strerror
, this function returns a string describing a return code. In this case, the return code is an MQTT library error code, status
.
The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.
[in] | status | The status to describe. |
status
.const char* IotMqtt_OperationType | ( | IotMqttOperationType_t | operation | ) |
Returns a string that describes an IotMqttOperationType_t.
This function returns a string describing an MQTT operation type, operation
.
The string returned by this function MUST be treated as read-only: any attempt to modify its contents may result in a crash. Therefore, this function is limited to usage in logging.
[in] | operation | The operation to describe. |
operation
.bool IotMqtt_IsSubscribed | ( | IotMqttConnection_t | mqttConnection, |
const char * | pTopicFilter, | ||
uint16_t | topicFilterLength, | ||
IotMqttSubscription_t *const | pCurrentSubscription | ||
) |
Check if an MQTT connection has a subscription for a topic filter.
This function checks whether an MQTT connection mqttConnection
has a subscription callback registered for a topic filter pTopicFilter
. If a subscription callback is found, its details are copied into the output parameter pCurrentSubscription
. This subscription callback will be invoked for incoming PUBLISH messages on pTopicFilter
.
The check for a matching subscription is only performed client-side; therefore, this function should not be relied upon for perfect accuracy. For example, this function may return an incorrect result if the MQTT server crashes and drops subscriptions without informing the client.
Note that an MQTT connection's subscriptions might change between the time this function checks the subscription list and its caller tests the return value. This function certainly should not be used concurrently with any pending SUBSCRIBE or UNSUBSCRIBE operations.
One suitable use of this function is to check which subscriptions were rejected if IotMqtt_SubscribeAsync returns IOT_MQTT_SERVER_REFUSED; that return code only means that at least one subscription was rejected.
[in] | mqttConnection | The MQTT connection to check. |
[in] | pTopicFilter | The topic filter to check. |
[in] | topicFilterLength | Length of pTopicFilter . |
[out] | pCurrentSubscription | If a subscription is found, its details are copied here. This output parameter is only valid if this function returns true (NULL to disable). |
true
if a subscription was found; false
otherwise.pCurrentSubscription->qos
will always be set to IOT_MQTT_QOS_0.