A Rust interface to the Mosquitto MQTT broker client

Mosquitto is a popular MQTT broker implemented in C. Although there are pure Rust MQTT clients, it is still useful to have a binding to the Mosquitto client.

The basic story is that you connect to a broker, subscribing to topics that interest you and publishing messages on a particular topic. The messages may be any arbitrary bytes, but this implementation does require that the topics themselves be UTF-8. The C API is based on callbacks, which are mapped onto Rust closures.

The Mosquitto client is thread-safe, so you can publish from one thread and listen for the messages on another. This example demonstrates mosquitto-client usage:

extern crate mosquitto_client_wrapper as mosq;
use mosq::Mosquitto;
use std::{thread, time};

fn main() {
    let m = Mosquitto::new("test");

    m.connect("localhost",1883,5).expect("can't connect");
    m.subscribe("bilbo/#",1).expect("can't subscribe to bonzo");

    let mt = m.clone();
    thread::spawn(move || {
        let timeout = time::Duration::from_millis(500);
        for _ in 0..5 {
            mt.publish("bilbo/baggins","hello dolly".as_bytes(), 1, false).unwrap();
            thread::sleep(timeout);
        }
        mt.disconnect().unwrap();
    });

    let mut mc = m.callbacks(0);
    mc.on_message(|data,msg| {
        println!("bilbo {:?}",msg);
        *data += 1;
    });

    m.loop_until_disconnect(200).expect("broken loop");
    println!("received {} messages",mc.data);
}

The Mosquitto struct is a thin wrapper around the C pointer we get from the client. It is Clone + Send + Sync, so we can pass it to a thread which simply publishes some bytes and waits; at the end of the thread we explicitly disconnect.

The Callbacks handler struct is separate, to avoid antagonizing the borrow checker. It is created by the callbacks method and is generic over some data (accessed as the data field) Whenever an event occurs, the callback will be passed a mutable reference to that data, and event-specific data - in this case a message struct.

loop_until_disconnect is a relative of loop_forever which ends without error if we explicitly disconnect from the broker.

Features

bundled (on by default)

This feature will automatically download and build the mosquitto client library. By default, the master branch is taken. This could be overwritten with the following variables:

• MOSQUITTO_GIT_URL Url of the git repository; by default https://github.com/eclipse/mosquitto.git
• MOSQUITTO_GIT_HASH Git hash to checkout for the build; by default none

Cross compilation

The library could be cross-compiled. The following env parameters have to be set for that:

• MOSQUITTO_CROSS_COMPILER default none, e.g. arm-linux-gnueabihf-
• MOSQUITTO_CC default gcc