From 6c20317de37c8e84b093aa88a30cde785caa1c4e Mon Sep 17 00:00:00 2001 From: Kevin Matz Date: Fri, 30 Jul 2021 09:11:32 -0400 Subject: [PATCH] documentation and namespace cleanup --- acn/acn.h | 16 +++--- acn/appliance.h | 3 ++ acn/component.h | 16 ++++-- acn/dmp.h | 51 +++++++++++++----- acn/rlp-tcp.h | 18 +++++-- acn/rlp.h | 1 - acn/sdt-udp.h | 16 ++++-- acn/sdt.h | 141 ++++++++++++++++++++++++++++++++++-------------- sacn/data.h | 14 +++-- sacn/extended.h | 27 ++++++---- 10 files changed, 215 insertions(+), 88 deletions(-) diff --git a/acn/acn.h b/acn/acn.h index 4761757..13bc01c 100644 --- a/acn/acn.h +++ b/acn/acn.h @@ -40,21 +40,21 @@ namespace ACN { // from https://tsp.esta.org/tsp/working_groups/CP/epi16ids.php // as of 1/14/21 -// Session Data Transport Protocol +/// @brief Session Data Transport Protocol static const uint32_t PLASA_SDT = 0x00000001; -// Device Management Protocol +/// @brief Device Management Protocol static const uint32_t PLASA_DMP = 0x00000002; -// Lightweight streaming protocol for transport of DMX512 +/// @brief Lightweight streaming protocol for transport of DMX512 static const uint32_t PLASA_E1_31 = 0x00000004; -// RDMnet +/// @brief RDMnet static const uint32_t PLASA_E1_33 = 0x00000005; -// Empty data used for health checking connections in E1.33 +/// @brief Empty data used for health checking connections in E1.33 static const uint32_t PLASA_NULL = 0x00000006; -// Open Lighting Architecture +/// @brief Open Lighting Architecture static const uint32_t OpenLightingProject_OLA = 0x00000007; -// Extended functionality for sACN +/// @brief Extended functionality for sACN static const uint32_t PLASA_E1_31_EXTENDED = 0x00000008; -// E1.59 Object Transform Protocol (OTP) +/// @brief E1.59 Object Transform Protocol (OTP) const static uint32_t ESTA_OTP = 0x00000009; } // ACN diff --git a/acn/appliance.h b/acn/appliance.h index 096d766..34c16dd 100644 --- a/acn/appliance.h +++ b/acn/appliance.h @@ -48,6 +48,9 @@ namespace ACN { +/** + * @brief The Appliance class + */ class Appliance : public Component { diff --git a/acn/component.h b/acn/component.h index d0c6243..102992a 100644 --- a/acn/component.h +++ b/acn/component.h @@ -28,7 +28,9 @@ namespace ACN { -// 2.1. ACN Components and Component Identifiers (CIDs) +/** + * @brief 2.1. ACN Components and Component Identifiers (CIDs) + */ class Component { public: Component(UUID::uuid cid = UUID::uuid()) @@ -53,12 +55,16 @@ private: // indicate the function of the component in human readable terms for browsing // purposes. -// 3.1. Fixed Component Type Name (FCTN) -// shall be a UTF-8 string that is assigned during manufacture. + /** + * @brief 3.1. Fixed Component Type Name (FCTN) + * shall be a UTF-8 string that is assigned during manufacture. + */ const std::string fctn_; -// 3.2. User Assigned Component Name (UACN) -// shall be a UTF-8 string that may be assigned by the user. + /** + * @brief 3.2. User Assigned Component Name (UACN) + * shall be a UTF-8 string that may be assigned by the user. + */ std::string uacn_; }; diff --git a/acn/dmp.h b/acn/dmp.h index db8b4e0..ac315ec 100644 --- a/acn/dmp.h +++ b/acn/dmp.h @@ -32,13 +32,9 @@ namespace ACN { namespace DMP { -using std::uint8_t; -using std::uint32_t; -using std::vector; -using std::pair; -using PDU::Block; - -// 5.1.4 Address and Data Types +/** + * @brief 5.1.4 Address and Data Types + */ enum data_type { SINGLE = 0b00, // 0 RANGE = 0b01, // 1 @@ -46,6 +42,10 @@ enum data_type { SERIES = 0b11 // 3 }; + +/** + * @brief The address_length enum + */ enum address_length { ONE = 0b00, // 0 TWO = 0b01, // 1 @@ -53,6 +53,10 @@ enum address_length { ZERO = 0b11 // 3 (reserved) }; + +/** + * @brief The address_type struct + */ struct address_type : PDU::pdu_header { bool z_reserved : 1; // Z bool relative : 1; // R @@ -64,7 +68,10 @@ struct address_type : PDU::pdu_header { void oStream(PDU::Stream) const override; }; -// 5.1.5 + +/** + * @brief 5.1.5 The range struct + */ struct range { uint32_t address = 0; uint32_t incriment = 0; @@ -74,15 +81,27 @@ private: uint32_t read(PDU::Stream, const address_length); }; -typedef pair> set_property; + +/** + * @brief set_property + */ +typedef std::pair> set_property; + + +/** + * @brief The dmp_set_data struct + */ struct dmp_set_data : PDU::pdu_data { - vector properties; + std::vector properties; size_t streamSize() const override; void iStream(PDU::Stream) override {}; void oStream(PDU::Stream) const override {}; }; -// 7 Response Messages + +/** + * @brief 7 Response Messages + */ enum failure_reason { NONSPECIFIC = 1, // Non-specific or non-DMP reason. NOT_PROPERTY = 2, // The address does not correspond to a property. @@ -95,7 +114,10 @@ enum failure_reason { UNAVAILABLE = 13 // The property’s value is not available due to restrictions imposed by device specific functionality (e.g., access permission mechanisms). }; -// 13.1 Protocol Codes + +/** + * @brief 13.1 Protocol Codes + */ static const uint32_t DMP_PROTOCOL_ID = 2; // PDU protocol value // 13.2 Message Codes @@ -111,13 +133,16 @@ static const uint8_t SUBSCRIBE_ACCEPT = 12; static const uint8_t SUBSCRIBE_REJECT = 13; static const uint8_t SYNC_EVENT = 17; + +/** + * @brief The DMP::Pdu class + */ class Pdu : public PDU::Pdu { public: Pdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; private: void readSetData(); }; diff --git a/acn/rlp-tcp.h b/acn/rlp-tcp.h index d265138..1baee68 100644 --- a/acn/rlp-tcp.h +++ b/acn/rlp-tcp.h @@ -33,7 +33,9 @@ namespace ACN { namespace RLP { namespace TCP { -// 3. Frame Preamble Format +/** + * @brief 3. Frame Preamble Format + */ struct preamble_t { uint8_t acn_id[12]; // 3.1 Packet Identifier uint32_t length; // 3.2 PDU Block Size @@ -41,12 +43,18 @@ struct preamble_t { operator bool(); }; -// 3.1 Packet Identifier -// The ACN Packet Identifier shall be the text string -// “ASC-E1.17\0\0\0” encoded in [ASCII]. + +/** + * @brief 3.1 Packet Identifier + * The ACN Packet Identifier shall be the text string “ASC-E1.17\0\0\0” + * encoded in [ASCII]. + */ static constexpr uint8_t ACN_PACKET_IDENTIFIER[] = { 0x41, 0x53, 0x43, 0x2d, 0x45, 0x31, 0x2e, 0x31, 0x37, 0x00, 0x00, 0x00 }; -// 3.2 PDU Block Size + +/** + * @brief 3.2 PDU Block Size INDEFINITE + */ static const uint32_t INDEFINITE = 0xffffffff; diff --git a/acn/rlp.h b/acn/rlp.h index 56c066b..00f0c01 100644 --- a/acn/rlp.h +++ b/acn/rlp.h @@ -57,7 +57,6 @@ class Pdu public: Pdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; }; } // RLP diff --git a/acn/sdt-udp.h b/acn/sdt-udp.h index bbd97f0..5143dfe 100644 --- a/acn/sdt-udp.h +++ b/acn/sdt-udp.h @@ -45,14 +45,20 @@ static const uint8_t NAK_MAX_TIME = 10 * NAK_HOLDOFF_INTERVAL; static const uint8_t NAK_BLANKTIME = 3 * NAK_HOLDOFF_INTERVAL; static const uint16_t SDT_MULTICAST_PORT = 5568; // IANA registered “sdt” -// defined in SDT, but needed here without including that header + +/** + * @brief The ip_addr_spec_t enum + * defined in SDT, but needed here without including that header + */ enum ip_addr_spec_t { - SDT_ADDR_NULL = 0, // Address is not present (0 octets). - SDT_ADDR_IPV4 = 1, // Address specified is in IP v4 format - SDT_ADDR_IPV6 = 2 // Address specified is in IP v6 format + SDT_ADDR_NULL = 0, //!< Address is not present (0 octets). + SDT_ADDR_IPV4 = 1, //!< Address specified is in IP v4 format + SDT_ADDR_IPV6 = 2 //!< Address specified is in IP v6 format }; -// 3 Address Specification +/** + * @brief 3 Address Specification + */ struct address_t { uint8_t type = SDT_ADDR_NULL; uint16_t port = SDT_MULTICAST_PORT; diff --git a/acn/sdt.h b/acn/sdt.h index 2cd8b96..cb04295 100644 --- a/acn/sdt.h +++ b/acn/sdt.h @@ -36,7 +36,9 @@ namespace ACN { namespace SDT { -// 3.1 Session Identity +/** + * @brief 3.1 Session Identity + */ struct SessionId { UUID::uuid cid; // the component ID (CID) of the session leader uint16_t number; // the session number the leader has assigned @@ -44,18 +46,25 @@ struct SessionId { bool operator== (const SessionId &) const; }; -// 3.3 Sequenced Channels -// Sequenced channels transport three categories of traffic: + +/** + * @brief 3.3 Sequenced Channels + * Sequenced channels transport three categories of traffic: + */ enum Direction { internal, // SDT internal traffic downstream, // Session downstream traffic upstream // Session upstream traffic }; + // 3.5.1.1 Member Identifiers using MID = uint16_t; -// 4.4.1.2 Channel Parameter Block + +/** + * @brief 4.4.1.2 Channel Parameter Block + */ struct params_t { uint8_t Expiry; // number of seconds without traffic before leaving struct { @@ -68,7 +77,10 @@ struct params_t { void iStream(PDU::Stream); }; -// 4.4.1 Join + +/** + * @brief 4.4.1 Join + */ struct join_data_t : PDU::pdu_data { MID mid; uint16_t number; @@ -83,7 +95,10 @@ struct join_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.4.2 Join Accept + +/** + * @brief 4.4.2 Join Accept + */ struct join_accept_data_t : PDU::pdu_data { UUID::uuid leader; uint16_t number; @@ -95,8 +110,10 @@ struct join_accept_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.4.3 Join Refuse -// 4.4.4 Leaving + +/** + * @brief 4.4.3 Join Refuse & 4.4.4 Leaving + */ struct join_refuse_data_t : PDU::pdu_data { UUID::uuid leader; uint16_t number; @@ -108,7 +125,10 @@ struct join_refuse_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.4.5 NAK + +/** + * @brief 4.4.5 NAK + */ struct nak_data_t : PDU::pdu_data { UUID::uuid leader; uint16_t number; @@ -121,7 +141,10 @@ struct nak_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.4.6 Reliable Wrapper and Unreliable Wrapper + +/** + * @brief 4.4.6 Reliable Wrapper and Unreliable Wrapper + */ struct wrapper_data_t : PDU::pdu_data { uint16_t number; uint32_t sequence; @@ -135,7 +158,10 @@ struct wrapper_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.4.7 SDT Client Block + +/** + * @brief 4.4.7 SDT Client Block + */ struct client_pdu_header_t : PDU::pdu_header { uint32_t protocol; uint16_t association; @@ -144,17 +170,22 @@ struct client_pdu_header_t : PDU::pdu_header { void oStream(PDU::Stream) const override {}; }; -// Client Block PDU + +/** + * @brief The ClientPdu class + */ class ClientPdu : public PDU::Pdu { public: ClientPdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; }; -// 4.4.8 Get Sessions + +/** + * @brief 4.4.8 Get Sessions + */ struct get_sessions_data_t : PDU::pdu_data { UUID::uuid cid; size_t streamSize() const override { return 0; } @@ -163,7 +194,9 @@ struct get_sessions_data_t : PDU::pdu_data { }; -// 4.4.9.1 Channel Owner Info Block +/** + * @brief 4.4.9.1 Channel Owner Info Block + */ struct channel_info_block_t { MID mid; UUID::uuid owner; @@ -175,7 +208,10 @@ struct channel_info_block_t { std::list protocols; }; -// 4.4.9 Sessions + +/** + * @brief 4.4.9 Sessions + */ struct sessions_data_t : PDU::pdu_data { std::list list; size_t streamSize() const override { return 0; } @@ -183,7 +219,10 @@ struct sessions_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.5.1 ACK + +/** + * @brief 4.5.1 ACK + */ struct ack_data_t : PDU::pdu_data { uint32_t reliable; size_t streamSize() const override { return 4; } @@ -191,7 +230,10 @@ struct ack_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.5.2 Channel Params + +/** + * @brief 4.5.2 Channel Params + */ struct channel_params_data_t : PDU::pdu_data { params_t parameters; UDP::address_t address; @@ -201,18 +243,21 @@ struct channel_params_data_t : PDU::pdu_data { void oStream(PDU::Stream) const override {}; }; -// 4.5.3 Connect -// 4.5.4 Connect Accept -// 4.5.6 Disconnect + +/** + * @brief 4.5.3 Connect, 4.5.4 Connect Accept, & 4.5.6 Disconnect + */ struct connect_data_t : PDU::pdu_data { uint32_t protocol; - size_t streamSize() const override { return 0; } + size_t streamSize() const override { return 4; } void iStream(PDU::Stream) override {}; void oStream(PDU::Stream) const override {}; }; -// 4.5.5 Connect Refuse -// 4.5.7 Disconnecting + +/** + * @brief 4.5.5 Connect Refuse & 4.5.7 Disconnecting + */ struct connect_refuse_data_t : PDU::pdu_data { uint32_t protocol; uint8_t code; @@ -222,10 +267,15 @@ struct connect_refuse_data_t : PDU::pdu_data { }; -// 7.1 Protocol Code +/** + * @brief 7.1 Protocol Code + */ static const uint32_t SDT_PROTOCOL_ID = 1; // PDU protocol value -// 7.2 PDU Vector Codes + +/** + * @brief 7.2 PDU Vector Codes + */ enum sdt_vector_t { REL_WRAP = 1, UNREL_WRAP = 2, @@ -248,7 +298,9 @@ enum sdt_vector_t { // 7.4 Other Symbolic Parameters -// Table 6: Reason Codes +/** + * @brief Table 6: Reason Codes + */ enum reason_code_t { NONSPECIFIC = 1, // Non-specific, non-SDT reason. ILLEGAL_PARAMETERS = 2, // Illegal channel parameters. @@ -265,26 +317,34 @@ enum reason_code_t { ONLY_UNICAST_SUPPORTED = 13 // Only unicast channels are supported }; -// Table 7: Address Specification Types + +/** + * @brief Table 7: Address Specification Types + */ enum ip_addr_spec_t { - SDT_ADDR_NULL = 0, // Address is not present (0 octets). - SDT_ADDR_IPV4 = 1, // Address specified is in IP v4 format - SDT_ADDR_IPV6 = 2 // Address specified is in IP v6 format + SDT_ADDR_NULL = 0, //!< Address is not present (0 octets). + SDT_ADDR_IPV4 = 1, //!< Address specified is in IP v4 format + SDT_ADDR_IPV6 = 2 //!< Address specified is in IP v6 format }; -// PDU type for this protocol + +/** + * @brief The SDT::Pdu class + */ class Pdu : public PDU::Pdu { public: Pdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; }; -// Sequenced channels are unidirectional communication channels (unicast or -// multicast) from an owner component to one or more member components. +/** + * @brief The Channel class + * Sequenced channels are unidirectional communication channels (unicast or + * multicast) from an owner component to one or more member components. + */ class Channel { public: Channel(std::shared_ptr, Direction); @@ -296,10 +356,13 @@ private: }; -// A session has a single leader and zero or more session members. The leader -// communicates to members using the downstream address. Members respond to the -// leader on the upstream address. A unique session identifier identifies a -// session. +/** + * @brief The Session class + * A session has a single leader and zero or more session members. The leader + * communicates to members using the downstream address. Members respond to + * the leader on the upstream address. A unique session identifier identifies + * a session. + */ class Session { public: Session(); diff --git a/sacn/data.h b/sacn/data.h index d0769ea..49622e0 100644 --- a/sacn/data.h +++ b/sacn/data.h @@ -31,7 +31,9 @@ namespace DATA { using std::uint8_t; using std::uint16_t; -// Table 6-1: E1.31 Data Packet Framing Layer +/** + * @brief Table 6-1: E1.31 Data Packet Framing Layer + */ struct frame_header : PDU::pdu_header { uint8_t source_name[64]; uint8_t priority; @@ -44,20 +46,26 @@ struct frame_header : PDU::pdu_header { void oStream(PDU::Stream) const override; }; -// 6.2.6 E1.31 Data Packet: Options + +/** + * @brief 6.2.6 E1.31 Data Packet: Options + */ enum options_t : uint8_t { PREVIEW_DATA = 0b10000000, // Bit 7 = Preview_Data STREAM_TERMINATED = 0b01000000, // Bit 6 = Stream_Terminated FORCE_SYNCHRONIZATION = 0b00100000, // Bit 5 = Force_Synchronization }; + +/** + * @brief The DATA::Pdu class + */ class Pdu : public PDU::Pdu { public: Pdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; }; } // DATA diff --git a/sacn/extended.h b/sacn/extended.h index fcc153f..8dc45fe 100644 --- a/sacn/extended.h +++ b/sacn/extended.h @@ -30,10 +30,10 @@ namespace SACN { using namespace ACN; namespace EXTENDED { -using std::uint8_t; -using std::uint16_t; -// 6.3 E1.31 Synchronization Packet Framing Layer +/** + * @brief 6.3 E1.31 Synchronization Packet Framing Layer + */ struct frame_sync_header : PDU::pdu_header { uint8_t sequence_number; uint16_t sync_address; @@ -44,7 +44,9 @@ struct frame_sync_header : PDU::pdu_header { }; -// 6.4 E1.31 Universe Discovery Packet Framing Layer +/** + * @brief 6.4 E1.31 Universe Discovery Packet Framing Layer + */ struct frame_discovery_header : PDU::pdu_header { uint8_t source_name[64]; uint8_t reserved[4]; @@ -54,19 +56,23 @@ struct frame_discovery_header : PDU::pdu_header { }; +/** + * @brief The EXTENDED::Pdu class + */ class Pdu : public PDU::Pdu { public: Pdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; }; namespace DISCOVERY { -// Table 8-9: E1.31 Universe Discovery Packet Universe Discovery Layer +/** + * @brief Table 8-9: E1.31 Universe Discovery Packet Universe Discovery Layer + */ struct discovery_list_header : PDU::pdu_header { uint8_t page; uint8_t last_page; @@ -75,19 +81,22 @@ struct discovery_list_header : PDU::pdu_header { void oStream(PDU::Stream) const override; }; + +/** + * @brief The EXTENDED::DISCOVERY::Pdu class + */ class Pdu : public PDU::Pdu { public: Pdu(); void iStream(PDU::Stream) override; - void oStream(PDU::Stream) const override {}; }; /** - universe metadata -*/ + * @brief The DiscoveredUniverse class + */ class DiscoveredUniverse { public: