RDMCommand.h

Go to the documentation of this file.

/*
 * 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
 *
 * RDMCommand.h
 * All the classes that represent RDM commands.
 * Copyright (C) 2005 Simon Newton
 */


#ifndef INCLUDE_OLA_RDM_RDMCOMMAND_H_
#define INCLUDE_OLA_RDM_RDMCOMMAND_H_

#include <stdint.h>
#include <ola/base/Macro.h>
#include <ola/io/ByteString.h>
#include <ola/io/OutputStream.h>
#include <ola/rdm/CommandPrinter.h>
#include <ola/rdm/RDMEnums.h>
#include <ola/rdm/RDMPacket.h>
#include <ola/rdm/RDMResponseCodes.h>
#include <ola/rdm/UID.h>
#include <sstream>
#include <string>

namespace ola {
namespace rdm {

class RDMCommand {
 public:
  // TODO(simon): remove this in favor of the new one in RDMEnums.h
  typedef enum {
    DISCOVER_COMMAND = 0x10, 
    DISCOVER_COMMAND_RESPONSE = 0x11, 
    GET_COMMAND = 0x20, 
    GET_COMMAND_RESPONSE = 0x21, 
    SET_COMMAND = 0x30, 
    SET_COMMAND_RESPONSE = 0x31, 
    INVALID_COMMAND = 0xff, 
  } RDMCommandClass;

  virtual ~RDMCommand();

  std::string ToString() const;

  friend std::ostream& operator<<(std::ostream &out,
                                  const RDMCommand &command) {
    return out << command.ToString();
  }

  virtual uint8_t SubStartCode() const { return SUB_START_CODE; }

  virtual uint8_t MessageLength() const;

  const UID& SourceUID() const { return m_source; }

  const UID& DestinationUID() const { return m_destination; }

  uint8_t TransactionNumber() const { return m_transaction_number; }

  uint8_t PortIdResponseType() const { return m_port_id; }

  uint8_t MessageCount() const { return m_message_count; }

  uint16_t SubDevice() const { return m_sub_device; }

  virtual RDMCommandClass CommandClass() const = 0;

  uint16_t ParamId() const { return m_param_id; }

  unsigned int ParamDataSize() const { return m_data_length; }

  const uint8_t *ParamData() const { return m_data; }

  virtual uint16_t Checksum(uint16_t checksum) const { return checksum; }

  virtual void Print(CommandPrinter *printer,
                     bool summarize,
                     bool unpack_param_data) const {
    printer->Print(this, summarize, unpack_param_data);
  }

  bool operator==(const RDMCommand &other) const;

  static const uint8_t START_CODE = ola::rdm::START_CODE;

  static RDMCommand *Inflate(const uint8_t *data, unsigned int length);

 protected:
  uint8_t m_port_id;
  UID m_source;
  UID m_destination;
  uint8_t m_transaction_number;

  RDMCommand(const UID &source,
             const UID &destination,
             uint8_t transaction_number,
             uint8_t port_id,
             uint8_t message_count,
             uint16_t sub_device,
             uint16_t param_id,
             const uint8_t *data,
             unsigned int length);

  void SetParamData(const uint8_t *data, unsigned int length);

  static RDMStatusCode VerifyData(const uint8_t *data,
                                  size_t length,
                                  RDMCommandHeader *command_message);

  static RDMCommandClass ConvertCommandClass(uint8_t command_type);

 private:
  uint8_t m_message_count;
  uint16_t m_sub_device;
  uint16_t m_param_id;
  uint8_t *m_data;
  unsigned int m_data_length;

  static uint16_t CalculateChecksum(const uint8_t *data,
                                    unsigned int packet_length);

  DISALLOW_COPY_AND_ASSIGN(RDMCommand);
};


class RDMRequest: public RDMCommand {
 public:
  struct OverrideOptions {
   public:
    OverrideOptions()
      : has_message_length(false),
        has_checksum(false),
        sub_start_code(SUB_START_CODE),
        message_length(0),
        message_count(0),
        checksum(0) {
    }

    void SetMessageLength(uint8_t message_length_arg) {
      has_message_length = true;
      message_length = message_length_arg;
    }

    void SetChecksum(uint16_t checksum_arg) {
      has_checksum = true;
      checksum = checksum_arg;
    }

    bool has_message_length;
    bool has_checksum;

    uint8_t sub_start_code;
    uint8_t message_length;
    uint8_t message_count;
    uint16_t checksum;
  };

  RDMRequest(const UID &source,
             const UID &destination,
             uint8_t transaction_number,
             uint8_t port_id,
             uint16_t sub_device,
             RDMCommandClass command_class,
             uint16_t param_id,
             const uint8_t *data,
             unsigned int length,
             const OverrideOptions &options = OverrideOptions());

  RDMCommandClass CommandClass() const { return m_command_class; }

  uint8_t PortId() const { return m_port_id; }

  virtual RDMRequest *Duplicate() const {
    return new RDMRequest(
      SourceUID(),
      DestinationUID(),
      TransactionNumber(),
      PortId(),
      SubDevice(),
      m_command_class,
      ParamId(),
      ParamData(),
      ParamDataSize(),
      m_override_options);
  }

  virtual void Print(CommandPrinter *printer,
                     bool summarize,
                     bool unpack_param_data) const {
    printer->Print(this, summarize, unpack_param_data);
  }

  bool IsDUB() const;

  uint8_t SubStartCode() const;
  uint8_t MessageLength() const;
  uint16_t Checksum(uint16_t checksum) const;

  void SetSourceUID(const UID &source_uid) {
    m_source = source_uid;
  }

  void SetTransactionNumber(uint8_t transaction_number) {
    m_transaction_number = transaction_number;
  }

  void SetPortId(uint8_t port_id) {
    m_port_id = port_id;
  }

  static RDMRequest* InflateFromData(const uint8_t *data,
                                     unsigned int length);

 protected:
  OverrideOptions m_override_options;

 private:
  RDMCommandClass m_command_class;
};


class RDMGetSetRequest: public RDMRequest {
 public:
  RDMGetSetRequest(const UID &source,
                   const UID &destination,
                   uint8_t transaction_number,
                   uint8_t port_id,
                   uint16_t sub_device,
                   RDMCommandClass command_class,
                   uint16_t param_id,
                   const uint8_t *data,
                   unsigned int length,
                   const OverrideOptions &options)
      : RDMRequest(source, destination, transaction_number, port_id,
                   sub_device, command_class, param_id, data, length, options) {
  }
};


template <RDMCommand::RDMCommandClass command_class>
class BaseRDMRequest: public RDMGetSetRequest {
 public:
  BaseRDMRequest(const UID &source,
                 const UID &destination,
                 uint8_t transaction_number,
                 uint8_t port_id,
                 uint16_t sub_device,
                 uint16_t param_id,
                 const uint8_t *data,
                 unsigned int length,
                 const OverrideOptions &options = OverrideOptions())
    : RDMGetSetRequest(source, destination, transaction_number, port_id,
                       sub_device, command_class, param_id, data, length,
                       options) {
  }

  BaseRDMRequest<command_class> *Duplicate() const {
    return new BaseRDMRequest<command_class>(
      SourceUID(),
      DestinationUID(),
      TransactionNumber(),
      PortId(),
      SubDevice(),
      ParamId(),
      ParamData(),
      ParamDataSize(),
      m_override_options);
  }
};

typedef BaseRDMRequest<RDMCommand::GET_COMMAND> RDMGetRequest;
typedef BaseRDMRequest<RDMCommand::SET_COMMAND> RDMSetRequest;


class RDMResponse: public RDMCommand {
 public:
  RDMResponse(const UID &source,
              const UID &destination,
              uint8_t transaction_number,
              uint8_t response_type,
              uint8_t message_count,
              uint16_t sub_device,
              RDMCommand::RDMCommandClass command_class,
              uint16_t param_id,
              const uint8_t *data,
              unsigned int length)
        : RDMCommand(source, destination, transaction_number, response_type,
                     message_count, sub_device, param_id, data, length),
          m_command_class(command_class) {
  }

  virtual void Print(CommandPrinter *printer,
                     bool summarize,
                     bool unpack_param_data) const {
    printer->Print(this, summarize, unpack_param_data);
  }

  RDMResponse *Duplicate() const {
    return new RDMResponse(
      SourceUID(),
      DestinationUID(),
      TransactionNumber(),
      ResponseType(),
      MessageCount(),
      SubDevice(),
      CommandClass(),
      ParamId(),
      ParamData(),
      ParamDataSize());
  }

  uint8_t ResponseType() const { return m_port_id; }

  RDMCommandClass CommandClass() const { return m_command_class; }

  void SetDestinationUID(const UID &destination_uid) {
    m_destination = destination_uid;
  }

  void SetTransactionNumber(uint8_t transaction_number) {
    m_transaction_number = transaction_number;
  }

  static const unsigned int MAX_OVERFLOW_SIZE = 4 << 10;

  static RDMResponse* InflateFromData(const uint8_t *data,
                                      size_t length,
                                      RDMStatusCode *status_code,
                                      const RDMRequest *request = NULL);

  static RDMResponse* InflateFromData(const ola::io::ByteString &input,
                                      RDMStatusCode *status_code,
                                      const RDMRequest *request = NULL) {
    return InflateFromData(input.data(), input.size(), status_code, request);
  }

  static RDMResponse* CombineResponses(const RDMResponse *response1,
                                       const RDMResponse *response2);

 private:
  RDMCommand::RDMCommandClass m_command_class;
};


class RDMGetSetResponse: public RDMResponse {
 public:
    RDMGetSetResponse(const UID &source,
                      const UID &destination,
                      uint8_t transaction_number,
                      uint8_t response_type,
                      uint8_t message_count,
                      uint16_t sub_device,
                      RDMCommand::RDMCommandClass command_class,
                      uint16_t param_id,
                      const uint8_t *data,
                      unsigned int length)
        : RDMResponse(source, destination, transaction_number, response_type,
                      message_count, sub_device, command_class, param_id, data,
                      length) {
    }
};


template <RDMCommand::RDMCommandClass command_class>
class BaseRDMResponse: public RDMGetSetResponse {
 public:
    BaseRDMResponse(const UID &source,
                    const UID &destination,
                    uint8_t transaction_number,
                    uint8_t response_type,
                    uint8_t message_count,
                    uint16_t sub_device,
                    uint16_t param_id,
                    const uint8_t *data,
                    unsigned int length)
        : RDMGetSetResponse(source, destination, transaction_number,
                            response_type, message_count, sub_device,
                            command_class, param_id, data, length) {
    }
};

typedef BaseRDMResponse<RDMCommand::GET_COMMAND_RESPONSE> RDMGetResponse;
typedef BaseRDMResponse<RDMCommand::SET_COMMAND_RESPONSE> RDMSetResponse;

// Helper functions for dealing with RDMCommands
// These are mostly used with the RDM-TRI & dummy plugin

RDMResponse *NackWithReason(const RDMRequest *request,
                            rdm_nack_reason reason,
                            uint8_t outstanding_messages = 0);
RDMResponse *GetResponseFromData(const RDMRequest *request,
                                 const uint8_t *data = NULL,
                                 unsigned int length = 0,
                                 rdm_response_type type = RDM_ACK,
                                 uint8_t outstanding_messages = 0);

RDMResponse *GetResponseWithPid(const RDMRequest *request,
                                uint16_t pid,
                                const uint8_t *data,
                                unsigned int length,
                                uint8_t type = RDM_ACK,
                                uint8_t outstanding_messages = 0);

class RDMDiscoveryRequest: public RDMRequest {
 public:
    RDMDiscoveryRequest(const UID &source,
                        const UID &destination,
                        uint8_t transaction_number,
                        uint8_t port_id,
                        uint16_t sub_device,
                        uint16_t param_id,
                        const uint8_t *data,
                        unsigned int length,
                        const OverrideOptions &options = OverrideOptions())
        : RDMRequest(source,
                     destination,
                     transaction_number,
                     port_id,
                     sub_device,
                     DISCOVER_COMMAND,
                     param_id,
                     data,
                     length,
                     options) {
    }

    uint8_t PortId() const { return m_port_id; }

    virtual void Print(CommandPrinter *printer,
                       bool summarize,
                       bool unpack_param_data) const {
      printer->Print(this, summarize, unpack_param_data);
    }

    static RDMDiscoveryRequest* InflateFromData(const uint8_t *data,
                                                unsigned int length);
};


// Because the number of discovery requests is small (3 type) we provide a
// helper method for each here.
RDMDiscoveryRequest *NewDiscoveryUniqueBranchRequest(
    const UID &source,
    const UID &lower,
    const UID &upper,
    uint8_t transaction_number,
    uint8_t port_id = 1);


RDMDiscoveryRequest *NewMuteRequest(const UID &source,
                                    const UID &destination,
                                    uint8_t transaction_number,
                                    uint8_t port_id = 1);

RDMDiscoveryRequest *NewUnMuteRequest(const UID &source,
                                      const UID &destination,
                                      uint8_t transaction_number,
                                      uint8_t port_id = 1);


class RDMDiscoveryResponse: public RDMResponse {
 public:
    RDMDiscoveryResponse(const UID &source,
                         const UID &destination,
                         uint8_t transaction_number,
                         uint8_t port_id,
                         uint8_t message_count,
                         uint16_t sub_device,
                         uint16_t param_id,
                         const uint8_t *data,
                         unsigned int length)
        : RDMResponse(source,
                      destination,
                      transaction_number,
                      port_id,
                      message_count,
                      sub_device,
                      DISCOVER_COMMAND_RESPONSE,
                      param_id,
                      data,
                      length) {
    }

    virtual void Print(CommandPrinter *printer,
                       bool summarize,
                       bool unpack_param_data) const {
      printer->Print(this, summarize, unpack_param_data);
    }

    static RDMDiscoveryResponse* InflateFromData(const uint8_t *data,
                                                 unsigned int length);
};
}  // namespace rdm
}  // namespace ola
#endif  // INCLUDE_OLA_RDM_RDMCOMMAND_H_