Descriptor.h

/*
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 *
 * Descriptor.h
 * Holds the metadata (schema) for a Message.
 * Copyright (C) 2011 Simon Newton
 */

#ifndef INCLUDE_OLA_MESSAGING_DESCRIPTOR_H_
#define INCLUDE_OLA_MESSAGING_DESCRIPTOR_H_

#include <ola/messaging/DescriptorVisitor.h>
#include <ola/network/IPV4Address.h>
#include <ola/network/MACAddress.h>
#include <ola/rdm/UID.h>
#include <map>
#include <string>
#include <vector>
#include <utility>

namespace ola {
namespace messaging {

class FieldDescriptorVisitor;

class FieldDescriptorInterface {
 public:
    virtual ~FieldDescriptorInterface() {}

    // Returns the name of this field
    virtual const std::string& Name() const = 0;

    // Call back into a FieldDescriptorVisitor
    virtual void Accept(FieldDescriptorVisitor *visitor) const = 0;

    // Returns true if the size of this field is constant
    virtual bool FixedSize() const = 0;

    // True if there is some bound on the field's size.
    virtual bool LimitedSize() const = 0;

    // This is the max size in bytes of the field. This is only valid if
    // LimitedSize() is  true, otherwise it returns 0.
    virtual unsigned int MaxSize() const = 0;
};


class FieldDescriptor: public FieldDescriptorInterface {
 public:
    explicit FieldDescriptor(const std::string &name)
        : m_name(name) {
    }
    virtual ~FieldDescriptor() {}

    // Returns the name of this field
    const std::string& Name() const { return m_name; }

 private:
    std::string m_name;
};


class BoolFieldDescriptor: public FieldDescriptor {
 public:
    explicit BoolFieldDescriptor(const std::string &name)
        : FieldDescriptor(name) {
    }

    bool FixedSize() const { return true; }
    bool LimitedSize() const { return true; }
    unsigned int MaxSize() const { return 1; }

    void Accept(FieldDescriptorVisitor *visitor) const {
      visitor->Visit(this);
    }
};


class IPV4FieldDescriptor: public FieldDescriptor {
 public:
    explicit IPV4FieldDescriptor(const std::string &name)
        : FieldDescriptor(name) {
    }

    bool FixedSize() const { return true; }
    bool LimitedSize() const { return true; }
    unsigned int MaxSize() const { return ola::network::IPV4Address::LENGTH; }

    void Accept(FieldDescriptorVisitor *visitor) const {
      visitor->Visit(this);
    }
};


class MACFieldDescriptor: public FieldDescriptor {
 public:
    explicit MACFieldDescriptor(const std::string &name)
        : FieldDescriptor(name) {
    }

    bool FixedSize() const { return true; }
    bool LimitedSize() const { return true; }
    unsigned int MaxSize() const { return ola::network::MACAddress::LENGTH; }

    void Accept(FieldDescriptorVisitor *visitor) const {
      visitor->Visit(this);
    }
};


class UIDFieldDescriptor: public FieldDescriptor {
 public:
    explicit UIDFieldDescriptor(const std::string &name)
        : FieldDescriptor(name) {
    }

    bool FixedSize() const { return true; }
    bool LimitedSize() const { return true; }
    unsigned int MaxSize() const { return ola::rdm::UID::LENGTH; }

    void Accept(FieldDescriptorVisitor *visitor) const {
      visitor->Visit(this);
    }
};


class StringFieldDescriptor: public FieldDescriptor {
 public:
    StringFieldDescriptor(const std::string &name,
                          uint8_t min_size,
                          uint8_t max_size)
        : FieldDescriptor(name),
          m_min_size(min_size),
          m_max_size(max_size) {
    }

    bool FixedSize() const { return m_min_size == m_max_size; }
    bool LimitedSize() const { return true; }
    unsigned int MinSize() const { return m_min_size; }
    unsigned int MaxSize() const { return m_max_size; }

    void Accept(FieldDescriptorVisitor *visitor) const {
      visitor->Visit(this);
    }

 private:
    uint8_t m_min_size, m_max_size;
};


template <typename type>
class IntegerFieldDescriptor: public FieldDescriptor {
 public:
    typedef std::pair<type, type> Interval;
    typedef std::vector<std::pair<type, type> > IntervalVector;
    typedef std::map<std::string, type> LabeledValues;

    IntegerFieldDescriptor(const std::string &name,
                           bool little_endian = false,
                           int8_t multiplier = 0)
        : FieldDescriptor(name),
          m_little_endian(little_endian),
          m_multiplier(multiplier) {
    }

    IntegerFieldDescriptor(const std::string &name,
                           const IntervalVector &intervals,
                           const LabeledValues &labels,
                           bool little_endian = false,
                           int8_t multiplier = 0)
        : FieldDescriptor(name),
          m_little_endian(little_endian),
          m_multiplier(multiplier),
          m_intervals(intervals),
          m_labels(labels) {
    }

    bool FixedSize() const { return true; }
    bool LimitedSize() const { return true; }
    unsigned int MaxSize() const { return sizeof(type); }
    int8_t Multiplier() const { return m_multiplier; }
    bool IsLittleEndian() const { return m_little_endian; }

    const IntervalVector &Intervals() const { return m_intervals; }

    bool IsValid(type value) const {
      if (m_intervals.empty())
        return true;

      typename IntervalVector::const_iterator iter = m_intervals.begin();
      for (; iter != m_intervals.end(); ++iter) {
        if (value >= iter->first && value <= iter->second)
          return true;
      }
      return false;
    }

    const LabeledValues &Labels() const { return m_labels; }

    bool LookupLabel(const std::string &label, type *value) const {
      typename LabeledValues::const_iterator iter = m_labels.find(label);
      if (iter == m_labels.end())
        return false;
      *value = iter->second;
      return true;
    }

    const std::string LookupValue(type value) const {
      typename LabeledValues::const_iterator iter = m_labels.begin();
      for (; iter != m_labels.end(); ++iter) {
        if (iter->second == value)
          return iter->first;
      }
      return "";
    }

    void Accept(FieldDescriptorVisitor *visitor) const {
      visitor->Visit(this);
    }

 private:
    bool m_little_endian;
    int8_t m_multiplier;
    IntervalVector m_intervals;
    LabeledValues m_labels;
};


typedef IntegerFieldDescriptor<uint8_t> UInt8FieldDescriptor;
typedef IntegerFieldDescriptor<uint16_t> UInt16FieldDescriptor;
typedef IntegerFieldDescriptor<uint32_t> UInt32FieldDescriptor;
typedef IntegerFieldDescriptor<int8_t> Int8FieldDescriptor;
typedef IntegerFieldDescriptor<int16_t> Int16FieldDescriptor;
typedef IntegerFieldDescriptor<int32_t> Int32FieldDescriptor;


class FieldDescriptorGroup: public FieldDescriptor {
 public:
    static const int16_t UNLIMITED_BLOCKS;

    FieldDescriptorGroup(const std::string &name,
                         const std::vector<const FieldDescriptor*> &fields,
                         uint16_t min_blocks,
                         int16_t max_blocks)
      : FieldDescriptor(name),
        m_fields(fields),
        m_min_blocks(min_blocks),
        m_max_blocks(max_blocks),
        m_populated(false),
        m_fixed_size(true),
        m_limited_size(true),
        m_block_size(0),
        m_max_block_size(0) {
    }
    virtual ~FieldDescriptorGroup();

    // This is true iff all fields in a group are of a fixed size and the
    // number of blocks is fixed
    bool FixedSize() const { return FixedBlockSize() && FixedBlockCount(); }

    // True if the number of blocks has some bound, and all fields also have
    // some bound.
    bool LimitedSize() const;

    // This is the max size of the group, which is only valid if LimitedSize()
    // is  true, otherwise it returns 0.
    unsigned int MaxSize() const;

    // Field information
    // the number of fields in this group
    unsigned int FieldCount() const { return m_fields.size(); }
    // True if all the fields in this group are a fixed size. This is then a
    // type 2 group as described above.
    bool FixedBlockSize() const;
    // If this block size is fixed, this returns the size of a single block,
    // otherwise it returns 0;
    unsigned int BlockSize() const;
    // If this block size is bounded, this returns the size of the block.
    unsigned int MaxBlockSize() const;

    // Blocks
    // The minimum number of blocks, usually 0 or 1.
    uint16_t MinBlocks() const { return m_min_blocks; }
    // A max size of UNLIMITED_BLOCKS means no restrictions on the number of
    // blocks
    int16_t MaxBlocks() const { return m_max_blocks; }
    // True if the block count is fixed.
    bool FixedBlockCount() const { return m_min_blocks == m_max_blocks; }


    const class FieldDescriptor *GetField(unsigned int index) const {
      if (index < m_fields.size())
        return m_fields[index];
      return NULL;
    }

    virtual void Accept(FieldDescriptorVisitor *visitor) const;

 protected:
    std::vector<const class FieldDescriptor *> m_fields;

 private:
    uint16_t m_min_blocks;
    int16_t m_max_blocks;
    mutable bool m_populated;
    mutable bool m_fixed_size, m_limited_size;
    mutable unsigned int m_block_size, m_max_block_size;

    void PopulateIfRequired() const;
};


class Descriptor: public FieldDescriptorGroup {
 public:
    Descriptor(const std::string &name,
               const std::vector<const FieldDescriptor*> &fields)
        : FieldDescriptorGroup(name, fields, 1, 1) {}

    void Accept(FieldDescriptorVisitor *visitor) const;
};
}  // namespace messaging
}  // namespace ola

#endif  // INCLUDE_OLA_MESSAGING_DESCRIPTOR_H_