# 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:
```rust
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](https://github.com/eclipse/mosquitto.git)
* `MOSQUITTO_GIT_HASH` Git hash to checkout for the build; by default none