OpenLCP/protocols/sacn/data.h

/*
  data.h

  Copyright (c) 2020 Kevin Matz (kevin.matz@gmail.com)

  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:

  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
*/
#pragma once

#include "acn/pdu.h"
#include "sacn.h"

/**
 * \cite sACN 1.4 Classes of Data Appropriate for Transmission
 *
 * This standard, E1.31, is intended to define a method to carry DMX512-A
 * \cite DMX style data and metadata over IP Networks. It is designed to carry
 * repetitive control data from one or more sources to one or more receivers.
 * This protocol is intended to be used to control dimmers, other lighting
 * devices, and related non- hazardous effects equipment.
*/
namespace sACN::DATA {

/**
 * @brief The data_options struct
 */
struct data_options
    : ACN::PDU::pdu_stream_object
{
  union {
    uint8_t byte;
    struct {
      uint8_t reserved              : 5;
      bool    force_synchronization : 1; //!< Bit 5 = Force_Synchronization
      bool    stream_terminated     : 1; //!< Bit 6 = Stream_Terminated
      bool    preview_data          : 1; //!< Bit 7 = Preview_Data
    };
  };

  size_t   streamSize() const override { return 1; }
  void     iStream(ACN::PDU::Stream) override;
  void     oStream(ACN::PDU::Stream) const override;
};


/**
 * @brief \cite sACN Table 6-1: E1.31 Data Packet Framing Layer
 */
struct  data_header
    : ACN::PDU::pdu_header
{
  /// \cite sACN 6.2.2 E1.31 Data Packet: Source Name
  ///
  /// A user-assigned name provided by the source of the packet for use in
  /// displaying the identity of a source to a user. There is no mechanism,
  /// other than user configuration, to ensure uniqueness of this name. The
  /// source name shall be null-terminated. If the source component implements
  /// ACN discovery as defined in EPI 19 \cite epi19, then this name shall be
  /// the same as the UACN field specified in EPI 19 \cite epi19. User-Assigned
  /// Component Names, as the title suggests, supply a single name for an entire
  /// component, so this Source Name field will exist for each unique CID, but
  /// may be the same across multiple universes sourced by the same component.
  std::string  source_name;

  /// \cite sACN 6.2.3 E1.31 Data Packet: Priority
  ///
  /// The Priority field is an unsigned, one octet field. The value is used by
  /// receivers in selecting between multiple sources of data for a given
  /// universe number. Sources that do not support variable priority shall
  /// transmit a priority of 100. No priority outside the range of 0 to 200
  /// shall be transmitted on the network. Priority increases with numerical
  /// value, e.g., 200 is a higher priority than 100.
  uint8_t      priority;

  /// \cite sACN 6.2.4 E1.31 Data Packet: Synchronization Address
  ///
  /// The Synchronization Address identifies a universe number to be used for
  /// universe synchronization.
  uint16_t     sync_address;

  /// \cite sACN 6.2.5 E1.31 Data Packet: Sequence Number
  ///
  /// In a routed network environment it is possible for packets to be received
  /// in a different order to the one in which they were sent. The sequence
  /// number allows receivers or diagnostic equipment to detect out of sequence
  /// or lost packets.
  ///
  /// Sources shall maintain a sequence for each universe they
  /// transmit. The sequence number for a universe shall be incremented by one
  /// for every packet sent on that universe. There is no implied relationship
  /// between the sequence number of an E1.31 Synchronization Packet and the
  /// sequence number of an E1.31 Data Packet on that same universe.
  uint8_t      sequence_number;

  /// \cite sACN 6.2.6 E1.31 Data Packet: Options
  ///
  /// This bit-oriented field is used to encode optional flags that control
  /// how the packet is used.
  data_options options;

  /// \cite sACN 6.2.7 E1.31 Data Packet: Universe
  ///
  /// The Universe is a 16-bit field that defines the universe number of the
  /// data carried in the packet. Universe values shall be limited to the range
  /// 1 to 63999.
  uint16_t     universe;

  size_t   streamSize() const override { return 71; }
  void     iStream(ACN::PDU::Stream) override;
  void     oStream(ACN::PDU::Stream) const override;
};


/**
 * @brief \cite sACN 6.2 E1.31 Data Packet Framing Layer
 */
class Pdu
  : public ACN::PDU::Pdu
{
public:
    Pdu();
    void iStream(ACN::PDU::Stream) override;
};

} // SACN::DATA