# Eclipse Paho MQTT C++ Client Library
[](https://travis-ci.org/eclipse/paho.mqtt.cpp)
This repository contains the source code for the [Eclipse Paho](http://eclipse.org/paho) MQTT C++ client library on memory-managed operating systems such as Linux/Posix and Windows.
This code builds a library which enables C++11 applications to connect to an [MQTT](http://mqtt.org) broker, publish messages to the broker, and to subscribe to topics and receive published messages.
The library has the following features:
- Support for MQTT v5, v3.1.1, and v 3.1
- TCP, SSL/TLS, and WebSocket transports
- Message persistence
- Automatic reconnect
- Offline buffering
- High availability
- Blocking and non-blocking API's
This code requires the [Paho C library](https://github.com/eclipse/paho.mqtt.c) by Ian Craggs, et al., specifically version 1.3.1 or possibly later.
## Latest News
To keep up with the latest announcements for this project, or to ask questions:
**Twitter:** [@eclipsepaho](https://twitter.com/eclipsepaho) and [@fmpagliughi](https://twitter.com/fmpagliughi)
**EMail:** [Eclipse Paho Mailing List](https://accounts.eclipse.org/mailing-list/paho-dev)
**Mattermost:** [Eclipse Mattermost Paho Channel](https://mattermost.eclipse.org/eclipse/channels/paho)
### New Features in Paho C++ v1.1
- MQTT v5 support:
- **Properties**
- New `property` class acts something like a std::variant to hold a property of any supported type.
- New `properties` class is a collection type to hold all the properties for a single transmitted packet.
- Properties can be added to outbound messages and obtained from received messages.
- Properties can also be obtained from server responses to requests such as from a _connect_ call. These are available in the `token` objects when they complete.
- The client object tracks the desired MQTT version that the app requested and/or is currently connected at. Internally this is now required by the `response_options` the need to distinguish between pre-v5 and post-v5 callback functions.
- MQTT v5 reason codes for requests are available via `token` objects when they complete. They are also available in `exception` objects that are thrown by tokens.
- Support for subscibe options, like no local subscriptions, etc.
- Sample applications were added showing how to do basic Remote Procedure Calls (RPC's) with MQTT v5 using the *RESPONSE_TOPIC* and *CORRELATION_DATA* properties. These are *rpc_math_cli* and *rpc_math_srvr* in the _src/samples_ directory.
- A sample "chat" application was added, showing how to use subscribe options, such as "no local".
- More descriptive error messages (PR #154), integrated into the `mqtt::exception` class. MQTT v5 reason codes are also included in the exceptions when an error occurs.
- Applications can (finally) get server responses from the various ACK packets. These are available through the tokens after they complete, as `connect_response`, `subscribe_response`, and `unsubscribe_response`.
- The `topic` objects can be used to subscribe.
- Applications can register individual callback functions instead of using a `callback` interface object. This allows easy use of lambda functions for callbacks.
- The connect options can take a LWT as a plain message, via `connect_options::set_will_message()`
### _Catch2_ Unit Tests
Unit tests are being converted to use _Catch2_ for the test framework. The legacy unit tests are still using _CppUnit_, compiled into a separate test executable. If everything goes well with _Catch2_, the older unit tests will be ported to _Catch2_ as well.
_Catch2_ can be found here: [Catch2](https://github.com/catchorg/Catch2)
## Contributing
Contributions to this project are gladly welcomed. Before submitting a Pull Request, please keep two things in mind:
- This is an official Eclipse project, so it is required that all contributors sign an [Eclipse Contributor Agreement (ECA)](https://www.eclipse.org/legal/ECA.php)
- Please submit all Pull Requests against the _develop_ branch (not master).
For full details, see [CONTRIBUTING.md](https://github.com/eclipse/paho.mqtt.cpp/blob/master/CONTRIBUTING.md).
## Building from source
*GNU Make and autotools were deprecated and removed in the v1.1 release.*
_CMake_ is a cross-platform build system suitable for Unix and non-Unix platforms such as Microsoft Windows. It is now the only supported build system.
The Paho C++ library requires the Paho C library, v1.3.1 or greater, to be built and installed first. More information below.
CMake allows for options to direct the build. The following are specific to Paho C++:
Variable | Default Value | Description
------------ | ------------- | -------------
PAHO_BUILD_SHARED | TRUE (Linux), FALSE (Win32) | Whether to build the shared library
PAHO_BUILD_STATIC | FALSE (Linux), TRUE (Win32) | Whether to build the static library
PAHO_BUILD_DOCUMENTATION | FALSE | Create and install the HTML based API documentation (requires Doxygen)
PAHO_BUILD_SAMPLES | FALSE | Build sample programs
PAHO_BUILD_TESTS | FALSE | Build the unit tests. (This currently requires both _CppUnit_ and _Catch2_)
PAHO_WITH_SSL | TRUE (Linux), FALSE (Win32) | Flag that defines whether to build ssl-enabled binaries too
In addition, the C++ build might commonly use `CMAKE_PREFIX_PATH` to help the build system find the location of the Paho C library.
### Unix and Linux
On *nix systems CMake creates Makefiles.
The build process currently supports a number of Unix and Linux flavors. The build process requires the following tools:
* CMake v3.5 or newer
* GCC v4.8 or newer or Clang v3.9 or newer
* GNU Make
On Debian based systems this would mean that the following packages have to be installed:
```
$ sudo apt-get install build-essential gcc make cmake cmake-gui cmake-curses-gui
```
If you will be using secure sockets (and you probably should):
```
$ sudo apt-get install libssl-dev
```
Building the documentation requires doxygen and optionally graphviz to be installed:
```
$ sudo apt-get install doxygen graphviz
```
Unite tests are currently being built using both _CppUnit_ and _Catch2_. The _CppUnit_ tests are being deprecated and replaced with _Catch2_ equivalents. In the meantime, however, both systems are required to build the tests.
```
$ sudo apt-get install libcppunit-dev
```
_Catch2_ can be found here: [Catch2](https://github.com/catchorg/Catch2)
Before building the C++ library, first, build and install the Paho C library:
```
$ git clone https://github.com/eclipse/paho.mqtt.c.git
$ cd paho.mqtt.c
$ git checkout v1.3.1
$ cmake -Bbuild -H. -DPAHO_WITH_SSL=ON -DPAHO_ENABLE_TESTING=OFF
$ sudo cmake --build build/ --target install
$ sudo ldconfig
```
This builds with SSL/TLS enabled. If that is not desired, omit the `-DPAHO_WITH_SSL=ON`.
If you installed the C library on a non-standard path, you might want to pass it as value to the `CMAKE_PREFIX_PATH` option.
Using these variables CMake can be used to generate your Makefiles. The out-of-source build is the default on CMake. Therefore it is recommended to invoke all build commands inside your chosen build directory.
An example build session might look like this:
```
$ git clone https://github.com/eclipse/paho.mqtt.cpp
$ cd paho.mqtt.cpp
$ cmake -Bbuild -H. -DPAHO_BUILD_DOCUMENTATION=TRUE -DPAHO_BUILD_SAMPLES=TRUE
$ sudo cmake --build build/ --target install
$ sudo ldconfig
```
If you did not install Paho C library to a default system location or you want to build against a different version, use the `CMAKE_PREFIX_PATH` to specify its install location:
```
$ cmake -Bbuild -H. -DPAHO_BUILD_DOCUMENTATION=TRUE -DPAHO_BUILD_SAMPLES=TRUE \
-DCMAKE_PREFIX_PATH=../../pa
