implementing decoder interface

Author: andreagilardoni

src/cbor/CborDecoder.cpp

@@ -0,0 +1,94 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#include "CborDecoder.h"
+
+Decoder::Status CBORMessageDecoderSingleton::decode(Message* msg, const uint8_t* const buf, size_t &len) { // TODO do we need to propagate the maximum length?
+  // prepare cbor structure
+  CborValue iter;
+  CborTag tag;
+  CborParser parser;
+
+  if (cbor_parser_init(buf, len, 0, &parser, &iter) != CborNoError) {
+    return Decoder::Status::Error;
+  }
+
+  if (iter.type != CborTagType) {
+    return Decoder::Status::Error;
+  }
+
+  if (cbor_value_get_tag(&iter, &tag) != CborNoError) {
+    return Decoder::Status::Error;
+  }
+
+  if (cbor_value_advance(&iter) != CborNoError) {
+    return Decoder::Status::Error;
+  }
+
+  auto decoder_it = decoders.begin();
+
+  for(; decoder_it != decoders.end(); decoder_it++) {
+    if(decoder_it->first == tag) {
+      break;
+    }
+  }
+
+  // check if message.id exists on the decoders list or return error
+  if(decoder_it == decoders.end()) {
+    return Decoder::Status::Error;
+  }
+
+  // encode the message
+  if(decoder_it->second->_decode(&iter, msg) == Decoder::Status::Error) {
+    return Decoder::Status::Error;
+  }
+
+  return Decoder::Status::Complete;
+}
+
+CBORMessageDecoderSingleton& CBORMessageDecoderSingleton::getInstance() {
+  static CBORMessageDecoderSingleton singleton;
+
+  return singleton;
+}
+
+void CBORMessageDecoderSingleton::append(CBORTag tag, CBORMessageDecoderInterface* decoder) {
+    auto decoder_it = decoders.begin();
+
+  for(; decoder_it != decoders.end(); decoder_it++) {
+    if(decoder_it->first == tag) {
+      return;
+    }
+  }
+
+  decoders.push_back(
+    std::make_pair(tag, decoder)
+  );
+}
+
+CBORMessageDecoderInterface::CBORMessageDecoderInterface(const CBORTag tag, const MessageId id)
+: tag(tag), id(id) {
+  // call singleton/global variable and insert this decoder
+  CBORMessageDecoderSingleton::getInstance().append(tag, this);
+}
+
+Decoder::Status CBORMessageDecoderInterface::_decode(CborValue* iter, Message *msg) {
+  CborValue array_iter;
+  msg->id = this->id;
+
+  if (cbor_value_get_type(iter) != CborArrayType) {
+    return Decoder::Status::Error;
+  }
+
+  if (cbor_value_enter_container(iter, &array_iter) != CborNoError) {
+    return Decoder::Status::Error;
+  }
+
+  return decode(&array_iter, msg);
+}

src/cbor/CborDecoder.h

@@ -0,0 +1,133 @@
+/*
+    This file is part of the Arduino_CloudUtils library.
+
+    Copyright (c) 2024 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+*/
+#pragma once
+
+#include <vector>
+#include "../interfaces/Decoder.h"
+#include "CBOR.h"
+#include "../interfaces/message.h"
+#include "./tinycbor/cbor-lib.h"
+
+// forward declaration
+class CBORMessageDecoderSingleton;
+
+/*
+ * This library collects the interfaces used to decode Messages. Messages are C structs
+ * that are identified by a uint32 id after which they can contain anything.
+ * The objective of this library is to be modular and extensible in other libraries.
+ *
+ * In order to do so one have to extend the class `CBORMessageDecoderInterface`,
+ * provide the associated CBORTag and MessageId and provide a way to decode the message
+ * specific data. MessageId must be univocal across all DecoderInterfaces instantiated.
+ * The class implemented must be instantiated somewhere (using extern may be helpful)
+ * and that is enough to have it included in the decode process.
+ *
+ * In order to decode a message one can instantiate `CBORMessageDecoder` and
+ * call the decode function.
+ */
+
+/**
+ * CBORMessageDecoderInterface class is an abstract class one has to implement
+ * in order to provide the instructions needed to decode a buffer contasining
+ * a message specific data.
+ */
+class CBORMessageDecoderInterface {
+public:
+
+  /**
+   * Constructor that initializes the CBORMessageDecoderInterface by providing the associated
+   * CBORTag and MessageId. The constructor also appends the object into CBORMessageDecoderSingleton
+   * allowing it to be used in CBORMessageDecoderSingleton::decode
+   *
+   * @param tag the cbor tag the message is associated with
+   * @param id  the message id the message is associated with
+   */
+  CBORMessageDecoderInterface(const CBORTag tag, const MessageId id);
+  virtual ~CBORMessageDecoderInterface() {}
+
+protected:
+
+  /**
+   * Abstract decode function one must implement to decode the Message meaningful
+   * information present into the provided buffer
+   *
+   * @param iter tinycbor iterator to the buffer provided to CBORMessageDecoderSingleton::decode
+   * @param msg  The message to which data must be applied to. Casting may be needed
+   */
+  virtual Decoder::Status decode(CborValue* iter, Message *msg) = 0;
+
+private:
+  const CBORTag tag;
+  const MessageId id;
+
+  friend CBORMessageDecoderSingleton;
+
+  /**
+   * Decode wrapper function that opens the cbor array and calls the abstract decode function
+   *
+   * @param iter tinycbor iterator to the buffer provided to CBORMessageDecoderSingleton::decode
+   * @param msg  The message to which data must be applied to. Casting may be needed
+   */
+  Decoder::Status _decode(CborValue* iter, Message *msg);
+};
+
+/**
+ * This class is a singleton. It collects CBORMessageDecoderInterfaces implementations to decode
+ * all possible CBOR encoded messages
+ */
+class CBORMessageDecoderSingleton: public Decoder {
+public:
+  /**
+   * Get the singleton instance
+   */
+  static CBORMessageDecoderSingleton& getInstance();
+
+  /**
+   * Add a new decoder to the singleton instance associating it to the provided cbor tag
+   *
+   * @param tag     the tag to which we associate the decoder
+   * @param decoder the instance of decoder to append
+   */
+  void append(CBORTag tag, CBORMessageDecoderInterface* decoder);
+
+  /**
+   * Decode a buffer and put the contents into a message. The message should be big enough
+   * to accommodate the content of the buffer.
+   *
+   * @param[out] msg    A struct that embeds struct Message onto which the content of buf is copied
+   * @param[in] buf     The input buffer containing a cbor encoded message
+   * @param[in out] len The length of the buffer
+   */
+  Decoder::Status decode(Message* msg, const uint8_t* const buf, size_t &len);
+private:
+  CBORMessageDecoderSingleton() {}
+
+  std::vector<std::pair<CBORTag, CBORMessageDecoderInterface*>> decoders;
+};
+
+/**
+ * In order to decode a message one can instantiate `CBORMessageDecoder` and
+ * call the decode function. In the future this class will contain decode session related
+ * information, in order to allow streaming decoding
+ */
+class CBORMessageDecoder: public Decoder {
+public:
+  /**
+   * Decode a buffer and put the contents into a message. The message should be big enough
+   * to accommodate the content of the buffer.
+   *
+   * @param[out] msg    A struct that embeds struct Message onto which the content of buf is copied
+   * @param[in] buf     The input buffer containing a cbor encoded message
+   * @param[in out] len The length of the buffer
+   */
+  inline Decoder::Status decode(Message* msg, const uint8_t* const buf, size_t &len) {
+    return CBORMessageDecoderSingleton::getInstance().decode(msg, buf, len);
+  }
+};