天嵌二次封装库使用手册
V2.1.2
|
#include "MQTTExportDeclarations.h"
#include "MQTTProperties.h"
#include "MQTTReasonCodes.h"
#include "MQTTSubscribeOpts.h"
#include "MQTTClientPersistence.h"
类 | |
struct | MQTTAsync_init_options |
struct | MQTTAsync_message |
struct | MQTTAsync_connectData |
struct | MQTTAsync_failureData |
struct | MQTTAsync_failureData5 |
struct | MQTTAsync_successData |
struct | MQTTAsync_successData5 |
struct | MQTTAsync_responseOptions |
struct | MQTTAsync_createOptions |
struct | MQTTAsync_willOptions |
struct | MQTTAsync_SSLOptions |
struct | MQTTAsync_nameValue |
struct | MQTTAsync_connectOptions |
struct | MQTTAsync_disconnectOptions |
类型定义 | |
typedef void * | MQTTAsync |
typedef int | MQTTAsync_token |
typedef int | MQTTAsync_messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message) |
typedef void | MQTTAsync_deliveryComplete(void *context, MQTTAsync_token token) |
typedef void | MQTTAsync_connectionLost(void *context, char *cause) |
typedef void | MQTTAsync_connected(void *context, char *cause) |
typedef void | MQTTAsync_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode) |
typedef int | MQTTAsync_updateConnectOptions(void *context, MQTTAsync_connectData *data) |
typedef void | MQTTAsync_onSuccess(void *context, MQTTAsync_successData *response) |
typedef void | MQTTAsync_onSuccess5(void *context, MQTTAsync_successData5 *response) |
typedef void | MQTTAsync_onFailure(void *context, MQTTAsync_failureData *response) |
typedef void | MQTTAsync_onFailure5(void *context, MQTTAsync_failureData5 *response) |
typedef struct MQTTAsync_responseOptions | MQTTAsync_responseOptions |
typedef struct MQTTAsync_responseOptions | MQTTAsync_callOptions |
typedef void | MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char *message) |
#define MQTT_BAD_SUBSCRIBE 0x80 |
Bad return code from subscribe, as defined in the 3.1.1 specification
在文件 MQTTAsync.h 第 215 行定义.
#define MQTT_SSL_VERSION_DEFAULT 0 |
在文件 MQTTAsync.h 第 1030 行定义.
#define MQTT_SSL_VERSION_TLS_1_0 1 |
在文件 MQTTAsync.h 第 1031 行定义.
#define MQTT_SSL_VERSION_TLS_1_1 2 |
在文件 MQTTAsync.h 第 1032 行定义.
#define MQTT_SSL_VERSION_TLS_1_2 3 |
在文件 MQTTAsync.h 第 1033 行定义.
#define MQTTASYNC_0_LEN_WILL_TOPIC -17 |
Return code: 0 length will topic
在文件 MQTTAsync.h 第 189 行定义.
#define MQTTASYNC_BAD_MQTT_OPTION -15 |
Return code: don't use options for another version of MQTT
在文件 MQTTAsync.h 第 181 行定义.
#define MQTTASYNC_BAD_PROTOCOL -14 |
Return code: protocol prefix in serverURI should be tcp://, ssl://, ws:// or wss:// The TLS enabled prefixes (ssl, wss) are only valid if the TLS version of the library is linked with.
在文件 MQTTAsync.h 第 177 行定义.
#define MQTTASYNC_BAD_QOS -9 |
Return code: A qos parameter is not 0, 1 or 2
在文件 MQTTAsync.h 第 155 行定义.
#define MQTTASYNC_BAD_STRUCTURE -8 |
Return code: A structure parameter does not have the correct eyecatcher and version number.
在文件 MQTTAsync.h 第 151 行定义.
#define MQTTASYNC_BAD_UTF8_STRING -5 |
Return code: An invalid UTF-8 string has been detected.
在文件 MQTTAsync.h 第 136 行定义.
#define MQTTAsync_callOptions_initializer MQTTAsync_responseOptions_initializer |
在文件 MQTTAsync.h 第 764 行定义.
#define MQTTASYNC_COMMAND_IGNORED -18 |
在文件 MQTTAsync.h 第 195 行定义.
#define MQTTAsync_connectData_initializer {{'M', 'Q', 'C', 'D'}, 0, NULL, {0, NULL}} |
在文件 MQTTAsync.h 第 479 行定义.
#define MQTTAsync_connectOptions_initializer |
在文件 MQTTAsync.h 第 1358 行定义.
#define MQTTAsync_connectOptions_initializer5 |
在文件 MQTTAsync.h 第 1361 行定义.
#define MQTTAsync_connectOptions_initializer5_ws |
在文件 MQTTAsync.h 第 1367 行定义.
#define MQTTAsync_connectOptions_initializer_ws |
在文件 MQTTAsync.h 第 1364 行定义.
#define MQTTAsync_createOptions_initializer { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_DEFAULT, 0, 0, 1, 1} |
在文件 MQTTAsync.h 第 979 行定义.
#define MQTTAsync_createOptions_initializer5 { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_5, 0, 0, 1, 1} |
在文件 MQTTAsync.h 第 981 行定义.
#define MQTTASYNC_DISCONNECTED -3 |
Return code: The client is disconnected.
在文件 MQTTAsync.h 第 127 行定义.
#define MQTTAsync_disconnectOptions_initializer |
在文件 MQTTAsync.h 第 1445 行定义.
#define MQTTAsync_disconnectOptions_initializer5 |
在文件 MQTTAsync.h 第 1448 行定义.
#define MQTTASYNC_FAILURE -1 |
Return code: A generic error code indicating the failure of an MQTT client operation.
在文件 MQTTAsync.h 第 118 行定义.
#define MQTTAsync_failureData5_initializer {{'M', 'Q', 'F', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, 0, NULL, 0} |
在文件 MQTTAsync.h 第 557 行定义.
#define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 } |
在文件 MQTTAsync.h 第 231 行定义.
#define MQTTASYNC_MAX_BUFFERED_MESSAGES -12 |
Return code: no more messages can be buffered
在文件 MQTTAsync.h 第 167 行定义.
#define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4 |
Return code: The maximum number of messages allowed to be simultaneously in-flight has been reached.
在文件 MQTTAsync.h 第 132 行定义.
#define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer } |
在文件 MQTTAsync.h 第 324 行定义.
#define MQTTASYNC_NO_MORE_MSGIDS -10 |
Return code: All 65535 MQTT msgids are being used
在文件 MQTTAsync.h 第 159 行定义.
#define MQTTASYNC_NULL_PARAMETER -6 |
Return code: A NULL parameter has been supplied when this is invalid.
在文件 MQTTAsync.h 第 140 行定义.
#define MQTTASYNC_OPERATION_INCOMPLETE -11 |
Return code: the request is being discarded when not complete
在文件 MQTTAsync.h 第 163 行定义.
#define MQTTASYNC_PERSISTENCE_ERROR -2 |
在文件 MQTTAsync.h 第 122 行定义.
#define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 1, NULL, NULL, 0, 0, NULL, NULL, MQTTProperties_initializer, MQTTSubscribe_options_initializer, 0, NULL} |
在文件 MQTTAsync.h 第 760 行定义.
#define MQTTASYNC_SSL_NOT_SUPPORTED -13 |
Return code: Attempting SSL connection using non-SSL version of library
在文件 MQTTAsync.h 第 171 行定义.
#define MQTTAsync_SSLOptions_initializer { {'M', 'Q', 'T', 'S'}, 5, NULL, NULL, NULL, NULL, NULL, 1, MQTT_SSL_VERSION_DEFAULT, 0, NULL, NULL, NULL, NULL, NULL, 0, NULL, 0 } |
在文件 MQTTAsync.h 第 1158 行定义.
#define MQTTASYNC_SUCCESS 0 |
Return code: No error. Indicates successful completion of an MQTT client operation.
在文件 MQTTAsync.h 第 113 行定义.
#define MQTTAsync_successData5_initializer {{'M', 'Q', 'S', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, {.sub={0,0}}} |
在文件 MQTTAsync.h 第 630 行定义.
#define MQTTASYNC_TOPICNAME_TRUNCATED -7 |
Return code: The topic has been truncated (the topic string includes embedded NULL characters). String functions will not access the full topic. Use the topic length value to access the full topic.
在文件 MQTTAsync.h 第 146 行定义.
#define MQTTASYNC_TRUE 1 |
Tests whether a request corresponding to a token is complete.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
token | An MQTTAsync_token associated with a request. |
在文件 MQTTAsync.h 第 1616 行定义.
#define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } } |
在文件 MQTTAsync.h 第 1028 行定义.
#define MQTTASYNC_WRONG_MQTT_VERSION -16 |
Return code: call not applicable to the client's version of MQTT
在文件 MQTTAsync.h 第 185 行定义.
#define MQTTVERSION_3_1 3 |
MQTT version to connect with: 3.1
在文件 MQTTAsync.h 第 203 行定义.
#define MQTTVERSION_3_1_1 4 |
MQTT version to connect with: 3.1.1
在文件 MQTTAsync.h 第 207 行定义.
#define MQTTVERSION_5 5 |
MQTT version to connect with: 5
在文件 MQTTAsync.h 第 211 行定义.
#define MQTTVERSION_DEFAULT 0 |
Default MQTT version to connect with. Use 3.1.1 then fall back to 3.1
在文件 MQTTAsync.h 第 199 行定义.
typedef void* MQTTAsync |
A handle representing an MQTT client. A valid client handle is available following a successful call to MQTTAsync_create().
在文件 MQTTAsync.h 第 243 行定义.
typedef struct MQTTAsync_responseOptions MQTTAsync_callOptions |
A synonym for responseOptions to better reflect its usage since MQTT 5.0
在文件 MQTTAsync.h 第 763 行定义.
typedef void MQTTAsync_connected(void *context, char *cause) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context. |
cause | The reason for the disconnection. Currently, cause is always set to NULL. |
在文件 MQTTAsync.h 第 420 行定义.
typedef void MQTTAsync_connectionLost(void *context, char *cause) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context. |
cause | The reason for the disconnection. Currently, cause is always set to NULL. |
在文件 MQTTAsync.h 第 402 行定义.
typedef void MQTTAsync_deliveryComplete(void *context, MQTTAsync_token token) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context. |
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. |
在文件 MQTTAsync.h 第 382 行定义.
typedef void MQTTAsync_disconnected(void *context, MQTTProperties *properties, enum MQTTReasonCodes reasonCode) |
This is a callback function, which will be called when the client library receives a disconnect packet.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context. |
properties | the properties in the disconnect packet. |
properties | the reason code from the disconnect packet Currently, cause is always set to NULL. |
在文件 MQTTAsync.h 第 434 行定义.
typedef int MQTTAsync_messageArrived(void *context, char *topicName, int topicLen, MQTTAsync_message *message) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_setCallbacks(), which contains any application-specific context. |
topicName | The topic associated with the received message. |
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. |
message | The MQTTAsync_message structure for the received message. This structure contains the message payload and attributes. |
在文件 MQTTAsync.h 第 359 行定义.
typedef void MQTTAsync_onFailure(void *context, MQTTAsync_failureData *response) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_responseOptions, which contains any application-specific context. |
response | Failure data associated with the API completion. |
在文件 MQTTAsync.h 第 676 行定义.
typedef void MQTTAsync_onFailure5(void *context, MQTTAsync_failureData5 *response) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_responseOptions, which contains any application-specific context. |
response | Failure data associated with the API completion. |
在文件 MQTTAsync.h 第 691 行定义.
typedef void MQTTAsync_onSuccess(void *context, MQTTAsync_successData *response) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_responseOptions, which contains any application-specific context. |
response | Any success data associated with the API completion. |
在文件 MQTTAsync.h 第 645 行定义.
typedef void MQTTAsync_onSuccess5(void *context, MQTTAsync_successData5 *response) |
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.
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
context | A pointer to the context value originally passed to MQTTAsync_responseOptions, which contains any application-specific context. |
response | Any success data associated with the API completion. |
在文件 MQTTAsync.h 第 661 行定义.
typedef struct MQTTAsync_responseOptions MQTTAsync_responseOptions |
Structure to define call options. For MQTT 5.0 there is input data as well as that describing the response method. So there is now also a synonym MQTTAsync_callOptions to better reflect the use. This responseOptions name is kept for backward compatibility.
typedef int MQTTAsync_token |
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()).
在文件 MQTTAsync.h 第 253 行定义.
typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char *message) |
This is a callback function prototype which must be implemented if you want to receive trace information.
level | the trace level of the message returned |
message | 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. |
在文件 MQTTAsync.h 第 1705 行定义.
typedef int MQTTAsync_updateConnectOptions(void *context, MQTTAsync_connectData *data) |
This is a callback function which will allow the client application to update the connection data.
data | The connection data which can be modified by the application. |
在文件 MQTTAsync.h 第 487 行定义.
枚举值 | |
---|---|
MQTTASYNC_TRACE_MAXIMUM | |
MQTTASYNC_TRACE_MEDIUM | |
MQTTASYNC_TRACE_MINIMUM | |
MQTTASYNC_TRACE_PROTOCOL | |
MQTTASYNC_TRACE_ERROR | |
MQTTASYNC_TRACE_SEVERE | |
MQTTASYNC_TRACE_FATAL |
在文件 MQTTAsync.h 第 1677 行定义.
LIBMQTT_API int MQTTAsync_connect | ( | MQTTAsync | handle, |
const MQTTAsync_connectOptions * | options | ||
) |
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().
handle | A valid client handle from a successful call to MQTTAsync_create(). |
options | A pointer to a valid MQTTAsync_connectOptions structure. |
LIBMQTT_API int MQTTAsync_create | ( | MQTTAsync * | handle, |
const char * | serverURI, | ||
const char * | clientId, | ||
int | persistence_type, | ||
void * | persistence_context | ||
) |
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().
handle | A pointer to an MQTTAsync handle. The handle is populated with a valid client reference following a successful return from this function. |
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, ssl, ws or wss. The TLS enabled prefixes (ssl, wss) are only valid if a TLS version of the library is linked with. 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. |
clientId | The client identifier passed to the server when the client connects to it. It is a null-terminated UTF-8 encoded string. |
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. |
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. |
LIBMQTT_API int MQTTAsync_createWithOptions | ( | MQTTAsync * | handle, |
const char * | serverURI, | ||
const char * | clientId, | ||
int | persistence_type, | ||
void * | persistence_context, | ||
MQTTAsync_createOptions * | options | ||
) |
LIBMQTT_API void MQTTAsync_destroy | ( | MQTTAsync * | handle | ) |
This function frees the memory allocated to an MQTT client (see MQTTAsync_create()). It should be called when the client is no longer required.
handle | A pointer to the handle referring to the MQTTAsync structure to be freed. |
LIBMQTT_API int MQTTAsync_disconnect | ( | MQTTAsync | handle, |
const MQTTAsync_disconnectOptions * | options | ||
) |
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()).
handle | A valid client handle from a successful call to MQTTAsync_create(). |
options | The client delays disconnection for up to this time (in milliseconds) in order to allow in-flight message transfers to complete. |
LIBMQTT_API void MQTTAsync_free | ( | void * | ptr | ) |
This function frees memory allocated by the MQTT C client library, especially the topic name. This is needed on Windows when the client library 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.
ptr | The pointer to the client library storage to be freed. |
LIBMQTT_API void MQTTAsync_freeMessage | ( | MQTTAsync_message ** | msg | ) |
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.
msg | The address of a pointer to the MQTTAsync_message structure to be freed. |
LIBMQTT_API int MQTTAsync_getPendingTokens | ( | MQTTAsync | handle, |
MQTTAsync_token ** | tokens | ||
) |
This function sets a pointer to an array of tokens for messages that are currently in-flight (pending completion).
Important note: The memory used to hold the array of tokens is malloc()'d in this function. The client application is responsible for freeing this memory when it is no longer required.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
tokens | The address of a pointer to an MQTTAsync_token. When the function returns successfully, the pointer is set to point to an array of tokens representing messages pending completion. The last member of the array is set to -1 to indicate there are no more tokens. If no tokens are pending, the pointer is set to NULL. |
LIBMQTT_API MQTTAsync_nameValue* MQTTAsync_getVersionInfo | ( | void | ) |
This function returns version information about the library. no trace information will be returned. The default trace level is MQTTASYNC_TRACE_MINIMUM
LIBMQTT_API void MQTTAsync_global_init | ( | MQTTAsync_init_options * | inits | ) |
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)
LIBMQTT_API int MQTTAsync_isComplete | ( | MQTTAsync | handle, |
MQTTAsync_token | token | ||
) |
LIBMQTT_API int MQTTAsync_isConnected | ( | MQTTAsync | handle | ) |
This function allows the client application to test whether or not a client is currently connected to the MQTT server.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
LIBMQTT_API void* MQTTAsync_malloc | ( | size_t | size | ) |
This function is used to allocate memory to be used or freed by the MQTT C client library, especially the data in the MQTTPersistence_afterRead and MQTTPersistence_beforeWrite callbacks. This is needed on Windows when the client library and application program have been compiled with different versions of the C compiler.
size | The size of the memory to be allocated. |
LIBMQTT_API int MQTTAsync_reconnect | ( | MQTTAsync | handle | ) |
Reconnects a client with the previously used connect options. Connect must have previously been called for this to work.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
LIBMQTT_API int MQTTAsync_send | ( | MQTTAsync | handle, |
const char * | destinationName, | ||
int | payloadlen, | ||
const void * | payload, | ||
int | qos, | ||
int | retained, | ||
MQTTAsync_responseOptions * | response | ||
) |
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 QoS is greater than 0. If the client application needs to test for successful delivery of messages, a callback should be set (see MQTTAsync_onSuccess() and MQTTAsync_deliveryComplete()).
handle | A valid client handle from a successful call to MQTTAsync_create(). |
destinationName | The topic associated with this message. |
payloadlen | The length of the payload in bytes. |
payload | A pointer to the byte array payload of the message. |
qos | The qos of the message. |
retained | The retained flag for the message. |
response | A pointer to an MQTTAsync_responseOptions structure. Used to set callback functions. This is optional and can be set to NULL. |
LIBMQTT_API int MQTTAsync_sendMessage | ( | MQTTAsync | handle, |
const char * | destinationName, | ||
const MQTTAsync_message * | msg, | ||
MQTTAsync_responseOptions * | response | ||
) |
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 QoS is greater than 0. If the client application needs to test for successful delivery of messages, a callback should be set (see MQTTAsync_onSuccess() and MQTTAsync_deliveryComplete()).
handle | A valid client handle from a successful call to MQTTAsync_create(). |
destinationName | The topic associated with this message. |
msg | A pointer to a valid MQTTAsync_message structure containing the payload and attributes of the message to be published. |
response | A pointer to an MQTTAsync_responseOptions structure. Used to set callback functions. |
LIBMQTT_API int MQTTAsync_setAfterPersistenceRead | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTPersistence_afterRead * | co | ||
) |
Sets the MQTTPersistence_afterRead() callback function for a client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
context | A pointer to any application-specific context. The the context pointer is passed to the callback function to provide access to the context information in the callback. |
co | A pointer to an MQTTPersistence_beforeWrite() callback function. NULL removes the callback setting. |
LIBMQTT_API int MQTTAsync_setBeforePersistenceWrite | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTPersistence_beforeWrite * | co | ||
) |
Sets the MQTTPersistence_beforeWrite() callback function for a client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
context | A pointer to any application-specific context. The the context pointer is passed to the callback function to provide access to the context information in the callback. |
co | A pointer to an MQTTPersistence_beforeWrite() callback function. NULL removes the callback setting. |
LIBMQTT_API int MQTTAsync_setCallbacks | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_connectionLost * | cl, | ||
MQTTAsync_messageArrived * | ma, | ||
MQTTAsync_deliveryComplete * | dc | ||
) |
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.
Note: The MQTT client must be disconnected when this function is called.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
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. |
cl | A pointer to an MQTTAsync_connectionLost() callback function. You can set this to NULL if your application doesn't handle disconnections. |
ma | A pointer to an MQTTAsync_messageArrived() callback function. If this callback is not set, an error will be returned. You must set this callback because otherwise there would be no way to deliver any incoming messages. |
dc | A pointer to an MQTTAsync_deliveryComplete() callback function. You can set this to NULL if you do not want to check for successful delivery. |
LIBMQTT_API int MQTTAsync_setConnected | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_connected * | co | ||
) |
Sets the MQTTAsync_connected() callback function for a client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
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. |
co | A pointer to an MQTTAsync_connected() callback function. NULL removes the callback setting. |
LIBMQTT_API int MQTTAsync_setConnectionLostCallback | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_connectionLost * | cl | ||
) |
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.
Note: The MQTT client must be disconnected when this function is called.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
context | A pointer to any application-specific context. The the context pointer is passed the callback functions to provide access to the context information in the callback. |
cl | A pointer to an MQTTAsync_connectionLost() callback function. You can set this to NULL if your application doesn't handle disconnections. |
LIBMQTT_API int MQTTAsync_setDeliveryCompleteCallback | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_deliveryComplete * | dc | ||
) |
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.
Note: The MQTT client must be disconnected when this function is called.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
context | A pointer to any application-specific context. The the context pointer is passed to the callback functions to provide access to the context information in the callback. |
dc | A pointer to an MQTTAsync_deliveryComplete() callback function. You can set this to NULL if you do not want to check for successful delivery. |
LIBMQTT_API int MQTTAsync_setDisconnected | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_disconnected * | co | ||
) |
Sets the MQTTAsync_disconnected() callback function for a client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
Note: Neither MQTTAsync_create() nor MQTTAsync_destroy() should be called within this callback.
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. |
co | A pointer to an MQTTAsync_connected() callback function. NULL removes the callback setting. |
LIBMQTT_API int MQTTAsync_setMessageArrivedCallback | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_messageArrived * | ma | ||
) |
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.
Note: The MQTT client must be disconnected when this function is called.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
context | A pointer to any application-specific context. The the context pointer is passed to the callback functions to provide access to the context information in the callback. |
ma | A pointer to an MQTTAsync_messageArrived() callback function. You can set this to NULL if your application doesn't handle receipt of messages. |
LIBMQTT_API void MQTTAsync_setTraceCallback | ( | MQTTAsync_traceCallback * | callback | ) |
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.
callback | a pointer to the function which will handle the trace information |
LIBMQTT_API void MQTTAsync_setTraceLevel | ( | enum MQTTASYNC_TRACE_LEVELS | level | ) |
This function sets the level of trace information which will be returned in the trace callback.
level | the trace level required |
LIBMQTT_API int MQTTAsync_setUpdateConnectOptions | ( | MQTTAsync | handle, |
void * | context, | ||
MQTTAsync_updateConnectOptions * | co | ||
) |
Sets the MQTTAsync_updateConnectOptions() callback function for a client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
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. |
co | A pointer to an MQTTAsync_updateConnectOptions() callback function. NULL removes the callback setting. |
LIBMQTT_API const char* MQTTAsync_strerror | ( | int | code | ) |
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.
code | the MQTTASYNC_ return code. |
LIBMQTT_API int MQTTAsync_subscribe | ( | MQTTAsync | handle, |
const char * | topic, | ||
int | qos, | ||
MQTTAsync_responseOptions * | response | ||
) |
This function attempts to subscribe a client to a single topic, which may contain wildcards (see wildcard). This call also specifies the qos requested for the subscription (see also MQTTAsync_subscribeMany()).
handle | A valid client handle from a successful call to MQTTAsync_create(). |
topic | The subscription topic, which may include wildcards. |
qos | The requested quality of service for the subscription. |
response | A pointer to a response options structure. Used to set callback functions. |
LIBMQTT_API int MQTTAsync_subscribeMany | ( | MQTTAsync | handle, |
int | count, | ||
char *const * | topic, | ||
const int * | qos, | ||
MQTTAsync_responseOptions * | response | ||
) |
This function attempts to subscribe a client to a list of topics, which may contain wildcards (see wildcard). This call also specifies the qos requested for each topic (see also MQTTAsync_subscribe()).
handle | A valid client handle from a successful call to MQTTAsync_create(). |
count | The number of topics for which the client is requesting subscriptions. |
topic | An array (of length count) of pointers to topics, each of which may include wildcards. |
qos | An array (of length count) of qos values. qos[n] is the requested QoS for topic[n]. |
response | A pointer to a response options structure. Used to set callback functions. |
LIBMQTT_API int MQTTAsync_unsubscribe | ( | MQTTAsync | handle, |
const char * | topic, | ||
MQTTAsync_responseOptions * | response | ||
) |
This function attempts to remove an existing subscription made by the specified client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
topic | The topic for the subscription to be removed, which may include wildcards (see wildcard). |
response | A pointer to a response options structure. Used to set callback functions. |
LIBMQTT_API int MQTTAsync_unsubscribeMany | ( | MQTTAsync | handle, |
int | count, | ||
char *const * | topic, | ||
MQTTAsync_responseOptions * | response | ||
) |
This function attempts to remove existing subscriptions to a list of topics made by the specified client.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
count | The number subscriptions to be removed. |
topic | An array (of length count) of pointers to the topics of the subscriptions to be removed, each of which may include wildcards. |
response | A pointer to a response options structure. Used to set callback functions. |
LIBMQTT_API int MQTTAsync_waitForCompletion | ( | MQTTAsync | handle, |
MQTTAsync_token | token, | ||
unsigned long | timeout | ||
) |
Waits for a request corresponding to a token to complete. This only works for messages with QoS greater than 0. A QoS 0 message has no MQTT token. This function will always return MQTTASYNC_SUCCESS for a QoS 0 message.
handle | A valid client handle from a successful call to MQTTAsync_create(). |
token | An MQTTAsync_token associated with a request. |
timeout | the maximum time to wait for completion, in milliseconds |