Linux Notes

Quick Start

Library Open / Close

Before using any functions of Perfect Mosquitto, please initialize the function set by calling Mosquitto.OpenLibrary(). Also, Mosquitto.CloseLibrary() is highly recommended once program quitted.

Note Both operations are not thread safe, so please perform the operation prior to any threads.

Initialize a Mosquitto Client

Mosquitto instance can be constructed by calling with or without any parameters. The simplest form can be:

let m = Mosquitto()

Which means assigning a random client id to this new instance, while all messages and subscriptions will be cleared once disconnected.

However, you can also assign it with a customized client id with instruction of keeping all messages and subscription by this specific name. This is useful for resuming work in case of connection loss.

let mosquitto = Mosquitto(id: "myInstanceId", cleanSession: false)

Connect to a Message Broker

A message broker is a server that implements MQTT protocol and serves all clients in terms of messaging - receiving messages from producer and dispatching them to message subscribers.

Although connection to a message broker can be asynchronous, keeping alive or binding to a specific network address, api connect() can be as express as demo below - only a host name and a port (usually 1883) are required:

try moosquitto.connect(host: "mybroker.com", port: 1883)

Although the instance can disconnect() from a broker automatically when no longer uses the object, it is recommended to call this function explicitly for a better practice. Besides, a reconnect() function is available for the same instance.

Threading Model

Start / Stop

Perfect Mosquitto is flexible in dealing with threads. Clients can call start() to run the mosquitto thread in background, which will automatically execute message publishing / receiving without any extra operations in the main thread, i.e., the thread will do the actual sending after calling publish() and activate callbacks for incoming messages. If no longer running, you can also stop the service thread at any time by calling stop()

// start the messaging thread as a background service, it will not block the main thread and will return immediately.
try mosquitto.start()
// do your other work in the main thread, such as publishing etc., and the messages received will go to the callbacks
// stop the background messaging service if no longer need.
try mosquitto.stop()

Wait for Event

Or, alternatively, you can process events in the main thread, by calling wait() method frequently in a message polling style:

// wait a minimal while for events.
// In this specific moment, mosquitto will perform actual message sending,
// and pull messages from broker / run call backs.
try mosquitto.wait(0)

The only parameter of wait() is the timeout value for message polling in milliseconds. Zero represents the minimal period of the system wait and negative value will be treated the same as 1000 (1 second).

⚠️ NOTE ⚠️ DO NOT MIX start()/stop() with wait()

Publish a Message

Once connected to a broker, you can send messages at any time you want:

As demo above, firstly setup an empty message structure, then assign an message id (integer), a topic for this message and the message content; Then call publish() method to send it to the broker with a returned message id.