added Mqtt client Interface definition

Author: andreagilardoni

src/MqttInterface.h

@@ -0,0 +1,137 @@
+#pragma once
+#include <functional>
+#include <memory>
+
+// https://github.com/arduino-libraries/ArduinoMqttClient/
+
+// The Idea for this section of the library is to allow the usage of different implementation for Mqtt Clients
+// while preserving the possibility of having an Arduino standardized interface for Mqtt protocol
+// One should implement MqttClientInterface and provide a way to instantiate the implementation
+
+// namespace arduino { // namespace net { namespace mqtt {
+
+class IStream {
+public:
+    virtual ~IStream() = default;
+
+    virtual int available() = 0;
+    virtual int read() = 0;
+    virtual int peek() = 0;
+    virtual size_t readBytes(uint8_t *buffer, size_t length) = 0; // read chars from stream into buffer
+};
+
+class OStream {
+public:
+    virtual ~OStream() = default;
+
+    virtual size_t write(uint8_t) = 0;
+    virtual size_t write(const uint8_t *buffer, size_t size) = 0;
+    virtual int availableForWrite() = 0;
+};
+
+using Topic = const char* const;
+
+// for incoming published messages
+using MqttReceiveCallback = std::function<void(Topic, IStream&)>;
+
+// TODO MQTT 5.0 stuff
+
+// TODO define callback for mqtt events. one should be the default, but the user can always change it
+
+typedef int error_t; // TODO move this to be generally available
+
+// copied from zephyr
+enum mqtt_conn_return_code {
+	/** Connection accepted. */
+	MQTT_CONNECTION_ACCEPTED                = 0x00,
+
+	/** The Server does not support the level of the MQTT protocol
+	 * requested by the Client.
+	 */
+	MQTT_UNACCEPTABLE_PROTOCOL_VERSION      = 0x01,
+
+	/** The Client identifier is correct UTF-8 but not allowed by the
+	 *  Server.
+	 */
+	MQTT_IDENTIFIER_REJECTED                = 0x02,
+
+	/** The Network Connection has been made but the MQTT service is
+	 *  unavailable.
+	 */
+	MQTT_SERVER_UNAVAILABLE                 = 0x03,
+
+	/** The data in the user name or password is malformed. */
+	MQTT_BAD_USER_NAME_OR_PASSWORD          = 0x04,
+
+	/** The Client is not authorized to connect. */
+	MQTT_NOT_AUTHORIZED                     = 0x05
+};
+
+enum MqttQos: uint8_t {
+    MqttQos0 = 0, // At Most once
+    MqttQos1 = 1, // At least once
+    MqttQos2 = 2, // Exactly once
+};
+
+typedef uint8_t MqttPublishFlag;
+enum class MqttPublishFlags: MqttPublishFlag {
+    None            = 0;
+    RetainEnabled   = 1,
+    DupEnabled      = 2,
+};
+
+// TODO define mqtt version
+
+constexpr MqttQos QosDefault = MqttQos0;
+// constexpr size_t MqttClientIdMaxLength = 256;
+constexpr size_t MqttClientIdMaxLength = 40;
+
+// TODO it shouldn't be called client, since it is not an arduino client
+class MqttClientInterface {
+public:
+    virtual ~MqttClientInterface() = default;
+
+    virtual error_t connect(IPAddress ip, uint16_t port) = 0;
+    virtual error_t connect(const char *host, uint16_t port) = 0; // TODO should host be string instead of c-string?
+
+    virtual error_t subscribe(Topic t, MqttQos qos = QosDefault) = 0;
+
+    virtual error_t publish(
+        Topic t, uint8_t payload[],
+        size_t size, MqttQos qos = QosDefault,
+        MqttPublishFlag flags = MqttPublishFlags::None) = 0;
+
+    /**
+     * Publish method for publishing messages in "streaming mode", meaning that
+     * they can outsize the available ram. The OStream returned handles the lifecycle of
+     * an mqtt Message, from the opening header to its termaination.
+     * The concrete OStream is defined by the implementation
+     */
+    virtual OStream& publish( // TODO should OStream keep publish error information?
+        Topic t, MqttQos qos = QosDefault,
+        MqttPublishFlag flags = MqttPublishFlags::None) = 0;
+
+    virtual error_t unsubscribe(Topic t) = 0;
+    virtual void poll() = 0;
+    virtual error_t ping() = 0;
+
+    virtual void setReceiveCallback(MqttReceiveCallback cbk) = 0;
+
+    // nullptr means generate it randomly
+    virtual void setId(const char* client_id = nullptr) = 0;
+
+    // password may be null, if username is null password won't be used
+    virtual void setAuth(const char* username, const char* password=nullptr) = 0;
+
+    virtual void setWill(
+        Topic willTopic, const uint8_t* will_message,
+        size_t will_size, MqttQos qos=QosDefault,
+        MqttPublishFlag flags = MqttPublishFlags::None) = 0;
+
+    virtual void setClient(Client*) = 0;
+
+    // may cause errors since one can easily pass a context dependent object
+    // virtual void setClient(Client&) = 0;
+    // Could this be a better solution?
+    // virtual void setClient(Client&&) = 0;
+};