MQTTAsync.h

浏览该文件的文档.

/*******************************************************************************
 * Copyright (c) 2009, 2021 IBM Corp., Ian Craggs and others
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v2.0
 * and Eclipse Distribution License v1.0 which accompany this distribution.
 *
 * The Eclipse Public License is available at
 *    https://www.eclipse.org/legal/epl-2.0/
 * and the Eclipse Distribution License is available at
 *   http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *    Ian Craggs - initial API and implementation
 *    Ian Craggs, Allan Stockdill-Mander - SSL connections
 *    Ian Craggs - multiple server connection support
 *    Ian Craggs - MQTT 3.1.1 support
 *    Ian Craggs - fix for bug 444103 - success/failure callbacks not invoked
 *    Ian Craggs - automatic reconnect and offline buffering (send while disconnected)
 *    Ian Craggs - binary will message
 *    Ian Craggs - binary password
 *    Ian Craggs - remove const on eyecatchers #168
 *    Ian Craggs - MQTT 5.0
 *******************************************************************************/

/********************************************************************/

/*
*/
#if !defined(MQTTASYNC_H)
#define MQTTASYNC_H

#if defined(__cplusplus)
 extern "C" {
#endif

#include <stdio.h>
/*
*/

#include "MQTTExportDeclarations.h"

#include "MQTTProperties.h"
#include "MQTTReasonCodes.h"
#include "MQTTSubscribeOpts.h"
#if !defined(NO_PERSISTENCE)
#include "MQTTClientPersistence.h"
#endif

#define MQTTASYNC_SUCCESS 0

#define MQTTASYNC_FAILURE -1

/* error code -2 is MQTTAsync_PERSISTENCE_ERROR */

#define MQTTASYNC_PERSISTENCE_ERROR -2

#define MQTTASYNC_DISCONNECTED -3

#define MQTTASYNC_MAX_MESSAGES_INFLIGHT -4

#define MQTTASYNC_BAD_UTF8_STRING -5

#define MQTTASYNC_NULL_PARAMETER -6

#define MQTTASYNC_TOPICNAME_TRUNCATED -7

#define MQTTASYNC_BAD_STRUCTURE -8

#define MQTTASYNC_BAD_QOS -9

#define MQTTASYNC_NO_MORE_MSGIDS -10

#define MQTTASYNC_OPERATION_INCOMPLETE -11

#define MQTTASYNC_MAX_BUFFERED_MESSAGES -12

#define MQTTASYNC_SSL_NOT_SUPPORTED -13

#define MQTTASYNC_BAD_PROTOCOL -14

#define MQTTASYNC_BAD_MQTT_OPTION -15

#define MQTTASYNC_WRONG_MQTT_VERSION -16

#define MQTTASYNC_0_LEN_WILL_TOPIC -17
/*
 * Return code: connect or disconnect command ignored because there is already a connect or disconnect
 * command at the head of the list waiting to be processed. Use the onSuccess/onFailure callbacks to wait
 * for the previous connect or disconnect command to be complete.
 */
#define MQTTASYNC_COMMAND_IGNORED -18

#define MQTTVERSION_DEFAULT 0

#define MQTTVERSION_3_1 3

#define MQTTVERSION_3_1_1 4

#define MQTTVERSION_5 5

#define MQTT_BAD_SUBSCRIBE 0x80


typedef struct
{
    char struct_id[4];
    int struct_version;
    int do_openssl_init;
} MQTTAsync_init_options;

#define MQTTAsync_init_options_initializer { {'M', 'Q', 'T', 'G'}, 0, 0 }

LIBMQTT_API void MQTTAsync_global_init(MQTTAsync_init_options* inits);

typedef void* MQTTAsync;
typedef int MQTTAsync_token;

typedef struct
{
    char struct_id[4];
    int struct_version;
    int payloadlen;
    void* payload;
    int qos;
    int retained;
    int dup;
    int msgid;
    MQTTProperties properties;
} MQTTAsync_message;

#define MQTTAsync_message_initializer { {'M', 'Q', 'T', 'M'}, 1, 0, NULL, 0, 0, 0, 0, MQTTProperties_initializer }

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);

LIBMQTT_API int MQTTAsync_setDisconnected(MQTTAsync handle, void* context, MQTTAsync_disconnected* co);

typedef struct
{
    char struct_id[4];
    int struct_version;
    const char* username;
    struct {
        int len;           
        const void* data;  
    } binarypwd;
} MQTTAsync_connectData;

#define MQTTAsync_connectData_initializer {{'M', 'Q', 'C', 'D'}, 0, NULL, {0, NULL}}

typedef int MQTTAsync_updateConnectOptions(void* context, MQTTAsync_connectData* data);

LIBMQTT_API int MQTTAsync_setUpdateConnectOptions(MQTTAsync handle, void* context, MQTTAsync_updateConnectOptions* co);

LIBMQTT_API int MQTTAsync_setBeforePersistenceWrite(MQTTAsync handle, void* context, MQTTPersistence_beforeWrite* co);


LIBMQTT_API int MQTTAsync_setAfterPersistenceRead(MQTTAsync handle, void* context, MQTTPersistence_afterRead* co);


typedef struct
{
    MQTTAsync_token token;
    int code;
    const char *message;
} MQTTAsync_failureData;


typedef struct
{
    char struct_id[4];
    int struct_version;
    MQTTAsync_token token;
    enum MQTTReasonCodes reasonCode;
    MQTTProperties properties;
    int code;
    const char *message;
    int packet_type;
} MQTTAsync_failureData5;

#define MQTTAsync_failureData5_initializer {{'M', 'Q', 'F', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, 0, NULL, 0}

typedef struct
{
    MQTTAsync_token token;
    union
    {
        int qos;
        int* qosList;
        struct
        {
            MQTTAsync_message message; 
            char* destinationName;     
        } pub;
        /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
        struct
        {
            char* serverURI; 
            int MQTTVersion; 
            int sessionPresent; 
        } connect;
    } alt;
} MQTTAsync_successData;


typedef struct
{
    char struct_id[4];      
    int struct_version;     
    MQTTAsync_token token;
    enum MQTTReasonCodes reasonCode;    
    MQTTProperties properties;              
    union
    {
        struct
        {
            int reasonCodeCount; 
            enum MQTTReasonCodes* reasonCodes; 
        } sub;
        struct
        {
            MQTTAsync_message message; 
            char* destinationName;     
        } pub;
        /* For connect, the server connected to, MQTT version used, and sessionPresent flag */
        struct
        {
            char* serverURI;  
            int MQTTVersion;  
            int sessionPresent;  
        } connect;
        struct
        {
            int reasonCodeCount; 
            enum MQTTReasonCodes* reasonCodes; 
        } unsub;
    } alt;
} MQTTAsync_successData5;

#define MQTTAsync_successData5_initializer {{'M', 'Q', 'S', 'D'}, 0, 0, MQTTREASONCODE_SUCCESS, MQTTProperties_initializer, {.sub={0,0}}}

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
{
    char struct_id[4];
    int struct_version;
    MQTTAsync_onSuccess* onSuccess;
    MQTTAsync_onFailure* onFailure;
    void* context;
    MQTTAsync_token token;
    MQTTAsync_onSuccess5* onSuccess5;
    MQTTAsync_onFailure5* onFailure5;
    MQTTProperties properties;
    /*
     * MQTT V5 subscribe options, when used with subscribe only.
     */
    MQTTSubscribe_options subscribeOptions;
    /*
     * MQTT V5 subscribe option count, when used with subscribeMany only.
     * The number of entries in the subscribe_options_list array.
     */
    int subscribeOptionsCount;
    /*
     * MQTT V5 subscribe option array, when used with subscribeMany only.
     */
    MQTTSubscribe_options* subscribeOptionsList;
} MQTTAsync_responseOptions;

#define MQTTAsync_responseOptions_initializer { {'M', 'Q', 'T', 'R'}, 1, NULL, NULL, 0, 0, NULL, NULL, MQTTProperties_initializer, MQTTSubscribe_options_initializer, 0, NULL}

typedef struct MQTTAsync_responseOptions MQTTAsync_callOptions;
#define MQTTAsync_callOptions_initializer MQTTAsync_responseOptions_initializer

LIBMQTT_API int MQTTAsync_setCallbacks(MQTTAsync handle, void* context, MQTTAsync_connectionLost* cl,
                                     MQTTAsync_messageArrived* ma, MQTTAsync_deliveryComplete* dc);

LIBMQTT_API int MQTTAsync_setConnectionLostCallback(MQTTAsync handle, void* context,
                                                  MQTTAsync_connectionLost* cl);

LIBMQTT_API int MQTTAsync_setMessageArrivedCallback(MQTTAsync handle, void* context,
                                                  MQTTAsync_messageArrived* ma);

LIBMQTT_API int MQTTAsync_setDeliveryCompleteCallback(MQTTAsync handle, void* context,
                                                    MQTTAsync_deliveryComplete* dc);

LIBMQTT_API int MQTTAsync_setConnected(MQTTAsync handle, void* context, MQTTAsync_connected* co);


LIBMQTT_API int MQTTAsync_reconnect(MQTTAsync handle);


LIBMQTT_API int MQTTAsync_create(MQTTAsync* handle, const char* serverURI, const char* clientId,
        int persistence_type, void* persistence_context);

typedef struct
{
    char struct_id[4];
    int struct_version;
    int sendWhileDisconnected;
    int maxBufferedMessages;
    int MQTTVersion;
    int allowDisconnectedSendAtAnyTime;
    /*
     * When the maximum number of buffered messages is reached, delete the oldest rather than the newest.
     */
    int deleteOldestMessages;
    /*
     * Restore messages from persistence on create - or clear it.
     */
    int restoreMessages;
    /*
     * Persist QoS0 publish commands - an option to not persist them.
     */
    int persistQoS0;
} MQTTAsync_createOptions;

#define MQTTAsync_createOptions_initializer  { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_DEFAULT, 0, 0, 1, 1}

#define MQTTAsync_createOptions_initializer5 { {'M', 'Q', 'C', 'O'}, 2, 0, 100, MQTTVERSION_5, 0, 0, 1, 1}


LIBMQTT_API int MQTTAsync_createWithOptions(MQTTAsync* handle, const char* serverURI, const char* clientId,
        int persistence_type, void* persistence_context, MQTTAsync_createOptions* options);

typedef struct
{
    char struct_id[4];
    int struct_version;
    const char* topicName;
    const char* message;
    int retained;
    int qos;
    struct
    {
    int len;            
        const void* data;  
    } payload;
} MQTTAsync_willOptions;

#define MQTTAsync_willOptions_initializer { {'M', 'Q', 'T', 'W'}, 1, NULL, NULL, 0, 0, { 0, NULL } }

#define MQTT_SSL_VERSION_DEFAULT 0
#define MQTT_SSL_VERSION_TLS_1_0 1
#define MQTT_SSL_VERSION_TLS_1_1 2
#define MQTT_SSL_VERSION_TLS_1_2 3

typedef struct
{
    char struct_id[4];

    int struct_version;

    const char* trustStore;

    const char* keyStore;

    const char* privateKey;

    const char* privateKeyPassword;

    const char* enabledCipherSuites;

    int enableServerCertAuth;

    int sslVersion;

    int verify;

    const char* CApath;

    int (*ssl_error_cb) (const char *str, size_t len, void *u);

    void* ssl_error_context;

    unsigned int (*ssl_psk_cb) (const char *hint, char *identity, unsigned int max_identity_len, unsigned char *psk, unsigned int max_psk_len, void *u);

    void* ssl_psk_context;

    int disableDefaultTrustStore;

    const unsigned char *protos;

    unsigned int protos_len;
} MQTTAsync_SSLOptions;

#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 }

typedef struct
{
    const char* name; 
    const char* value; 
} MQTTAsync_nameValue;

typedef struct
{
    char struct_id[4];
    int struct_version;
    int keepAliveInterval;
    int cleansession;
    int maxInflight;
    MQTTAsync_willOptions* will;
    const char* username;
    const char* password;
    int connectTimeout;
    int retryInterval;
    MQTTAsync_SSLOptions* ssl;
    MQTTAsync_onSuccess* onSuccess;
    MQTTAsync_onFailure* onFailure;
    void* context;
    int serverURIcount;
    char* const* serverURIs;
    int MQTTVersion;
    int automaticReconnect;
    int minRetryInterval;
    int maxRetryInterval;
    struct {
        int len;            
        const void* data;  
    } binarypwd;
    /*
     * MQTT V5 clean start flag.  Only clears state at the beginning of the session.
     */
    int cleanstart;
    MQTTProperties *connectProperties;
    MQTTProperties *willProperties;
    MQTTAsync_onSuccess5* onSuccess5;
    MQTTAsync_onFailure5* onFailure5;
    const MQTTAsync_nameValue* httpHeaders;
    const char* httpProxy;
    const char* httpsProxy;
} MQTTAsync_connectOptions;


#define MQTTAsync_connectOptions_initializer { {'M', 'Q', 'T', 'C'}, 8, 60, 1, 65535, NULL, NULL, NULL, 30, 0,\
NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0, 1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

#define MQTTAsync_connectOptions_initializer5 { {'M', 'Q', 'T', 'C'}, 8, 60, 0, 65535, NULL, NULL, NULL, 30, 0,\
NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60, {0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

#define MQTTAsync_connectOptions_initializer_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 1, 65535, NULL, NULL, NULL, 30, 0,\
NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_DEFAULT, 0, 1, 60, {0, NULL}, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

#define MQTTAsync_connectOptions_initializer5_ws { {'M', 'Q', 'T', 'C'}, 8, 45, 0, 65535, NULL, NULL, NULL, 30, 0,\
NULL, NULL, NULL, NULL, 0, NULL, MQTTVERSION_5, 0, 1, 60, {0, NULL}, 1, NULL, NULL, NULL, NULL, NULL, NULL, NULL}


LIBMQTT_API int MQTTAsync_connect(MQTTAsync handle, const MQTTAsync_connectOptions* options);

typedef struct
{
    char struct_id[4];
    int struct_version;
    int timeout;
    MQTTAsync_onSuccess* onSuccess;
    MQTTAsync_onFailure* onFailure;
    void* context;
    MQTTProperties properties;
    enum MQTTReasonCodes reasonCode;
    MQTTAsync_onSuccess5* onSuccess5;
    MQTTAsync_onFailure5* onFailure5;
} MQTTAsync_disconnectOptions;

#define MQTTAsync_disconnectOptions_initializer { {'M', 'Q', 'T', 'D'}, 0, 0, NULL, NULL, NULL,\
    MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }

#define MQTTAsync_disconnectOptions_initializer5 { {'M', 'Q', 'T', 'D'}, 1, 0, NULL, NULL, NULL,\
    MQTTProperties_initializer, MQTTREASONCODE_SUCCESS, NULL, NULL }

LIBMQTT_API int MQTTAsync_disconnect(MQTTAsync handle, const MQTTAsync_disconnectOptions* options);


LIBMQTT_API int MQTTAsync_isConnected(MQTTAsync handle);


LIBMQTT_API int MQTTAsync_subscribe(MQTTAsync handle, const char* topic, int qos, MQTTAsync_responseOptions* response);


LIBMQTT_API int MQTTAsync_subscribeMany(MQTTAsync handle, int count, char* const* topic, const int* qos, MQTTAsync_responseOptions* response);

LIBMQTT_API int MQTTAsync_unsubscribe(MQTTAsync handle, const char* topic, MQTTAsync_responseOptions* response);

LIBMQTT_API int MQTTAsync_unsubscribeMany(MQTTAsync handle, int count, char* const* topic, MQTTAsync_responseOptions* response);


LIBMQTT_API int MQTTAsync_send(MQTTAsync handle, const char* destinationName, int payloadlen, const void* payload, int qos,
        int retained, MQTTAsync_responseOptions* response);

LIBMQTT_API int MQTTAsync_sendMessage(MQTTAsync handle, const char* destinationName, const MQTTAsync_message* msg, MQTTAsync_responseOptions* response);


LIBMQTT_API int MQTTAsync_getPendingTokens(MQTTAsync handle, MQTTAsync_token **tokens);

#define MQTTASYNC_TRUE 1
LIBMQTT_API int MQTTAsync_isComplete(MQTTAsync handle, MQTTAsync_token token);


LIBMQTT_API int MQTTAsync_waitForCompletion(MQTTAsync handle, MQTTAsync_token token, unsigned long timeout);


LIBMQTT_API void MQTTAsync_freeMessage(MQTTAsync_message** msg);

LIBMQTT_API void MQTTAsync_free(void* ptr);

LIBMQTT_API void* MQTTAsync_malloc(size_t size);

LIBMQTT_API void MQTTAsync_destroy(MQTTAsync* handle);



enum MQTTASYNC_TRACE_LEVELS
{
    MQTTASYNC_TRACE_MAXIMUM = 1,
    MQTTASYNC_TRACE_MEDIUM,
    MQTTASYNC_TRACE_MINIMUM,
    MQTTASYNC_TRACE_PROTOCOL,
    MQTTASYNC_TRACE_ERROR,
    MQTTASYNC_TRACE_SEVERE,
    MQTTASYNC_TRACE_FATAL,
};


LIBMQTT_API void MQTTAsync_setTraceLevel(enum MQTTASYNC_TRACE_LEVELS level);


typedef void MQTTAsync_traceCallback(enum MQTTASYNC_TRACE_LEVELS level, char* message);

LIBMQTT_API void MQTTAsync_setTraceCallback(MQTTAsync_traceCallback* callback);

LIBMQTT_API MQTTAsync_nameValue* MQTTAsync_getVersionInfo(void);

LIBMQTT_API const char* MQTTAsync_strerror(int code);


#if defined(__cplusplus)
     }
#endif

#endif