'\" t
|
.\" Title: libmosquitto
|
.\" Author: [see the "Author" section]
|
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
|
.\" Date: 06/18/2019
|
.\" Manual: Library calls
|
.\" Source: Mosquitto Project
|
.\" Language: English
|
.\"
|
.TH "LIBMOSQUITTO" "3" "06/18/2019" "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\&.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\&.
|
.PP
|
This man page is woefully incomplete, please see the comments in mosquitto\&.h for missing functions and a 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_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" ");"
|
.SS "Helper functions"
|
.HP \w'int\ mosquitto_subscribe_simple('u
|
.BI "int mosquitto_subscribe_simple(struct\ mosquitto_message\ **" "message" ", int\ " "msg_count" ", bool\ " "want_retained" ", const\ char\ *" "topic" ", int" "qos" ", const\ char\ *" "host" ", int\ " "port" ", const\ char\ *" "client_id" ", int\ " "keepalive" ", bool\ " "clean_session" ", const\ char\ *" "username" ", const\ char\ *" "password" ", const\ struct\ libmosquitto_will\ *" "will" ", const\ struct\ libmosquitto_tls\ *" "tls" ");"
|
.HP \w'int\ mosquitto_subscribe_callback('u
|
.BI "int mosquitto_subscribe_callback(int\ " "(*callback)(struct\ mosquitto\ *,\ void\ *,\ const\ struct\ mosquitto_message\ *)" ", void\ *" "userdata" ", const\ char\ *" "topic" ", int\ " "qos" ", const\ char\ *" "host" ", int\ " "port" ", const\ char\ *" "client_id" ", int\ " "keepalive" ", bool\ " "clean_session" ", const\ char\ *" "username" ", const\ char\ *" "password" ", const\ struct\ libmosquitto_will\ *" "will" ", const\ struct\ libmosquitto_tls\ *" "tls" ");"
|
.SH "EXAMPLES"
|
.PP
|
.if n \{\
|
.RS 4
|
.\}
|
.nf
|
#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\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<qos_count; i++){
|
printf(", %d", granted_qos[i]);
|
}
|
printf("\en");
|
}
|
|
void my_log_callback(struct mosquitto *mosq, void *userdata, int level, const char *str)
|
{
|
/* Pring all log messages regardless of level\&. */
|
printf("%s\en", 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\&.\en");
|
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\&.\en");
|
return 1;
|
}
|
|
mosquitto_loop_forever(mosq, \-1, 1);
|
|
mosquitto_destroy(mosq);
|
mosquitto_lib_cleanup();
|
return 0;
|
}
|
|
.fi
|
.if n \{\
|
.RE
|
.\}
|
.SH "SEE ALSO"
|
\fBmosquitto\fR(8)\fBmqtt\fR(7)
|
.SH "AUTHOR"
|
.PP
|
Roger Light
|
<roger@atchoo\&.org>
|
