libmosquitto (3) - Linux Manuals

libmosquitto: MQTT version 3.1 client library

Command to display libmosquitto manual in Linux: $ man 3 libmosquitto

NAME

libmosquitto - MQTT version 3.1 client library

DESCRIPTION

This is an overview of how to use libmosquitto to create MQTT aware client programs. There may be separate man pages on each of the functions described here in the future. There is also a binding for libmosquitto for C++ and a Python implementation. They are not documented here but operate in a similar way.

This is fairly incomplete, please see mosquitto.h for a better description of the functions.

LIBMOSQUITTO SYMBOL NAMES

All public functions in libmosquitto have the prefix "mosquitto_". Any other functions defined in the source code are to be treated as private functions and may change between any release. Do not use these functions!

FUNCTIONS

Library version

int mosquitto_lib_version(int *major, int *minor, int *revision);

Obtain version information about the library. If any of major, minor or revision are not NULL they will return the corresponding version numbers. The return value is an integer representation of the complete version number (e.g. 1009001 for 1.9.1) that can be used for comparisons.

Library initialisation and cleanup

int mosquitto_lib_init(void);
int mosquitto_lib_cleanup(void);

Call mosquitto_lib_init() before using any of the other library functions and mosquitto_lib_cleanup() after finishing with the library.

Client constructor/destructor

struct mosquitto *mosquitto_new(const char *id, bool clean_session, void *userdata);

Create a new mosquitto client instance.

void mosquitto_destroy(struct mosquitto *mosq);

Use to free memory associated with a mosquitto client instance.

int mosquitto_reinitialise(struct mosquitto *mosq, const char *id, bool clean_session, void *userdata);

Authentication and encryption

int mosquitto_username_pw_set(struct mosquitto *mosq, const char *username, const char *password);
int mosquitto_tls_set(struct mosquitto *mosq, const char *cafile, const char *capath, const char *certfile, const char *keyfile, int (*pw_callback)(char *buf, int size, int rwflag, void *userdata));
int mosquitto_tls_opts_set(struct mosquitto *mosq, int cert_reqs, const char *tls_version, const char *ciphers);
int mosquitto_tls_insecure_set(struct mosquitto *mosq, bool value);
int mosquitto_tls_psk_set(struct mosquitto *mosq, const char *psk, const char *identity, const char *ciphers);

Wills

int mosquitto_will_set(struct mosquitto *mosq, const char *topic, int payloadlen, const void *payload, int qos, bool retain);
int mosquitto_will_clear(struct mosquitto *mosq);

Connect/disconnect

int mosquitto_connect(struct mosquitto *mosq, const char *host, int port, int keepalive);
int mosquitto_connect_bind(struct mosquitto *mosq, const char *host, int port, int keepalive, const char *bind_address);
int mosquitto_connect_async(struct mosquitto *mosq, const char *host, int port, int keepalive);
int mosquitto_connect_bind_async(struct mosquitto *mosq, const char *host, int port, int keepalive, const char *bind_address);
int mosquitto_reconnect(struct mosquitto *mosq);
int mosquitto_reconnect_async(struct mosquitto *mosq);
int mosquitto_disconnect(struct mosquitto *mosq);

Publish

int mosquitto_publish(struct mosquitto *mosq, int *mid, const char *topic, int payloadlen, const void *payload, int qos, bool retain);

Subscribe/unsubscribe

int mosquitto_subscribe(struct mosquitto *mosq, int *mid, const char *sub, int qos);
int mosquitto_unsubscribe(struct mosquitto *mosq, int *mid, const char *sub);

Network loop

int mosquitto_loop(struct mosquitto *mosq, int timeout, int max_packets);
int mosquitto_loop_read(struct mosquitto *mosq, int max_packets);
int mosquitto_loop_write(struct mosquitto *mosq, int max_packets);
int mosquitto_loop_misc(struct mosquitto *mosq);
int mosquitto_loop_forever(struct mosquitto *mosq, int timeout, int max_packets);
int mosquitto_socket(struct mosquitto *mosq);
bool mosquitto_want_write(struct mosquitto *mosq);

Threaded network loop

int mosquitto_loop_start(struct mosquitto *mosq);
int mosquitto_loop_stop(struct mosquitto *mosq, bool force);

Misc client functions

int mosquitto_max_inflight_messages_set(struct mosquitto *mosq, unsigned int max_inflight_messages);
int mosquitto_message_retry_set(struct mosquitto *mosq, unsigned int message_retry);
int mosquitto_reconnect_delay_set(struct mosquitto *mosq, unsigned int reconnect_delay, unsigned int reconnect_delay_max, bool reconnect_exponential_backoff);
int mosquitto_user_data_set(struct mosquitto *mosq, void *userdata);

Callbacks

int mosquitto_connect_callback_set(struct mosquitto *mosq, void (*on_connect)(struct mosquitto *, void *, int));
int mosquitto_disconnect_callback_set(struct mosquitto *mosq, void (*on_disconnect)(struct mosquitto *, void *, int));
int mosquitto_publish_callback_set(struct mosquitto *mosq, void (*on_publish)(struct mosquitto *, void *, int));
int mosquitto_message_callback_set(struct mosquitto *mosq, void (*on_message)(struct mosquitto *, void *, const struct mosquitto_message *));
int mosquitto_subscribe_callback_set(struct mosquitto *mosq, void (*on_subscribe)(struct mosquitto *, void *, int, int, const int *));
int mosquitto_unsubscribe_callback_set(struct mosquitto *mosq, void (*on_unsubscribe)(struct mosquitto *, void *, int));
int mosquitto_log_callback_set(struct mosquitto *mosq, void (*on_unsubscribe)(struct mosquitto *, void *, int, const char *));

Utility functions

const char *mosquitto_connack_string(int connack_code);
int mosquitto_message_copy(struct mosquitto_message *dst, const struct mosquitto_message *src);
int mosquitto_message_free(struct mosquitto_message **message);
const char *mosquitto_strerror(int mosq_errno);
int mosquitto_sub_topic_tokenise(const char *subtopic, char ***topics, int *count);
int mosquitto_sub_topic_tokens_free(char ***topics, int count);
int mosquitto_topic_matches_sub(const char *sub, const char *topic, bool *result);

EXAMPLES

#include <stdio.h>
#include <mosquitto.h>

void my_message_callback(struct mosquitto *mosq, void *userdata, const struct mosquitto_message *message)
{
        if(message->payloadlen){
                printf("%s %s\n", message->topic, message->payload);
        }else{
                printf("%s (null)\n", message->topic);
        }
        fflush(stdout);
}

void my_connect_callback(struct mosquitto *mosq, void *userdata, int result)
{
        int i;
        if(!result){
                /* Subscribe to broker information topics on successful connect. */
                mosquitto_subscribe(mosq, NULL, "$SYS/#", 2);
        }else{
                fprintf(stderr, "Connect failed\n");
        }
}

void my_subscribe_callback(struct mosquitto *mosq, void *userdata, int mid, int qos_count, const int *granted_qos)
{
        int i;

        printf("Subscribed (mid: %d): %d", mid, granted_qos[0]);
        for(i=1; i<qos_count; i++){
                printf(", %d", granted_qos[i]);
        }
        printf("\n");
}

void my_log_callback(struct mosquitto *mosq, void *userdata, int level, const char *str)
{
        /* Pring all log messages regardless of level. */
        printf("%s\n", str);
}

int main(int argc, char *argv[])
{
        int i;
        char *host = "localhost";
        int port = 1883;
        int keepalive = 60;
        bool clean_session = true;
        struct mosquitto *mosq = NULL;

        mosquitto_lib_init();
        mosq = mosquitto_new(NULL, clean_session, NULL);
        if(!mosq){
                fprintf(stderr, "Error: Out of memory.\n");
                return 1;
        }
        mosquitto_log_callback_set(mosq, my_log_callback);
        mosquitto_connect_callback_set(mosq, my_connect_callback);
        mosquitto_message_callback_set(mosq, my_message_callback);
        mosquitto_subscribe_callback_set(mosq, my_subscribe_callback);

        if(mosquitto_connect(mosq, host, port, keepalive)){
                fprintf(stderr, "Unable to connect.\n");
                return 1;
        }

        mosquitto_loop_forever(mosq, -1, 1);

        mosquitto_destroy(mosq);
        mosquitto_lib_cleanup();
        return 0;
}

AUTHOR

Roger Light <roger [at] atchoo.org>