Crate paho_mqtt_sys
source ·Structs
MQTTAsync_sslProperties defines the settings to establish an SSL/TLS connection using the
OpenSSL library. It covers the following scenarios:
MQTTAsync_connectOptions defines several settings that control the way the
client connects to an MQTT server. Default values are set in
MQTTAsync_connectOptions_initializer.
Optional binary password. Only checked and used if the password option is NULL
The data returned on completion of an unsuccessful API call in the response callback onFailure.
Initialization options
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()).
The data returned on completion of a successful API call in the response callback onSuccess.
For publish, the message being sent to the server.
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.
The LWT payload in binary form. This is only checked and used if the message option is NULL
@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.
Constants
Statics
Functions
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
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.
::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 sets a pointer to an array of tokens for
messages that are currently in-flight (pending completion).
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 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 sets the level of trace information which will be
returned in the trace callback.
@param level the trace level required
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.
Waits for a request corresponding to a token to complete.
feof⚠
getc⚠
getw⚠
putc⚠
puts⚠
putw⚠
Type Definitions
A handle representing an MQTT client. A valid client handle is available
following a successful call to MQTTAsync_create().
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. 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 Any 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.
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.
@brief Clears the persistence store, so that it no longer contains any
persisted data.
@brief Close the persistent store referred to by the handle.
@brief Returns whether any data has been persisted using the specified key.
@brief Retrieve the specified data from the persistent store.
@brief Returns the keys in this persistent data store.
@brief Initialize the persistent store.
@brief Put the specified data into the persistent store.
@brief Remove the data for the specified key from the store.
Unions
A union of the different values that can be returned for subscribe, unsubscribe and publish.