From 324ac934e8b650c876e6056e135cb9838bc50bdc Mon Sep 17 00:00:00 2001
From: Kevin Matz <kevin@company235.com>
Date: Sun, 29 Aug 2021 00:59:36 -0400
Subject: [PATCH] document PDU properties

---
 protocols/sacn/extended.cpp |  9 ++++++++
 protocols/sacn/extended.h   | 44 ++++++++++++++++++++++++++++++++-----
 2 files changed, 48 insertions(+), 5 deletions(-)

diff --git a/protocols/sacn/extended.cpp b/protocols/sacn/extended.cpp
index a662db5..7743642 100644
--- a/protocols/sacn/extended.cpp
+++ b/protocols/sacn/extended.cpp
@@ -36,7 +36,16 @@ namespace EXTENDED {
 void sync_header::iStream(ACN::PDU::Stream stream)
 {
   *stream >> sequence_number;
+  /// > \cite sACN 6.3.3.1 Synchronization Address Usage
+  /// >
+  /// > Synchronization Address of 0 is thus meaningless, and shall not be
+  /// > transmitted. Receivers shall ignore Synchronization Packets containing
+  /// > a Synchronization Address of 0.
   *stream >> sync_address;
+  if (sync_address == 0)
+    stream->setstate(std::ios_base::failbit);
+  if (sync_address >=64000)
+    stream->setstate(std::ios_base::failbit);
   *stream >> reserved;
 }
 
diff --git a/protocols/sacn/extended.h b/protocols/sacn/extended.h
index 84d38d0..8f36df8 100644
--- a/protocols/sacn/extended.h
+++ b/protocols/sacn/extended.h
@@ -39,9 +39,26 @@ namespace sACN::EXTENDED {
 struct sync_header
     : ACN::PDU::pdu_header
 {
-  uint8_t  sequence_number; //!< sequence
-  uint16_t sync_address;    //!< synchronization address
-  uint16_t reserved;        //!< reserved
+  /// @brief \cite sACN 6.3.2 Synchronization Packet: Sequence Number
+  ///
+  /// > 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;
+
+  /// @brief \cite sACN 6.3.3 Synchronization Packet: Synchronization Address
+  ///
+  /// > The Synchronization Address identifies the universe to which this
+  /// > synchronization packet is directed.
+  uint16_t sync_address;
+
+  /// @brief \cite sACN 6.3.4 Synchronization Packet: Reserved
+  ///
+  /// > Octets 47-48 of the E1.31 Synchronization Packet are reserved for
+  /// future use. They shall be transmitted as 0 and ignored by receivers.
+  uint16_t reserved;
 
   size_t streamSize() const override { return 5; }
   void iStream(ACN::PDU::Stream) override;
@@ -55,8 +72,25 @@ struct sync_header
 struct discovery_header
     : ACN::PDU::pdu_header
 {
-  std::string source_name; //!< source descripton
-  uint32_t reserved;       //!< reserved
+  /// @brief \cite sACN 6.4.2 E1.31 Universe Discovery 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;
+
+  /// @brief \cite sACN 6.4.3 E1.31 Universe Discovery Packet: Reserved
+  ///
+  /// Octets 108-111 of the E1.31 Universe Discovery Packet are reserved for
+  /// future use. They shall be transmitted as 0 and ignored by receivers.
+  uint32_t reserved;
 
   size_t streamSize() const override { return 68; }
   void iStream(ACN::PDU::Stream) override;