MQTTAsync_connectOptions defines several settings that control the way the
client connects to an MQTT server. Default values are set in
MQTTAsync_connectOptions_initializer.
A structure representing the payload and attributes of an MQTT message. The
message topic is not part of this structure (see MQTTAsync_publishMessage(),
MQTTAsync_publish(), MQTTAsync_receive(), MQTTAsync_freeMessage()
and MQTTAsync_messageArrived()).
MQTTAsync_willOptions defines the MQTT “Last Will and Testament” (LWT) settings for
the client. In the event that a client unexpectedly loses its connection to
the server, the server publishes the LWT message to the LWT topic on
behalf of the client. This allows other clients (subscribed to the LWT topic)
to be made aware that the client has disconnected. To enable the LWT
function for a specific client, a valid pointer to an MQTTAsync_willOptions
structure is passed in the MQTTAsync_connectOptions structure used in the
MQTTAsync_connect() call that connects the client to the server. The pointer
to MQTTAsync_willOptions can be set to NULL if the LWT function is not
required.
A structure representing the payload and attributes of an MQTT message. The
message topic is not part of this structure (see MQTTClient_publishMessage(),
MQTTClient_publish(), MQTTClient_receive(), MQTTClient_freeMessage()
and MQTTClient_messageArrived()).
MQTTClient_libraryInfo is used to store details relating to the currently used
library such as the version in use, the time it was built and relevant openSSL
options.
There is one static instance of this struct in MQTTClient.c
@brief A structure containing the function pointers to a persistence
implementation and the context or state that will be shared across all
the persistence functions.
MQTTClient_willOptions defines the MQTT “Last Will and Testament” (LWT) settings for
the client. In the event that a client unexpectedly loses its connection to
the server, the server publishes the LWT message to the LWT topic on
behalf of the client. This allows other clients (subscribed to the LWT topic)
to be made aware that the client has disconnected. To enable the LWT
function for a specific client, a valid pointer to an MQTTClient_willOptions
structure is passed in the MQTTClient_connectOptions structure used in the
MQTTClient_connect() call that connects the client to the server. The pointer
to MQTTClient_willOptions can be set to NULL if the LWT function is not
required.
This function attempts to connect a previously-created client (see
MQTTAsync_create()) to an MQTT server using the specified options. If you
want to enable asynchronous message and status notifications, you must call
MQTTAsync_setCallbacks() prior to MQTTAsync_connect().
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param options A pointer to a valid MQTTAsync_connectOptions
structure.
@return ::MQTTASYNC_SUCCESS if the client connect request was accepted.
If the client was unable to connect to the server, an error code is
returned via the onFailure callback, if set.
Error codes greater than 0 are returned by the MQTT protocol:
1: Connection refused: Unacceptable protocol version 2: Connection refused: Identifier rejected 3: Connection refused: Server unavailable 4: Connection refused: Bad user name or password 5: Connection refused: Not authorized 6-255: Reserved for future use
This function creates an MQTT client ready for connection to the
specified server and using the specified persistent storage (see
MQTTAsync_persistence). See also MQTTAsync_destroy().
@param handle A pointer to an ::MQTTAsync handle. The handle is
populated with a valid client reference following a successful return from
this function.
@param serverURI A null-terminated string specifying the server to
which the client will connect. It takes the form protocol://host:port.
protocol must be tcp or ssl. For host, you can
specify either an IP address or a host name. For instance, to connect to
a server running on the local machines with the default MQTT port, specify
tcp://localhost:1883.
@param clientId The client identifier passed to the server when the
client connects to it. It is a null-terminated UTF-8 encoded string.
@param persistence_type The type of persistence to be used by the client:
::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or
system on which the client is running fails or is switched off, the current
state of any in-flight messages is lost and some messages may not be
delivered even at QoS1 and QoS2.
::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based)
persistence mechanism. Status about in-flight messages is held in persistent
storage and provides some protection against message loss in the case of
unexpected failure.
::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence
implementation. Using this type of persistence gives control of the
persistence mechanism to the application. The application has to implement
the MQTTClient_persistence interface.
@param persistence_context If the application uses
::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should
be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it
should be set to the location of the persistence directory (if set
to NULL, the persistence directory used is the working directory).
Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this
argument to point to a valid MQTTClient_persistence structure.
@return ::MQTTASYNC_SUCCESS if the client is successfully created, otherwise
an error code is returned.
This function frees the memory allocated to an MQTT client (see
MQTTAsync_create()). It should be called when the client is no longer
required.
@param handle A pointer to the handle referring to the ::MQTTAsync
structure to be freed.
This function attempts to disconnect the client from the MQTT
server. In order to allow the client time to complete handling of messages
that are in-flight when this function is called, a timeout period is
specified. When the timeout period has expired, the client disconnects even
if there are still outstanding message acknowledgements.
The next time the client connects to the same server, any QoS 1 or 2
messages which have not completed will be retried depending on the
cleansession settings for both the previous and the new connection (see
MQTTAsync_connectOptions.cleansession and MQTTAsync_connect()).
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param options The client delays disconnection for up to this time (in
milliseconds) in order to allow in-flight message transfers to complete.
@return ::MQTTASYNC_SUCCESS if the client successfully disconnects from
the server. An error code is returned if the client was unable to disconnect
from the server
This function frees memory allocated by the MQTT C client library, especially the
topic name. This is needed on Windows when the client libary and application
program have been compiled with different versions of the C compiler. It is
thus good policy to always use this function when freeing any MQTT C client-
allocated memory.
@param ptr The pointer to the client library storage to be freed.
This function frees memory allocated to an MQTT message, including the
additional memory allocated to the message payload. The client application
calls this function when the message has been fully processed. Important
note: This function does not free the memory allocated to a message
topic string. It is the responsibility of the client application to free
this memory using the MQTTAsync_free() library function.
@param msg The address of a pointer to the ::MQTTAsync_message structure
to be freed.
This function returns version information about the library.
no trace information will be returned. The default trace level is
MQTTASYNC_TRACE_MINIMUM
@return an array of strings describing the library. The last entry is a NULL pointer.
Global init of mqtt library. Call once on program start to set global behaviour.
handle_openssl_init - if mqtt library should handle openssl init (1) or rely on the caller to init it before using mqtt (0)
This function allows the client application to test whether or not a
client is currently connected to the MQTT server.
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@return Boolean true if the client is connected, otherwise false.
Reconnects a client with the previously used connect options. Connect
must have previously been called for this to work.
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
::MQTTASYNC_FAILURE if an error occurred.
This function attempts to publish a message to a given topic (see also
::MQTTAsync_sendMessage()). An ::MQTTAsync_token is issued when
this function returns successfully. If the client application needs to
test for successful delivery of messages, a callback should be set
(see ::MQTTAsync_onSuccess() and ::MQTTAsync_deliveryComplete()).
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param destinationName The topic associated with this message.
@param payloadlen The length of the payload in bytes.
@param payload A pointer to the byte array payload of the message.
@param qos The @ref qos of the message.
@param retained The retained flag for the message.
@param response A pointer to an ::MQTTAsync_responseOptions structure. Used to set callback functions.
This is optional and can be set to NULL.
@return ::MQTTASYNC_SUCCESS if the message is accepted for publication.
An error code is returned if there was a problem accepting the message.
This function attempts to publish a message to a given topic (see also
MQTTAsync_publish()). An ::MQTTAsync_token is issued when
this function returns successfully. If the client application needs to
test for successful delivery of messages, a callback should be set
(see ::MQTTAsync_onSuccess() and ::MQTTAsync_deliveryComplete()).
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param destinationName The topic associated with this message.
@param msg A pointer to a valid MQTTAsync_message structure containing
the payload and attributes of the message to be published.
@param response A pointer to an ::MQTTAsync_responseOptions structure. Used to set callback functions.
@return ::MQTTASYNC_SUCCESS if the message is accepted for publication.
An error code is returned if there was a problem accepting the message.
This function sets the global callback functions for a specific client.
If your client application doesn’t use a particular callback, set the
relevant parameter to NULL. Any necessary message acknowledgements and
status communications are handled in the background without any intervention
from the client application. If you do not set a messageArrived callback
function, you will not be notified of the receipt of any messages as a
result of a subscription.
Sets the MQTTAsync_connected() callback function for a client.
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param context A pointer to any application-specific context. The
the context pointer is passed to each of the callback functions to
provide access to the context information in the callback.
@param co A pointer to an MQTTAsync_connected() callback
function. NULL removes the callback setting.
@return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
::MQTTASYNC_FAILURE if an error occurred.
This function sets the callback function for a connection lost event for
a specific client. Any necessary message acknowledgements and status
communications are handled in the background without any intervention
from the client application.
This function sets the callback function for a delivery complete event
for a specific client. Any necessary message acknowledgements and status
communications are handled in the background without any intervention
from the client application.
Sets the MQTTAsync_disconnected() callback function for a client.
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param context A pointer to any application-specific context. The
the context pointer is passed to each of the callback functions to
provide access to the context information in the callback.
@param co A pointer to an MQTTAsync_connected() callback
function. NULL removes the callback setting.
@return ::MQTTASYNC_SUCCESS if the callbacks were correctly set,
::MQTTASYNC_FAILURE if an error occurred.
This function sets the callback function for a message arrived event for
a specific client. Any necessary message acknowledgements and status
communications are handled in the background without any intervention
from the client application. If you do not set a messageArrived callback
function, you will not be notified of the receipt of any messages as a
result of a subscription.
This function sets the trace callback if needed. If set to NULL,
no trace information will be returned. The default trace level is
MQTTASYNC_TRACE_MINIMUM.
@param callback a pointer to the function which will handle the trace information
Returns a pointer to a string representation of the error code, or NULL.
Do not free after use. Returns NULL if the error code is unknown.
@param code the MQTTASYNC_ return code.
@return a static string representation of the error code.
This function attempts to subscribe a client to a single topic, which may
contain wildcards (see @ref wildcard). This call also specifies the
@ref qos requested for the subscription
(see also MQTTAsync_subscribeMany()).
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param topic The subscription topic, which may include wildcards.
@param qos The requested quality of service for the subscription.
@param response A pointer to a response options structure. Used to set callback functions.
@return ::MQTTASYNC_SUCCESS if the subscription request is successful.
An error code is returned if there was a problem registering the
subscription.
This function attempts to subscribe a client to a list of topics, which may
contain wildcards (see @ref wildcard). This call also specifies the
@ref qos requested for each topic (see also MQTTAsync_subscribe()).
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param count The number of topics for which the client is requesting
subscriptions.
@param topic An array (of length count) of pointers to
topics, each of which may include wildcards.
@param qos An array (of length count) of @ref qos
values. qos[n] is the requested QoS for topic[n].
@param response A pointer to a response options structure. Used to set callback functions.
@return ::MQTTASYNC_SUCCESS if the subscription request is successful.
An error code is returned if there was a problem registering the
subscriptions.
This function attempts to remove an existing subscription made by the
specified client.
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param topic The topic for the subscription to be removed, which may
include wildcards (see @ref wildcard).
@param response A pointer to a response options structure. Used to set callback functions.
@return ::MQTTASYNC_SUCCESS if the subscription is removed.
An error code is returned if there was a problem removing the
subscription.
This function attempts to remove existing subscriptions to a list of topics
made by the specified client.
@param handle A valid client handle from a successful call to
MQTTAsync_create().
@param count The number subscriptions to be removed.
@param topic An array (of length count) of pointers to the topics of
the subscriptions to be removed, each of which may include wildcards.
@param response A pointer to a response options structure. Used to set callback functions.
@return ::MQTTASYNC_SUCCESS if the subscriptions are removed.
An error code is returned if there was a problem removing the subscriptions.
This function attempts to connect a previously-created client (see
MQTTClient_create()) to an MQTT server using the specified options. If you
want to enable asynchronous message and status notifications, you must call
MQTTClient_setCallbacks() prior to MQTTClient_connect().
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param options A pointer to a valid MQTTClient_connectOptions
structure.
@return ::MQTTCLIENT_SUCCESS if the client successfully connects to the
server. An error code is returned if the client was unable to connect to
the server.
Error codes greater than 0 are returned by the MQTT protocol:
1: Connection refused: Unacceptable protocol version 2: Connection refused: Identifier rejected 3: Connection refused: Server unavailable 4: Connection refused: Bad user name or password 5: Connection refused: Not authorized 6-255: Reserved for future use
This function creates an MQTT client ready for connection to the
specified server and using the specified persistent storage (see
MQTTClient_persistence). See also MQTTClient_destroy().
@param handle A pointer to an ::MQTTClient handle. The handle is
populated with a valid client reference following a successful return from
this function.
@param serverURI A null-terminated string specifying the server to
which the client will connect. It takes the form protocol://host:port.
Currently, protocol must be tcp or ssl.
For host, you can
specify either an IP address or a host name. For instance, to connect to
a server running on the local machines with the default MQTT port, specify
tcp://localhost:1883.
@param clientId The client identifier passed to the server when the
client connects to it. It is a null-terminated UTF-8 encoded string.
@param persistence_type The type of persistence to be used by the client:
::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or
system on which the client is running fails or is switched off, the current
state of any in-flight messages is lost and some messages may not be
delivered even at QoS1 and QoS2.
::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based)
persistence mechanism. Status about in-flight messages is held in persistent
storage and provides some protection against message loss in the case of
unexpected failure.
::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence
implementation. Using this type of persistence gives control of the
persistence mechanism to the application. The application has to implement
the MQTTClient_persistence interface.
@param persistence_context If the application uses
::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should
be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it
should be set to the location of the persistence directory (if set
to NULL, the persistence directory used is the working directory).
Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this
argument to point to a valid MQTTClient_persistence structure.
@return ::MQTTCLIENT_SUCCESS if the client is successfully created, otherwise
an error code is returned.
A version of :MQTTClient_create() with additional options.
This function creates an MQTT client ready for connection to the
specified server and using the specified persistent storage (see
MQTTClient_persistence). See also MQTTClient_destroy().
@param handle A pointer to an ::MQTTClient handle. The handle is
populated with a valid client reference following a successful return from
this function.
@param serverURI A null-terminated string specifying the server to
which the client will connect. It takes the form protocol://host:port.
Currently, protocol must be tcp or ssl.
For host, you can
specify either an IP address or a host name. For instance, to connect to
a server running on the local machines with the default MQTT port, specify
tcp://localhost:1883.
@param clientId The client identifier passed to the server when the
client connects to it. It is a null-terminated UTF-8 encoded string.
@param persistence_type The type of persistence to be used by the client:
::MQTTCLIENT_PERSISTENCE_NONE: Use in-memory persistence. If the device or
system on which the client is running fails or is switched off, the current
state of any in-flight messages is lost and some messages may not be
delivered even at QoS1 and QoS2.
::MQTTCLIENT_PERSISTENCE_DEFAULT: Use the default (file system-based)
persistence mechanism. Status about in-flight messages is held in persistent
storage and provides some protection against message loss in the case of
unexpected failure.
::MQTTCLIENT_PERSISTENCE_USER: Use an application-specific persistence
implementation. Using this type of persistence gives control of the
persistence mechanism to the application. The application has to implement
the MQTTClient_persistence interface.
@param persistence_context If the application uses
::MQTTCLIENT_PERSISTENCE_NONE persistence, this argument is unused and should
be set to NULL. For ::MQTTCLIENT_PERSISTENCE_DEFAULT persistence, it
should be set to the location of the persistence directory (if set
to NULL, the persistence directory used is the working directory).
Applications that use ::MQTTCLIENT_PERSISTENCE_USER persistence set this
argument to point to a valid MQTTClient_persistence structure.
@param options additional options for the create.
@return ::MQTTCLIENT_SUCCESS if the client is successfully created, otherwise
an error code is returned.
This function frees the memory allocated to an MQTT client (see
MQTTClient_create()). It should be called when the client is no longer
required.
@param handle A pointer to the handle referring to the ::MQTTClient
structure to be freed.
This function attempts to disconnect the client from the MQTT
server. In order to allow the client time to complete handling of messages
that are in-flight when this function is called, a timeout period is
specified. When the timeout period has expired, the client disconnects even
if there are still outstanding message acknowledgements.
The next time the client connects to the same server, any QoS 1 or 2
messages which have not completed will be retried depending on the
cleansession settings for both the previous and the new connection (see
MQTTClient_connectOptions.cleansession and MQTTClient_connect()).
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param timeout The client delays disconnection for up to this time (in
milliseconds) in order to allow in-flight message transfers to complete.
@return ::MQTTCLIENT_SUCCESS if the client successfully disconnects from
the server. An error code is returned if the client was unable to disconnect
from the server
This function frees memory allocated by the MQTT C client library, especially the
topic name. This is needed on Windows when the client libary and application
program have been compiled with different versions of the C compiler. It is
thus good policy to always use this function when freeing any MQTT C client-
allocated memory.
@param ptr The pointer to the client library storage to be freed.
This function frees memory allocated to an MQTT message, including the
additional memory allocated to the message payload. The client application
calls this function when the message has been fully processed. Important
note: This function does not free the memory allocated to a message
topic string. It is the responsibility of the client application to free
this memory using the MQTTClient_free() library function.
@param msg The address of a pointer to the ::MQTTClient_message structure
to be freed.
This function returns version information about the library.
no trace information will be returned.
@return an array of strings describing the library. The last entry is a NULL pointer.
Global init of mqtt library. Call once on program start to set global behaviour.
do_openssl_init - if mqtt library should initialize OpenSSL (1) or rely on the caller to do it before using the library (0)
This function allows the client application to test whether or not a
client is currently connected to the MQTT server.
@param handle A valid client handle from a successful call to
MQTTClient_create().
@return Boolean true if the client is connected, otherwise false.
This function attempts to publish a message to a given topic (see also
MQTTClient_publishMessage()). An ::MQTTClient_deliveryToken is issued when
this function returns successfully. If the client application needs to
test for succesful delivery of QoS1 and QoS2 messages, this can be done
either asynchronously or synchronously (see @ref async,
::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param topicName The topic associated with this message.
@param payloadlen The length of the payload in bytes.
@param payload A pointer to the byte array payload of the message.
@param qos The @ref qos of the message.
@param retained The retained flag for the message.
@param dt A pointer to an ::MQTTClient_deliveryToken. This is populated
with a token representing the message when the function returns
successfully. If your application does not use delivery tokens, set this
argument to NULL.
@return ::MQTTCLIENT_SUCCESS if the message is accepted for publication.
An error code is returned if there was a problem accepting the message.
This function attempts to publish a message to a given topic (see also
MQTTClient_publish()). An ::MQTTClient_deliveryToken is issued when
this function returns successfully. If the client application needs to
test for succesful delivery of QoS1 and QoS2 messages, this can be done
either asynchronously or synchronously (see @ref async,
::MQTTClient_waitForCompletion and MQTTClient_deliveryComplete()).
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param topicName The topic associated with this message.
@param msg A pointer to a valid MQTTClient_message structure containing
the payload and attributes of the message to be published.
@param dt A pointer to an ::MQTTClient_deliveryToken. This is populated
with a token representing the message when the function returns
successfully. If your application does not use delivery tokens, set this
argument to NULL.
@return ::MQTTCLIENT_SUCCESS if the message is accepted for publication.
An error code is returned if there was a problem accepting the message.
This function performs a synchronous receive of incoming messages. It should
be used only when the client application has not set callback methods to
support asynchronous receipt of messages (see @ref async and
MQTTClient_setCallbacks()). Using this function allows a single-threaded
client subscriber application to be written. When called, this function
blocks until the next message arrives or the specified timeout expires
(see also MQTTClient_yield()).
This function sets the callback functions for a specific client.
If your client application doesn’t use a particular callback, set the
relevant parameter to NULL. Calling MQTTClient_setCallbacks() puts the
client into multi-threaded mode. Any necessary message acknowledgements and
status communications are handled in the background without any intervention
from the client application. See @ref async for more information.
Sets the MQTTClient_disconnected() callback function for a client. This will be called
if a disconnect packet is received from the server. Only valid for MQTT V5 and above.
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param context A pointer to any application-specific context. The
the context pointer is passed to each of the callback functions to
provide access to the context information in the callback.
@param co A pointer to an MQTTClient_disconnected() callback
function. NULL removes the callback setting.
@return ::MQTTCLIENT_SUCCESS if the callbacks were correctly set,
::MQTTCLIENT_FAILURE if an error occurred.
This function sets the trace callback if needed. If set to NULL,
no trace information will be returned. The default trace level is
MQTTASYNC_TRACE_MINIMUM.
@param callback a pointer to the function which will handle the trace information
This function attempts to subscribe a client to a single topic, which may
contain wildcards (see @ref wildcard). This call also specifies the
@ref qos requested for the subscription
(see also MQTTClient_subscribeMany()).
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param topic The subscription topic, which may include wildcards.
@param qos The requested quality of service for the subscription.
@return ::MQTTCLIENT_SUCCESS if the subscription request is successful.
An error code is returned if there was a problem registering the
subscription.
This function attempts to subscribe a client to a list of topics, which may
contain wildcards (see @ref wildcard). This call also specifies the
@ref qos requested for each topic (see also MQTTClient_subscribe()).
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param count The number of topics for which the client is requesting
subscriptions.
@param topic An array (of length count) of pointers to
topics, each of which may include wildcards.
@param qos An array (of length count) of @ref qos
values. qos[n] is the requested QoS for topic[n].
@return ::MQTTCLIENT_SUCCESS if the subscription request is successful.
An error code is returned if there was a problem registering the
subscriptions.
This function attempts to remove an existing subscription made by the
specified client.
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param topic The topic for the subscription to be removed, which may
include wildcards (see @ref wildcard).
@return ::MQTTCLIENT_SUCCESS if the subscription is removed.
An error code is returned if there was a problem removing the
subscription.
This function attempts to remove existing subscriptions to a list of topics
made by the specified client.
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param count The number subscriptions to be removed.
@param topic An array (of length count) of pointers to the topics of
the subscriptions to be removed, each of which may include wildcards.
@return ::MQTTCLIENT_SUCCESS if the subscriptions are removed.
An error code is returned if there was a problem removing the subscriptions.
This function is called by the client application to synchronize execution
of the main thread with completed publication of a message. When called,
MQTTClient_waitForCompletion() blocks execution until the message has been
successful delivered or the specified timeout has expired. See @ref async.
@param handle A valid client handle from a successful call to
MQTTClient_create().
@param dt The ::MQTTClient_deliveryToken that represents the message being
tested for successful delivery. Delivery tokens are issued by the
publishing functions MQTTClient_publish() and MQTTClient_publishMessage().
@param timeout The maximum time to wait in milliseconds.
@return ::MQTTCLIENT_SUCCESS if the message was successfully delivered.
An error code is returned if the timeout expires or there was a problem
checking the token.
When implementing a single-threaded client, call this function periodically
to allow processing of message retries and to send MQTT keepalive pings.
If the application is calling MQTTClient_receive() regularly, then it is
not necessary to call this function.
Add a property pointer to the property array. There is no memory allocation.
@param props The property list to add the property to.
@param prop The property to add to the list.
@return 0 on success, -1 on failure.
Copy the contents of a property list, allocating additional memory if needed.
@param props pointer to the property list.
@return the duplicated property list.
Returns the integer value of a specific property. The property given must be a numeric type.
@param props pointer to the property list.
@param propid the property id to check for.
@return the integer value of the property. -9999999 on failure.
Returns the integer value of a specific property when it’s not the only instance.
The property given must be a numeric type.
@param props pointer to the property list.
@param propid the property id to check for.
@param index the instance number, starting at 0.
@return the integer value of the property. -9999999 on failure.
Returns a pointer to the property structure for a specific property.
@param props pointer to the property list.
@param propid the property id to check for.
@return the pointer to the property structure if found. NULL if not found.
Returns a pointer to the property structure for a specific property when it’s not the only instance.
@param props pointer to the property list.
@param propid the property id to check for.
@param index the instance number, starting at 0.
@return the pointer to the property structure if found. NULL if not found.
Checks if property list contains a specific property.
@param props pointer to the property list.
@param propid the property id to check for.
@return 1 if found, 0 if not.
Returns the length of the properties structure when serialized ready for network transmission.
@param props an MQTT V5 property structure.
@return the length in bytes of the properties when serialized.
Returns the number of instances of a property id. Most properties can exist only once.
User properties and subscription ids can exist more than once.
@param props pointer to the property list.
@param propid the property id to check for.
@return the number of times found. Can be 0.
Reads a property list from a character buffer into an array.
@param properties pointer to the property list to be filled. Should be initalized but empty.
@param pptr pointer to the character buffer.
@param enddata pointer to the end of the character buffer so we don’t read beyond.
@return 1 if the properties were read successfully.
Serialize the given property list to a character buffer, e.g. for writing to the network.
@param pptr pointer to the buffer - move the pointer as we add data
@param properties pointer to the property list, can be NULL
@return whether the write succeeded or not: number of bytes written, or < 0 on failure.
Returns a printable string description of an MQTT V5 property code.
@param value an MQTT V5 property code.
@return the printable string description of the input property code.
NULL if the code was not found.
Returns the MQTT V5 type code of an MQTT V5 property.
@param value an MQTT V5 property code.
@return the MQTT V5 type code of the input property. -1 if the code was not found.
Returns a printable string description of an MQTT V5 reason code.
@param value an MQTT V5 reason code.
@return the printable string description of the input reason code.
NULL if the code was not found.
This is a callback function, which will be called when the client
library successfully connects. This is superfluous when the connection
is made in response to a MQTTAsync_connect call, because the onSuccess
callback can be used. It is intended for use when automatic reconnect
is enabled, so that when a reconnection attempt succeeds in the background,
the application is notified and can take any required actions.
@param context A pointer to the context value originally passed to
MQTTAsync_setCallbacks(), which contains any application-specific context.
@param cause The reason for the disconnection.
Currently, cause is always set to NULL.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
notification of the loss of connection to the server. The function is
registered with the client library by passing it as an argument to
MQTTAsync_setCallbacks(). It is called by the client library if the client
loses its connection to the server. The client application must take
appropriate action, such as trying to reconnect or reporting the problem.
This function is executed on a separate thread to the one on which the
client application is running.
@param context A pointer to the context value originally passed to
MQTTAsync_setCallbacks(), which contains any application-specific context.
@param cause The reason for the disconnection.
Currently, cause is always set to NULL.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
notification of delivery of messages to the server. The function is
registered with the client library by passing it as an argument to MQTTAsync_setCallbacks().
It is called by the client library after the client application has
published a message to the server. It indicates that the necessary
handshaking and acknowledgements for the requested quality of service (see
MQTTAsync_message.qos) have been completed. This function is executed on a
separate thread to the one on which the client application is running.
@param context A pointer to the context value originally passed to
MQTTAsync_setCallbacks(), which contains any application-specific context.
@param token The ::MQTTAsync_token associated with
the published message. Applications can check that all messages have been
correctly published by matching the tokens returned from calls to
MQTTAsync_send() and MQTTAsync_sendMessage() with the tokens passed
to this callback.
This is a callback function, which will be called when the client
library receives a disconnect packet.
@param context A pointer to the context value originally passed to
MQTTAsync_setCallbacks(), which contains any application-specific context.
@param properties the properties in the disconnect packet.
@param properties the reason code from the disconnect packet
Currently, cause is always set to NULL.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
receipt of messages. The function is registered with the client library by
passing it as an argument to MQTTAsync_setCallbacks(). It is
called by the client library when a new message that matches a client
subscription has been received from the server. This function is executed on
a separate thread to the one on which the client application is running.
@param context A pointer to the context value originally passed to
MQTTAsync_setCallbacks(), which contains any application-specific context.
@param topicName The topic associated with the received message.
@param topicLen The length of the topic if there are one
more NULL characters embedded in topicName, otherwise topicLen
is 0. If topicLen is 0, the value returned by strlen(topicName)
can be trusted. If topicLen is greater than 0, the full topic name
can be retrieved by accessing topicName as a byte array of length
topicLen.
@param message The MQTTAsync_message structure for the received message.
This structure contains the message payload and attributes.
@return This function must return a boolean value indicating whether or not
the message has been safely received by the client application. Returning
true indicates that the message has been successfully handled.
Returning false indicates that there was a problem. In this
case, the client library will reinvoke MQTTAsync_messageArrived() to
attempt to deliver the message to the application again.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
notification of the unsuccessful completion of an API call. The function is
registered with the client library by passing it as an argument in
::MQTTAsync_responseOptions.
@param context A pointer to the context value originally passed to
::MQTTAsync_responseOptions, which contains any application-specific context.
@param response Failure data associated with the API completion.
This is a callback function, the MQTT V5 version of ::MQTTAsync_onFailure.
The application must provide an implementation of this function to enable asynchronous
notification of the unsuccessful completion of an API call. The function is
registered with the client library by passing it as an argument in
::MQTTAsync_responseOptions.
@param context A pointer to the context value originally passed to
::MQTTAsync_responseOptions, which contains any application-specific context.
@param response Failure data associated with the API completion.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
notification of the successful completion of an API call. The function is
registered with the client library by passing it as an argument in
::MQTTAsync_responseOptions.
@param context A pointer to the context value originally passed to
::MQTTAsync_responseOptions, which contains any application-specific context.
@param response Any success data associated with the API completion.
This is a callback function, the MQTT V5 version of ::MQTTAsync_onSuccess.
The client application
must provide an implementation of this function to enable asynchronous
notification of the successful completion of an API call. The function is
registered with the client library by passing it as an argument in
::MQTTAsync_responseOptions.
@param context A pointer to the context value originally passed to
::MQTTAsync_responseOptions, which contains any application-specific context.
@param response Any success data associated with the API completion.
A value representing an MQTT message. A token is returned to the
client application when a message is published. The token can then be used to
check that the message was successfully delivered to its destination (see
MQTTAsync_publish(),
MQTTAsync_publishMessage(),
MQTTAsync_deliveryComplete(), and
MQTTAsync_getPendingTokens()).
This is a callback function prototype which must be implemented if you want
to receive trace information.
@param level the trace level of the message returned
@param meesage the trace message. This is a pointer to a static buffer which
will be overwritten on each call. You must copy the data if you want to keep
it for later.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
notification of the loss of connection to the server. The function is
registered with the client library by passing it as an argument to
MQTTClient_setCallbacks(). It is called by the client library if the client
loses its connection to the server. The client application must take
appropriate action, such as trying to reconnect or reporting the problem.
This function is executed on a separate thread to the one on which the
client application is running.
@param context A pointer to the context value originally passed to
MQTTClient_setCallbacks(), which contains any application-specific context.
@param cause The reason for the disconnection.
Currently, cause is always set to NULL.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
notification of delivery of messages. The function is registered with the
client library by passing it as an argument to MQTTClient_setCallbacks().
It is called by the client library after the client application has
published a message to the server. It indicates that the necessary
handshaking and acknowledgements for the requested quality of service (see
MQTTClient_message.qos) have been completed. This function is executed on a
separate thread to the one on which the client application is running.
Note:MQTTClient_deliveryComplete() is not called when messages are
published at QoS0.
@param context A pointer to the context value originally passed to
MQTTClient_setCallbacks(), which contains any application-specific context.
@param dt The ::MQTTClient_deliveryToken associated with
the published message. Applications can check that all messages have been
correctly published by matching the delivery tokens returned from calls to
MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed
to this callback.
A value representing an MQTT message. A delivery token is returned to the
client application when a message is published. The token can then be used to
check that the message was successfully delivered to its destination (see
MQTTClient_publish(),
MQTTClient_publishMessage(),
MQTTClient_deliveryComplete(),
MQTTClient_waitForCompletion() and
MQTTClient_getPendingDeliveryTokens()).
This is a callback function, which will be called when the a disconnect
packet is received from the server. This applies to MQTT V5 and above only.
@param context A pointer to the context value originally passed to
::MQTTAsync_setDisconnected(), which contains any application-specific context.
@param properties The MQTT V5 properties received with the disconnect, if any.
@param reasonCode The MQTT V5 reason code received with the disconnect.
Currently, cause is always set to NULL.
This is a callback function. The client application
must provide an implementation of this function to enable asynchronous
receipt of messages. The function is registered with the client library by
passing it as an argument to MQTTClient_setCallbacks(). It is
called by the client library when a new message that matches a client
subscription has been received from the server. This function is executed on
a separate thread to the one on which the client application is running.
@param context A pointer to the context value originally passed to
MQTTClient_setCallbacks(), which contains any application-specific context.
@param topicName The topic associated with the received message.
@param topicLen The length of the topic if there are one
more NULL characters embedded in topicName, otherwise topicLen
is 0. If topicLen is 0, the value returned by strlen(topicName)
can be trusted. If topicLen is greater than 0, the full topic name
can be retrieved by accessing topicName as a byte array of length
topicLen.
@param message The MQTTClient_message structure for the received message.
This structure contains the message payload and attributes.
@return This function must return a boolean value indicating whether or not
the message has been safely received by the client application. Returning
true indicates that the message has been successfully handled.
Returning false indicates that there was a problem. In this
case, the client library will reinvoke MQTTClient_messageArrived() to
attempt to deliver the message to the application again.
This is a callback function, the MQTT V5 version of MQTTClient_deliveryComplete().
The client application
must provide an implementation of this function to enable asynchronous
notification of the completed delivery of messages.
It is called by the client library after the client application has
published a message to the server. It indicates that the necessary
handshaking and acknowledgements for the requested quality of service (see
MQTTClient_message.qos) have been completed. This function is executed on a
separate thread to the one on which the client application is running.
Note: It is not called when messages are published at QoS0.
@param context A pointer to the context value originally passed to
MQTTClient_setCallbacks(), which contains any application-specific context.
@param dt The ::MQTTClient_deliveryToken associated with
the published message. Applications can check that all messages have been
correctly published by matching the delivery tokens returned from calls to
MQTTClient_publish() and MQTTClient_publishMessage() with the tokens passed
to this callback.
@param packet_type the last received packet type for this completion. For QoS 1
always PUBACK. For QoS 2 could be PUBREC or PUBCOMP.
@param properties the MQTT V5 properties returned with the last packet from the server
@param reasonCode the reason code returned from the server
This is a callback function prototype which must be implemented if you want
to receive trace information.
@param level the trace level of the message returned
@param meesage the trace message. This is a pointer to a static buffer which
will be overwritten on each call. You must copy the data if you want to keep
it for later.