'\" t
.\" Title: libmosquitto
.\" Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1
.\" Date: 03/24/2014
.\" Manual: Library calls
.\" Source: Mosquitto Project
.\" Language: English
.\"
.TH "LIBMOSQUITTO" "3" "03/24/2014" "Mosquitto Project" "Library calls"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
libmosquitto \- MQTT version 3\&.1 client library
.SH "DESCRIPTION"
.PP
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\&.
.PP
This is fairly incomplete, please see mosquitto\&.h for a better description of the functions\&.
.SH "LIBMOSQUITTO SYMBOL NAMES"
.PP
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!
.SH "FUNCTIONS"
.SS "Library version"
.HP \w'int\ mosquitto_lib_version('u
.BI "int mosquitto_lib_version(int\ *" "major" ", int\ *" "minor" ", int\ *" "revision" ");"
.PP
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\&.
.SS "Library initialisation and cleanup"
.HP \w'int\ mosquitto_lib_init('u
.BI "int mosquitto_lib_init(void);"
.HP \w'int\ mosquitto_lib_cleanup('u
.BI "int mosquitto_lib_cleanup(void);"
.PP
Call mosquitto_lib_init() before using any of the other library functions and mosquitto_lib_cleanup() after finishing with the library\&.
.SS "Client constructor/destructor"
.HP \w'struct\ mosquitto\ *mosquitto_new('u
.BI "struct mosquitto *mosquitto_new(const\ char\ *" "id" ", bool\ " "clean_session" ", void\ *" "userdata" ");"
.PP
Create a new mosquitto client instance\&.
.HP \w'void\ mosquitto_destroy('u
.BI "void mosquitto_destroy(struct\ mosquitto\ *" "mosq" ");"
.PP
Use to free memory associated with a mosquitto client instance\&.
.HP \w'int\ mosquitto_reinitialise('u
.BI "int mosquitto_reinitialise(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "id" ", bool\ " "clean_session" ", void\ *" "userdata" ");"
.SS "Authentication and encryption"
.HP \w'int\ mosquitto_username_pw_set('u
.BI "int mosquitto_username_pw_set(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "username" ", const\ char\ *" "password" ");"
.HP \w'int\ mosquitto_tls_set('u
.BI "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)" ");"
.HP \w'int\ mosquitto_tls_opts_set('u
.BI "int mosquitto_tls_opts_set(struct\ mosquitto\ *" "mosq" ", int\ " "cert_reqs" ", const\ char\ *" "tls_version" ", const\ char\ *" "ciphers" ");"
.HP \w'int\ mosquitto_tls_insecure_set('u
.BI "int mosquitto_tls_insecure_set(struct\ mosquitto\ *" "mosq" ", bool\ " "value" ");"
.HP \w'int\ mosquitto_tls_psk_set('u
.BI "int mosquitto_tls_psk_set(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "psk" ", const\ char\ *" "identity" ", const\ char\ *" "ciphers" ");"
.SS "Wills"
.HP \w'int\ mosquitto_will_set('u
.BI "int mosquitto_will_set(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "topic" ", int\ " "payloadlen" ", const\ void\ *" "payload" ", int\ " "qos" ", bool\ " "retain" ");"
.HP \w'int\ mosquitto_will_clear('u
.BI "int mosquitto_will_clear(" "struct\ mosquitto\ *mosq" ");"
.SS "Connect/disconnect"
.HP \w'int\ mosquitto_connect('u
.BI "int mosquitto_connect(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "host" ", int\ " "port" ", int\ " "keepalive" ");"
.HP \w'int\ mosquitto_connect_bind('u
.BI "int mosquitto_connect_bind(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "host" ", int\ " "port" ", int\ " "keepalive" ", const\ char\ *" "bind_address" ");"
.HP \w'int\ mosquitto_connect_async('u
.BI "int mosquitto_connect_async(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "host" ", int\ " "port" ", int\ " "keepalive" ");"
.HP \w'int\ mosquitto_connect_bind_async('u
.BI "int mosquitto_connect_bind_async(struct\ mosquitto\ *" "mosq" ", const\ char\ *" "host" ", int\ " "port" ", int\ " "keepalive" ", const\ char\ *" "bind_address" ");"
.HP \w'int\ mosquitto_reconnect('u
.BI "int mosquitto_reconnect(struct\ mosquitto\ *" "mosq" ");"
.HP \w'int\ mosquitto_reconnect_async('u
.BI "int mosquitto_reconnect_async(struct\ mosquitto\ *" "mosq" ");"
.HP \w'int\ mosquitto_disconnect('u
.BI "int mosquitto_disconnect(struct\ mosquitto\ *" "mosq" ");"
.SS "Publish"
.HP \w'int\ mosquitto_publish('u
.BI "int mosquitto_publish(struct\ mosquitto\ *" "mosq" ", int\ *" "mid" ", const\ char\ *" "topic" ", int\ " "payloadlen" ", const\ void\ *" "payload" ", int\ " "qos" ", bool\ " "retain" ");"
.SS "Subscribe/unsubscribe"
.HP \w'int\ mosquitto_subscribe('u
.BI "int mosquitto_subscribe(struct\ mosquitto\ *" "mosq" ", int\ *" "mid" ", const\ char\ *" "sub" ", int\ " "qos" ");"
.HP \w'int\ mosquitto_unsubscribe('u
.BI "int mosquitto_unsubscribe(struct\ mosquitto\ *" "mosq" ", int\ *" "mid" ", const\ char\ *" "sub" ");"
.SS "Network loop"
.HP \w'int\ mosquitto_loop('u
.BI "int mosquitto_loop(struct\ mosquitto\ *" "mosq" ", int\ " "timeout" ", int\ " "max_packets" ");"
.HP \w'int\ mosquitto_loop_read('u
.BI "int mosquitto_loop_read(struct\ mosquitto\ *" "mosq" ", int\ " "max_packets" ");"
.HP \w'int\ mosquitto_loop_write('u
.BI "int mosquitto_loop_write(struct\ mosquitto\ *" "mosq" ", int\ " "max_packets" ");"
.HP \w'int\ mosquitto_loop_misc('u
.BI "int mosquitto_loop_misc(struct\ mosquitto\ *" "mosq" ");"
.HP \w'int\ mosquitto_loop_forever('u
.BI "int mosquitto_loop_forever(struct\ mosquitto\ *" "mosq" ", int\ " "timeout" ", int\ " "max_packets" ");"
.HP \w'int\ mosquitto_socket('u
.BI "int mosquitto_socket(struct\ mosquitto\ *" "mosq" ");"
.HP \w'bool\ mosquitto_want_write('u
.BI "bool mosquitto_want_write(struct\ mosquitto\ *" "mosq" ");"
.SS "Threaded network loop"
.HP \w'int\ mosquitto_loop_start('u
.BI "int mosquitto_loop_start(struct\ mosquitto\ *" "mosq" ");"
.HP \w'int\ mosquitto_loop_stop('u
.BI "int mosquitto_loop_stop(struct\ mosquitto\ *" "mosq" ", bool\ " "force" ");"
.SS "Misc client functions"
.HP \w'int\ mosquitto_max_inflight_messages_set('u
.BI "int mosquitto_max_inflight_messages_set(struct\ mosquitto\ *" "mosq" ", unsigned\ int\ " "max_inflight_messages" ");"
.HP \w'int\ mosquitto_message_retry_set('u
.BI "int mosquitto_message_retry_set(struct\ mosquitto\ *" "mosq" ", unsigned\ int\ " "message_retry" ");"
.HP \w'int\ mosquitto_reconnect_delay_set('u
.BI "int mosquitto_reconnect_delay_set(struct\ mosquitto\ *" "mosq" ", unsigned\ int\ " "reconnect_delay" ", unsigned\ int\ " "reconnect_delay_max" ", bool\ " "reconnect_exponential_backoff" ");"
.HP \w'int\ mosquitto_user_data_set('u
.BI "int mosquitto_user_data_set(struct\ mosquitto\ *" "mosq" ", void\ *" "userdata" ");"
.SS "Callbacks"
.HP \w'int\ mosquitto_connect_callback_set('u
.BI "int mosquitto_connect_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_connect)(struct\ mosquitto\ *,\ void\ *,\ int)" ");"
.HP \w'int\ mosquitto_disconnect_callback_set('u
.BI "int mosquitto_disconnect_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_disconnect)(struct\ mosquitto\ *,\ void\ *,\ int)" ");"
.HP \w'int\ mosquitto_publish_callback_set('u
.BI "int mosquitto_publish_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_publish)(struct\ mosquitto\ *,\ void\ *,\ int)" ");"
.HP \w'int\ mosquitto_message_callback_set('u
.BI "int mosquitto_message_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_message)(struct\ mosquitto\ *,\ void\ *,\ const\ struct\ mosquitto_message\ *)" ");"
.HP \w'int\ mosquitto_subscribe_callback_set('u
.BI "int mosquitto_subscribe_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_subscribe)(struct\ mosquitto\ *,\ void\ *,\ int,\ int,\ const\ int\ *)" ");"
.HP \w'int\ mosquitto_unsubscribe_callback_set('u
.BI "int mosquitto_unsubscribe_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_unsubscribe)(struct\ mosquitto\ *,\ void\ *,\ int)" ");"
.HP \w'int\ mosquitto_log_callback_set('u
.BI "int mosquitto_log_callback_set(struct\ mosquitto\ *" "mosq" ", void\ " "(*on_unsubscribe)(struct\ mosquitto\ *,\ void\ *,\ int,\ const\ char\ *)" ");"
.SS "Utility functions"
.HP \w'const\ char\ *mosquitto_connack_string('u
.BI "const char *mosquitto_connack_string(int\ " "connack_code" ");"
.HP \w'int\ mosquitto_message_copy('u
.BI "int mosquitto_message_copy(struct\ mosquitto_message\ *" "dst" ", const\ struct\ mosquitto_message\ *" "src" ");"
.HP \w'int\ mosquitto_message_free('u
.BI "int mosquitto_message_free(struct\ mosquitto_message\ **" "message" ");"
.HP \w'const\ char\ *mosquitto_strerror('u
.BI "const char *mosquitto_strerror(int\ " "mosq_errno" ");"
.HP \w'int\ mosquitto_sub_topic_tokenise('u
.BI "int mosquitto_sub_topic_tokenise(const\ char\ *" "subtopic" ", char\ ***" "topics" ", int\ *" "count" ");"
.HP \w'int\ mosquitto_sub_topic_tokens_free('u
.BI "int mosquitto_sub_topic_tokens_free(char\ ***" "topics" ", int\ " "count" ");"
.HP \w'int\ mosquitto_topic_matches_sub('u
.BI "int mosquitto_topic_matches_sub(const\ char\ *" "sub" ", const\ char\ *" "topic" ", bool\ *" "result" ");"
.SH "EXAMPLES"
.PP
.if n \{\
.RS 4
.\}
.nf
#include
#include
void my_message_callback(struct mosquitto *mosq, void *userdata, const struct mosquitto_message *message)
{
if(message\->payloadlen){
printf("%s %s\en", message\->topic, message\->payload);
}else{
printf("%s (null)\en", 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\en");
}
}
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