From de874f802d5aa2d961f2f21ec2179707b4b0d356 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Fri, 2 Jan 2026 23:17:12 -0800 Subject: [PATCH 01/11] clippy doc_markdown --- src/error.rs | 18 +- src/packet.rs | 50 +++--- src/receive.rs | 316 +++++++++++++++++------------------ src/sacn_parse_pack_error.rs | 8 +- src/source.rs | 300 ++++++++++++++++----------------- 5 files changed, 346 insertions(+), 346 deletions(-) diff --git a/src/error.rs b/src/error.rs index 2756d33..0cd7b0d 100644 --- a/src/error.rs +++ b/src/error.rs @@ -84,30 +84,30 @@ pub mod errors { #[error("Limit for the number of supported sources has been reached: {0}")] SourcesExceededError(usize), - /// A source was discovered by a receiver with the announce_discovery_flag set to true. + /// A source was discovered by a receiver with the `announce_discovery_flag` set to true. /// /// # Arguments /// The name of the source discovered. #[error("Source discovered with announce_discovery_flag set to true: {0}")] SourceDiscovered(String), - /// Attempted to exceed the capacity of a single universe (packet::UNIVERSE_CHANNEL_CAPACITY). + /// Attempted to exceed the capacity of a single universe (`packet::UNIVERSE_CHANNEL_CAPACITY`). /// /// # Arguments /// Length of data provided. #[error("Attempted to exceed the capacity of a single universe, data len: {0}")] ExceedUniverseCapacity(usize), - /// Attempted to use illegal universe, outwith allowed range of [E131_MIN_MULTICAST_UNIVERSE, E131_MAX_MULTICAST_UNIVERSE] - /// + E131_DISCOVERY_UNIVERSE inclusive + /// Attempted to use illegal universe, outwith allowed range of [`E131_MIN_MULTICAST_UNIVERSE`, `E131_MAX_MULTICAST_UNIVERSE`] + /// + `E131_DISCOVERY_UNIVERSE` inclusive /// /// # Arguments /// u16: The provided universe. #[error("Attempted to use an illegal universe: {0}")] IllegalUniverse(u16), - /// Attempted to use illegal universe as the sync universe, outwith allowed range of [E131_MIN_MULTICAST_UNIVERSE, E131_MAX_MULTICAST_UNIVERSE] - /// + E131_DISCOVERY_UNIVERSE inclusive + /// Attempted to use illegal universe as the sync universe, outwith allowed range of [`E131_MIN_MULTICAST_UNIVERSE`, `E131_MAX_MULTICAST_UNIVERSE`] + /// + `E131_DISCOVERY_UNIVERSE` inclusive /// /// # Arguments /// u16: The provided synchronization universe. @@ -160,7 +160,7 @@ pub mod errors { OutOfSequence(u8, u8, isize), /// A source terminated a universe and this was detected when trying to receive data. - /// This is only returned if the announce_stream_termination flag is set to true (default false). + /// This is only returned if the `announce_stream_termination` flag is set to true (default false). /// /// # Arguments /// Uuid: The CID of the source which sent the termination packet. @@ -169,7 +169,7 @@ pub mod errors { #[error("Source terminated universe, source cid: {0}, universe: {1}")] UniverseTerminated(Uuid, u16), - /// A source universe timed out as no data was received on that universe within E131_NETWORK_DATA_LOSS_TIMEOUT as per ANSI E1.31-2018 Section 6.7.1. + /// A source universe timed out as no data was received on that universe within `E131_NETWORK_DATA_LOSS_TIMEOUT` as per ANSI E1.31-2018 Section 6.7.1. /// /// # Arguments /// uuid: The CID of the source which timed out. @@ -208,7 +208,7 @@ pub mod errors { /// such as by creating a new source. /// /// # Arguments - /// String: A message providing further details (if any) as to why the SourceCorrupt error was returned. + /// String: A message providing further details (if any) as to why the `SourceCorrupt` error was returned. #[error( "The sACN source has corrupted due to an internal panic! and should no longer be used, {0}" )] diff --git a/src/packet.rs b/src/packet.rs index 4616184..ffffd00 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -105,7 +105,7 @@ pub const E131_NO_SYNC_ADDR: u16 = 0; pub const E131_UNIVERSE_DISCOVERY_INTERVAL: Duration = time::Duration::from_secs(10); /// The exclusive lower bound on the different between the received and expected sequence numbers within which a -/// packet will be discarded. Outside of the range specified by (E131_SEQ_DIFF_DISCARD_LOWER_BOUND, E131_SEQ_DIFF_DISCARD_UPPER_BOUND] +/// packet will be discarded. Outside of the range specified by (`E131_SEQ_DIFF_DISCARD_LOWER_BOUND`, `E131_SEQ_DIFF_DISCARD_UPPER_BOUND`] /// the packet won't be discarded. /// /// Having a range allows receivers to catch up if packets are lost. @@ -113,7 +113,7 @@ pub const E131_UNIVERSE_DISCOVERY_INTERVAL: Duration = time::Duration::from_secs pub const E131_SEQ_DIFF_DISCARD_LOWER_BOUND: isize = -20; /// The inclusive upper bound on the different between the received and expected sequence numbers within which a -/// packet will be discarded. Outside of the range specified by (E131_SEQ_DIFF_DISCARD_LOWER_BOUND, E131_SEQ_DIFF_DISCARD_UPPER_BOUND] +/// packet will be discarded. Outside of the range specified by (`E131_SEQ_DIFF_DISCARD_LOWER_BOUND`, `E131_SEQ_DIFF_DISCARD_UPPER_BOUND`] /// the packet won't be discarded. /// /// Having a range allows receivers to catch up if packets are lost. @@ -153,7 +153,7 @@ pub const E131_UNIVERSE_SYNC_PACKET_FRAMING_LAYER_LENGTH: usize = 11; pub const E131_UNIVERSE_DISCOVERY_FRAMING_LAYER_MIN_LENGTH: usize = 82; /// The number of stream termination packets sent when a source terminates a stream. -/// Set to 3 as per section 6.2.6 , Stream_Terminated: Bit 6 of ANSI E1.31-2018. +/// Set to 3 as per section 6.2.6 , `Stream_Terminated`: Bit 6 of ANSI E1.31-2018. pub const E131_TERMINATE_STREAM_PACKET_COUNT: usize = 3; /// The length of the pdu flags and length field in bytes. @@ -277,19 +277,19 @@ pub const VECTOR_ROOT_E131_DATA: u32 = 0x0000_0004; pub const VECTOR_ROOT_E131_EXTENDED: u32 = 0x0000_0008; /// The E1.31 packet vector field value used to identify the E1.31 packet as a synchronisation packet. -/// This is used at the E1.31 layer and shouldn't be confused with the VECTOR values used for the ACN layer (i.e. VECTOR_ROOT_E131_DATA and VECTOR_ROOT_E131_EXTENDED). +/// This is used at the E1.31 layer and shouldn't be confused with the VECTOR values used for the ACN layer (i.e. `VECTOR_ROOT_E131_DATA` and `VECTOR_ROOT_E131_EXTENDED`). /// Value as defined in ANSI E1.31-2018 Appendix A: Defined Parameters (Normative). pub const VECTOR_E131_EXTENDED_SYNCHRONIZATION: u32 = 0x0000_0001; /// The E1.31 packet vector field value used to identify the E1.31 packet as a universe discovery packet. -/// This is used at the E1.31 layer and shouldn't be confused with the VECTOR values used for the ACN layer (i.e. VECTOR_ROOT_E131_DATA and VECTOR_ROOT_E131_EXTENDED). -/// This VECTOR value is shared by E1.31 data packets, distinguished by the value of the ACN ROOT_VECTOR. +/// This is used at the E1.31 layer and shouldn't be confused with the VECTOR values used for the ACN layer (i.e. `VECTOR_ROOT_E131_DATA` and `VECTOR_ROOT_E131_EXTENDED`). +/// This VECTOR value is shared by E1.31 data packets, distinguished by the value of the ACN `ROOT_VECTOR`. /// Value as defined in ANSI E1.31-2018 Appendix A: Defined Parameters (Normative). pub const VECTOR_E131_EXTENDED_DISCOVERY: u32 = 0x0000_0002; /// The E1.31 packet vector field value used to identify the E1.31 packet as a data packet. -/// This is used at the E1.31 layer and shouldn't be confused with the VECTOR values used for the ACN layer (i.e. VECTOR_ROOT_E131_DATA and VECTOR_ROOT_E131_EXTENDED). -/// This VECTOR value is shared by E1.31 universe discovery packets, distinguished by the value of the ACN ROOT_VECTOR. +/// This is used at the E1.31 layer and shouldn't be confused with the VECTOR values used for the ACN layer (i.e. `VECTOR_ROOT_E131_DATA` and `VECTOR_ROOT_E131_EXTENDED`). +/// This VECTOR value is shared by E1.31 universe discovery packets, distinguished by the value of the ACN `ROOT_VECTOR`. /// Value as defined in ANSI E1.31-2018 Appendix A: Defined Parameters (Normative). pub const VECTOR_E131_DATA_PACKET: u32 = 0x0000_0002; @@ -320,15 +320,15 @@ pub const E131_NETWORK_DATA_LOSS_TIMEOUT: Duration = Duration::from_millis(2500) pub const UNIVERSE_DISCOVERY_SOURCE_TIMEOUT: Duration = E131_NETWORK_DATA_LOSS_TIMEOUT; /// Converts the given ANSI E1.31-2018 universe into an Ipv4 multicast address with the port set to the acn multicast port as defined -/// in packet::ACN_SDT_MULTICAST_PORT. +/// in `packet::ACN_SDT_MULTICAST_PORT`. /// /// Conversion done as specified in section 9.3.1 of ANSI E1.31-2018 /// /// Returns the multicast address. /// /// # Errors -/// IllegalUniverse: Returned if the given universe is outwith the allowed range of universes, -/// see (is_universe_in_range)[fn.is_universe_in_range.packet]. +/// `IllegalUniverse`: Returned if the given universe is outwith the allowed range of universes, +/// see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. pub fn universe_to_ipv4_multicast_addr(universe: u16) -> Result { is_universe_in_range(universe)?; @@ -344,15 +344,15 @@ pub fn universe_to_ipv4_multicast_addr(universe: u16) -> Result { } /// Converts the given ANSI E1.31-2018 universe into an Ipv6 multicast address with the port set to the acn multicast port as defined -/// in packet::ACN_SDT_MULTICAST_PORT. +/// in `packet::ACN_SDT_MULTICAST_PORT`. /// /// Conversion done as specified in section 9.3.2 of ANSI E1.31-2018 /// /// Returns the multicast address. /// /// # Errors -/// IllegalUniverse: Returned if the given universe is outwith the allowed range of universes, -/// see (is_universe_in_range)[fn.is_universe_in_range.packet]. +/// `IllegalUniverse`: Returned if the given universe is outwith the allowed range of universes, +/// see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. pub fn universe_to_ipv6_multicast_addr(universe: u16) -> Result { is_universe_in_range(universe)?; @@ -367,8 +367,8 @@ pub fn universe_to_ipv6_multicast_addr(universe: u16) -> Result { /// Checks if the given universe is a valid universe to send on (within allowed range). /// /// # Errors -/// IllegalUniverse: Returned if the universe is outwith the allowed range of universes -/// [E131_MIN_MULTICAST_UNIVERSE, E131_MAX_MULTICAST_UNIVERSE] + E131_DISCOVERY_UNIVERSE. +/// `IllegalUniverse`: Returned if the universe is outwith the allowed range of universes +/// [`E131_MIN_MULTICAST_UNIVERSE`, `E131_MAX_MULTICAST_UNIVERSE`] + `E131_DISCOVERY_UNIVERSE`. pub fn is_universe_in_range(universe: u16) -> Result<()> { if (universe != E131_DISCOVERY_UNIVERSE) && !(E131_MIN_MULTICAST_UNIVERSE..=E131_MAX_MULTICAST_UNIVERSE).contains(&universe) @@ -392,7 +392,7 @@ fn zeros(buf: &mut [u8], n: usize) { /// buf: The byte buffer to parse into a str. /// /// # Errors -/// SourceNameNotNullTerminated: Returned if the source name is not null terminated as required by ANSI E1.31-2018 Section 6.2.2 +/// `SourceNameNotNullTerminated`: Returned if the source name is not null terminated as required by ANSI E1.31-2018 Section 6.2.2 #[inline] fn parse_source_name_str(buf: &[u8]) -> Result<&str> { let mut source_name_length = buf.len(); @@ -514,25 +514,25 @@ macro_rules! impl_acn_root_layer_protocol { impl_acn_root_layer_protocol!(<'a>); -/// Represents the data contained with the PduInfo section that appears at the start of a layer in an sACN packet. +/// Represents the data contained with the `PduInfo` section that appears at the start of a layer in an sACN packet. struct PduInfo { - /// The length in bytes of this layer inclusive of the PduInfo. + /// The length in bytes of this layer inclusive of the `PduInfo`. length: usize, /// The vector which indicates what the layer is, context dependent. vector: u32, } -/// Takes the given byte buffer and parses the flags, length and vector fields into a PduInfo struct. +/// Takes the given byte buffer and parses the flags, length and vector fields into a `PduInfo` struct. /// /// # Arguments /// buf: The raw byte buffer. /// -/// vector_length: The length of the vectorfield in bytes. +/// `vector_length`: The length of the vectorfield in bytes. /// /// # Errors -/// ParseInsufficientData: If the length of the buffer is less than the flag, length and vector fields (E131_PDU_LENGTH_FLAGS_LENGTH + vector_length). +/// `ParseInsufficientData`: If the length of the buffer is less than the flag, length and vector fields (`E131_PDU_LENGTH_FLAGS_LENGTH` + `vector_length`). /// -/// ParsePduInvalidFlags: If the flags parsed don't match the flags expected for an ANSI E1.31-2018 packet as per ANSI E1.31-2018 Section 4 Table 4-1, 4-2, 4-3. +/// `ParsePduInvalidFlags`: If the flags parsed don't match the flags expected for an ANSI E1.31-2018 packet as per ANSI E1.31-2018 Section 4 Table 4-1, 4-2, 4-3. fn pdu_info(buf: &[u8], vector_length: usize) -> Result { if buf.len() < E131_PDU_LENGTH_FLAGS_LENGTH + vector_length { return Err(SacnError::SacnParsePackError( @@ -1457,9 +1457,9 @@ macro_rules! impl_universe_discovery_packet_universe_discovery_layer { /// length: The number of universes to attempt to parse from the buffer. /// /// # Errors -/// ParseInvalidUniverseOrder: If the universes are not sorted in ascending order with no duplicates. +/// `ParseInvalidUniverseOrder`: If the universes are not sorted in ascending order with no duplicates. /// -/// ParseInsufficientData: If the buffer doesn't contain sufficient bytes and so cannot be parsed into the specified number of u16 universes. +/// `ParseInsufficientData`: If the buffer doesn't contain sufficient bytes and so cannot be parsed into the specified number of u16 universes. fn parse_universe_list<'a>(buf: &[u8], length: usize) -> Result> { let mut universes: Vec = Vec::with_capacity(length); let mut i = 0; diff --git a/src/receive.rs b/src/receive.rs index 3e15eee..2144d9c 100644 --- a/src/receive.rs +++ b/src/receive.rs @@ -46,11 +46,11 @@ use std::net::{IpAddr, Ipv6Addr}; use libc::{AF_INET, AF_INET6}; /// The libc constants required are not available on many windows environments and therefore are hard-coded. -/// Defined as per https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-socket +/// Defined as per #[cfg(target_os = "windows")] const AF_INET: i32 = 2; -/// Defined as per https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-socket +/// Defined as per #[cfg(target_os = "windows")] const AF_INET6: i32 = 23; @@ -64,20 +64,20 @@ pub const RCV_BUF_DEFAULT_SIZE: usize = 1144; /// DMX payload size in bytes (512 bytes of data + 1 byte start code). pub const DMX_PAYLOAD_SIZE: usize = 513; -/// The default value of the process_preview_data flag. +/// The default value of the `process_preview_data` flag. const PROCESS_PREVIEW_DATA_DEFAULT: bool = false; -/// The default value of the announce_source_discovery flag. +/// The default value of the `announce_source_discovery` flag. /// Defaults to false based on the assumption that often receivers won't have any immediate response/checks to do on a source -/// announcing itself (every source does this approximately every 10 seconds as per the E131_DISCOVERY_INTERVAL). +/// announcing itself (every source does this approximately every 10 seconds as per the `E131_DISCOVERY_INTERVAL`). const ANNOUNCE_SOURCE_DISCOVERY_DEFAULT: bool = false; -/// The default value of the announce_stream_termination flag. +/// The default value of the `announce_stream_termination` flag. /// Defaults to false based on the assumption that often receivers will want to ignore termination from a source based on there /// being multiple possible sources. const ANNOUNCE_STREAM_TERMINATION_DEFAULT: bool = false; -/// The default value of the announce_timeout flag. +/// The default value of the `announce_timeout` flag. const ANNOUNCE_TIMEOUT_DEFAULT: bool = false; /// If a packet for a universe is waiting to be synchronised and then another packet is received with the same universe and synchronisation address @@ -103,7 +103,7 @@ pub struct DMXData { pub sync_uni: u16, /// The priority of the data, this may be useful for receivers which want to implement their own implementing merge algorithms. - /// Must be less than packet::E131_MAX_PRIORITY. + /// Must be less than `packet::E131_MAX_PRIORITY`. pub priority: u8, /// The unique id of the source of the data, this may be useful for receivers which want to implement their own merge algorithms @@ -151,12 +151,12 @@ pub struct DMXData { /// } /// ``` pub struct SacnReceiver { - /// The SacnNetworkReceiver used for handling communication with UDP / Network / Transport layer. + /// The `SacnNetworkReceiver` used for handling communication with UDP / Network / Transport layer. receiver: SacnNetworkReceiver, /// Data that hasn't been passed up yet as it is waiting e.g. due to universe synchronisation. - /// Key is the universe. A receiver may not have more than one packet waiting per data_universe. - /// Data_universe used as key as oppose to sync universe because multiple packets might be waiting on the same sync universe + /// Key is the universe. A receiver may not have more than one packet waiting per `data_universe`. + /// `Data_universe` used as key as oppose to sync universe because multiple packets might be waiting on the same sync universe /// and adding data by data universe is at least as common as retrieving data by sync address because in a normal setup /// 1 or more bits of data wait for 1 sync. waiting_data: HashMap, @@ -167,15 +167,15 @@ pub struct SacnReceiver { /// Sacn sources that have been discovered by this receiver through universe discovery packets. discovered_sources: Vec, - /// The merge function used by this receiver if DMXData for the same universe and synchronisation universe is received while there - /// is already DMXData waiting for that universe and synchronisation address. + /// The merge function used by this receiver if `DMXData` for the same universe and synchronisation universe is received while there + /// is already `DMXData` waiting for that universe and synchronisation address. merge_func: fn(&DMXData, &DMXData) -> Result, /// Sacn sources that have been partially discovered by only some of their universes being discovered so far with more pages to go. partially_discovered_sources: Vec, /// The limit to the number of sources for which to track sequence numbers. - /// A new source after this limit will cause a SourcesExceededError as per ANSI E1.31-2018 Section 6.2.3.3. + /// A new source after this limit will cause a `SourcesExceededError` as per ANSI E1.31-2018 Section 6.2.3.3. source_limit: Option, /// The sequence numbers being tracked by this receiver for each packet type, source and universe. @@ -183,16 +183,16 @@ pub struct SacnReceiver { /// Flag that indicates if this receiver should process packets marked as preview data. /// If true then the receiver will process theses packets. - /// Returned data contains a flag to indicate if it is preview_data which can be used by the implementer to use/discard as required. + /// Returned data contains a flag to indicate if it is `preview_data` which can be used by the implementer to use/discard as required. process_preview_data: bool, - /// Flag which indicates if a SourceDiscovered error should be thrown when receiving data and a source is discovered. + /// Flag which indicates if a `SourceDiscovered` error should be thrown when receiving data and a source is discovered. announce_source_discovery: bool, - /// Flag which indicates if a StreamTerminated error should be thrown if a receiver receives a stream terminated packet. + /// Flag which indicates if a `StreamTerminated` error should be thrown if a receiver receives a stream terminated packet. announce_stream_termination: bool, - /// Flag which indicates if an UniverseTimeout error should be thrown if it is detected that a source has timed out. + /// Flag which indicates if an `UniverseTimeout` error should be thrown if it is detected that a source has timed out. announce_timeout: bool, } @@ -221,7 +221,7 @@ struct SacnNetworkReceiver { /// The underlying UDP network socket used. socket: Socket, - /// The address that this SacnNetworkReceiver is bound to. + /// The address that this `SacnNetworkReceiver` is bound to. addr: SocketAddr, /// If true then this receiver supports multicast, is false then it does not. @@ -245,7 +245,7 @@ struct UniversePage { universes: Vec, } -/// Allows debug ({:?}) printing of the SacnReceiver, used during debugging. +/// Allows debug ({:?}) printing of the `SacnReceiver`, used during debugging. impl fmt::Debug for SacnReceiver { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, "{:?}", self.receiver)?; @@ -257,33 +257,33 @@ impl fmt::Debug for SacnReceiver { } impl SacnReceiver { - /// Creates a new SacnReceiver. + /// Creates a new `SacnReceiver`. /// - /// SacnReceiverInternal is used for actually receiving the sACN data but is wrapped in SacnReceiver to allow the update thread to handle + /// `SacnReceiverInternal` is used for actually receiving the sACN data but is wrapped in `SacnReceiver` to allow the update thread to handle /// timeout etc. /// - /// By default for an IPv6 address this will only receive IPv6 data but IPv4 can also be enabled by calling set_ipv6_only(false). + /// By default for an IPv6 address this will only receive IPv6 data but IPv4 can also be enabled by calling `set_ipv6_only(false)`. /// A receiver with an IPv4 address will only receive IPv4 data. /// /// IPv6 multicast is unsupported on Windows in Rust. This is due to the underlying library (Socket2) not providing support. - /// Since UniverseDiscovery is primarily based around multicast to receive the UniverseDiscovery packets this mechanism is expected - /// to have limited usage when running in an Ipv6 Windows environment. The is_multicast_enabled method can be used to see if multicast + /// Since `UniverseDiscovery` is primarily based around multicast to receive the `UniverseDiscovery` packets this mechanism is expected + /// to have limited usage when running in an Ipv6 Windows environment. The `is_multicast_enabled` method can be used to see if multicast /// is enabled or not. /// /// Arguments: - /// ip: The address of the interface for this receiver to join, by default this address should use the ACN_SDT_MULTICAST_PORT as defined in + /// ip: The address of the interface for this receiver to join, by default this address should use the `ACN_SDT_MULTICAST_PORT` as defined in /// ANSI E1.31-2018 Appendix A: Defined Parameters (Normative) however another address might be used in some situations. - /// source_limit: The limit to the number of sources, past this limit a new source will cause a SourcesExceededError as per ANSI E1.31-2018 Section 6.2.3.3. + /// `source_limit`: The limit to the number of sources, past this limit a new source will cause a `SourcesExceededError` as per ANSI E1.31-2018 Section 6.2.3.3. /// A source limit of None means no limit to the number of sources. /// /// # Errors - /// Will return an InvalidInput error if the source_limit has a value of Some(0) which would indicate this receiver can never receive from any source. + /// Will return an `InvalidInput` error if the `source_limit` has a value of Some(0) which would indicate this receiver can never receive from any source. /// - /// Will return an error if the SacnReceiver fails to bind to a socket with the given ip. - /// For more details see socket2::Socket::new(). + /// Will return an error if the `SacnReceiver` fails to bind to a socket with the given ip. + /// For more details see `socket2::Socket::new()`. /// - /// Will return an error if the created SacnReceiver fails to listen to the E1.31_DISCOVERY_UNIVERSE. - /// For more details see SacnReceiver::listen_universes(). + /// Will return an error if the created `SacnReceiver` fails to listen to the `E1.31_DISCOVERY_UNIVERSE`. + /// For more details see `SacnReceiver::listen_universes()`. pub fn with_ip(ip: SocketAddr, source_limit: Option) -> Result { if let Some(x) = source_limit && x == 0 @@ -310,17 +310,17 @@ impl SacnReceiver { Ok(sri) } - /// Sets the value of the is_multicast_enabled flag to the given value. + /// Sets the value of the `is_multicast_enabled` flag to the given value. /// /// If set to false then the receiver won't attempt to join any more multicast groups. /// - /// This method does not attempt to leave multicast groups already joined through previous listen_universe calls. + /// This method does not attempt to leave multicast groups already joined through previous `listen_universe` calls. /// /// # Arguments - /// val: The new value for the is_multicast_enabled flag. + /// val: The new value for the `is_multicast_enabled` flag. /// /// # Errors - /// Will return an OsOperationUnsupported error if attempting to set the flag to true in an environment that multicast + /// Will return an `OsOperationUnsupported` error if attempting to set the flag to true in an environment that multicast /// isn't supported i.e. Ipv6 on Windows. pub fn set_is_multicast_enabled(&mut self, val: bool) -> Result<()> { self.receiver.set_is_multicast_enabled(val) @@ -336,7 +336,7 @@ impl SacnReceiver { /// Wipes the record of discovered and sequence number tracked sources. /// This is one way to handle a sources exceeded condition. /// - /// If you want to wipe data awaiting synchronisation then see (clear_all_waiting_data)[clear_all_waiting_data]. + /// If you want to wipe data awaiting synchronisation then see (`clear_all_waiting_data`)[`clear_all_waiting_data`]. pub fn reset_sources(&mut self) { self.sequences.clear(); self.partially_discovered_sources.clear(); @@ -346,9 +346,9 @@ impl SacnReceiver { /// Deletes all data currently waiting to be passed up - e.g. waiting for a synchronisation packet. /// /// This allows clearing all data awaiting synchronisation but without forgetting sequence numbers. To wipe sequence numbers - /// and discovered sources see (reset_sources)[reset_sources]. + /// and discovered sources see (`reset_sources`)[`reset_sources`]. /// - /// To clear only a specific universe of waiting data see (clear_waiting_data)[clear_waiting_data]. + /// To clear only a specific universe of waiting data see (`clear_waiting_data`)[`clear_waiting_data`]. pub fn clear_all_waiting_data(&mut self) { self.waiting_data.clear(); } @@ -368,11 +368,11 @@ impl SacnReceiver { /// This merge function is called if data is waiting for a universe e.g. for synchronisation and then further data for that universe with the same /// synchronisation address arrives. /// - /// This merge function MUST return a DmxMergeError if there is a problem merging. This error can optionally encapsulate further errors using the Error-chain system + /// This merge function MUST return a `DmxMergeError` if there is a problem merging. This error can optionally encapsulate further errors using the Error-chain system /// to provide a more informative backtrace. /// /// Arguments: - /// func: The merge function to use. Should take 2 DMXData references as arguments and return a Result. + /// func: The merge function to use. Should take 2 `DMXData` references as arguments and return a Result. pub fn set_merge_fn(&mut self, func: fn(&DMXData, &DMXData) -> Result) -> Result<()> { self.merge_func = func; Ok(()) @@ -385,14 +385,14 @@ impl SacnReceiver { /// Allows receiving from the given universe and starts listening to the multicast addresses which corresponds to the given universe. /// - /// Note that if the is_multicast_enabled flag is set to false then this method will only register the universe to listen to and won't + /// Note that if the `is_multicast_enabled` flag is set to false then this method will only register the universe to listen to and won't /// attempt to join any multicast groups. /// /// If 1 or more universes in the list are already being listened to this method will have no effect for those universes only. /// /// # Errors - /// Returns an SacnError::IllegalUniverse error if the given universe is outwith the allowed range of universes, - /// see (is_universe_in_range)[fn.is_universe_in_range.packet]. + /// Returns an `SacnError::IllegalUniverse` error if the given universe is outwith the allowed range of universes, + /// see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. /// /// pub fn listen_universes(&mut self, universes: &[u16]) -> Result<()> { @@ -421,10 +421,10 @@ impl SacnReceiver { /// Stops listening to the given universe. /// /// # Errors - /// Returns an SacnError::IllegalUniverse error if the given universe is outwith the allowed range of universes, - /// see (is_universe_in_range)[fn.is_universe_in_range.packet]. + /// Returns an `SacnError::IllegalUniverse` error if the given universe is outwith the allowed range of universes, + /// see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. /// - /// Returns UniverseNotFound if the given universe wasn't already being listened to. + /// Returns `UniverseNotFound` if the given universe wasn't already being listened to. pub fn mute_universe(&mut self, universe: u16) -> Result<()> { is_universe_in_range(universe)?; @@ -441,12 +441,12 @@ impl SacnReceiver { } } - /// Set the process_preview_data flag to the given value. + /// Set the `process_preview_data` flag to the given value. /// - /// This flag indicates if this receiver should process packets marked as preview_data or should ignore them. + /// This flag indicates if this receiver should process packets marked as `preview_data` or should ignore them. /// /// Argument: - /// val: The new value of process_preview_data flag. + /// val: The new value of `process_preview_data` flag. pub fn set_process_preview_data(&mut self, val: bool) { self.process_preview_data = val; } @@ -471,26 +471,26 @@ impl SacnReceiver { /// is already handled. /// /// # Errors - /// This method will return a WouldBlock (unix) or TimedOut (windows) error if there is no data ready within the given timeout. + /// This method will return a `WouldBlock` (unix) or `TimedOut` (windows) error if there is no data ready within the given timeout. /// A timeout of duration 0 will do timeout checks but otherwise will return a WouldBlock/TimedOut error without checking for data. /// - /// Will return SacnError::SourceDiscovered error if the announce_source_discovery flag is set and a universe discovery + /// Will return `SacnError::SourceDiscovered` error if the `announce_source_discovery` flag is set and a universe discovery /// packet is received and a source fully discovered. /// - /// Will return a UniverseNotRegistered error if this method is called with an infinite timeout, no - /// registered data universes and the announce_discovered_sources flag set to off. This is to protect the user from + /// Will return a `UniverseNotRegistered` error if this method is called with an infinite timeout, no + /// registered data universes and the `announce_discovered_sources` flag set to off. This is to protect the user from /// making this mistake leading to the method never being able to return. /// /// The method may also return an error if there is an issue setting a timeout on the receiver. See - /// SacnNetworkReceiver::set_timeout for details. + /// `SacnNetworkReceiver::set_timeout` for details. /// /// The method may also return an error if there is an issue handling the data as either a Data, Synchronisation or Discovery packet. - /// See the SacnReceiver::handle_data_packet, SacnReceiver::handle_sync_packet and SacnReceiver::handle_universe_discovery_packet methods + /// See the `SacnReceiver::handle_data_packet`, `SacnReceiver::handle_sync_packet` and `SacnReceiver::handle_universe_discovery_packet` methods /// for details. /// - /// If the announce_timeout flag is set then the recv will return a UniverseTimeout error if a source fails to send on a universe within the timeout - /// specified by E131_NETWORK_DATA_LOSS_TIMEOUT (ANSI E1.31-2018 Appendix A). This may not be detected immediately unless data is received for the timed-out - /// universe from the source. If it isn't detected immediately it will be detected within an interval of E131_NETWORK_DATA_LOSS_TIMEOUT (assuming code + /// If the `announce_timeout` flag is set then the recv will return a `UniverseTimeout` error if a source fails to send on a universe within the timeout + /// specified by `E131_NETWORK_DATA_LOSS_TIMEOUT` (ANSI E1.31-2018 Appendix A). This may not be detected immediately unless data is received for the timed-out + /// universe from the source. If it isn't detected immediately it will be detected within an interval of `E131_NETWORK_DATA_LOSS_TIMEOUT` (assuming code /// executes in zero time). pub fn recv(&mut self, timeout: Option) -> Result> { if self.universes.len() == 1 @@ -632,14 +632,14 @@ impl SacnReceiver { } } - /// Returns the current value of the announce_source_discovery flag. - /// See (set_announce_source_discovery)[receive::set_announce_source_discovery] for an explanation of the flag. + /// Returns the current value of the `announce_source_discovery` flag. + /// See (`set_announce_source_discovery`)[`receive::set_announce_source_discovery`] for an explanation of the flag. pub fn get_announce_source_discovery(&self) -> bool { self.announce_source_discovery } /// Gets all discovered sources without checking if any are timed out. - /// As the sources may be timed out get_discovered_sources is the preferred method but this is included + /// As the sources may be timed out `get_discovered_sources` is the preferred method but this is included /// to allow receivers to disable universe discovery source timeouts which may be useful in very high latency networks. pub fn get_discovered_sources_no_check(&mut self) -> Vec { self.discovered_sources.clone() @@ -651,48 +651,48 @@ impl SacnReceiver { self.discovered_sources.clone() } - /// Sets the value of the announce_source_discovery flag to the given value. + /// Sets the value of the `announce_source_discovery` flag to the given value. /// /// By default this flag is false which indicates that when receiving data discovered sources through universe discovery /// won't be announced by the recv method and the receivers list of discovered universes will be updated silently. - /// If set to true then it means that a SourceDiscovered error will be thrown whenever a source is discovered through a + /// If set to true then it means that a `SourceDiscovered` error will be thrown whenever a source is discovered through a /// complete universe discovery packet. /// /// # Arguments: - /// new_val: The new value for the announce_source_discovery flag. + /// `new_val`: The new value for the `announce_source_discovery` flag. pub fn set_announce_source_discovery(&mut self, new_val: bool) { self.announce_source_discovery = new_val; } - /// Returns the current value of the announce_timeout flag. - /// See (set_announce_timeout)[set_announce_timeout] for an explanation of the flag. + /// Returns the current value of the `announce_timeout` flag. + /// See (`set_announce_timeout`)[`set_announce_timeout`] for an explanation of the flag. pub fn get_announce_timeout(&self) -> bool { self.announce_timeout } - /// Sets the value of the announce_timeout flag to the given value. + /// Sets the value of the `announce_timeout` flag to the given value. /// /// By default this flag is false which means that if a universe for a source times out due to data not being sent then /// this will be updated on the receiver silently. - /// If set to true then a UniverseTimeout error will be thrown when attempting to receive if it is detected that a source universe has + /// If set to true then a `UniverseTimeout` error will be thrown when attempting to receive if it is detected that a source universe has /// timed out as per ANSI E1.31-2018 Section 6.7.1. /// /// # Arguments: - /// new_val: The new value for the announce_timeout flag. + /// `new_val`: The new value for the `announce_timeout` flag. pub fn set_announce_timeout(&mut self, new_val: bool) { self.announce_timeout = new_val; } - /// Returns the current value of the announce_stream_termination flag. - /// See (set_announce_stream_termination)[set_announce_stream_termination] for an explanation of the flag. + /// Returns the current value of the `announce_stream_termination` flag. + /// See (`set_announce_stream_termination`)[`set_announce_stream_termination`] for an explanation of the flag. pub fn get_announce_stream_termination(&self) -> bool { self.announce_stream_termination } - /// Sets the value of the announce_stream_termination flag to the given value. + /// Sets the value of the `announce_stream_termination` flag to the given value. /// /// By default this flag is false. This indicates that if a source sends a stream termination packet it will be handled silently by the receiver. - /// If set to true then a UniverseTermination error will be thrown when attempting to receive if a termination packet is received as per + /// If set to true then a `UniverseTermination` error will be thrown when attempting to receive if a termination packet is received as per /// ANSI E1.31-2018 Section 6.2.6. pub fn set_announce_stream_termination(&mut self, new_val: bool) { self.announce_stream_termination = new_val; @@ -706,16 +706,16 @@ impl SacnReceiver { /// Synchronised data packets handled as per ANSI E1.31-2018 Section 6.2.4.1. /// /// Arguments: - /// data_pkt: The sACN data packet to handle. + /// `data_pkt`: The sACN data packet to handle. /// /// # Errors - /// Returns an OutOfSequence error if a packet is received out of order as detected by the different between + /// Returns an `OutOfSequence` error if a packet is received out of order as detected by the different between /// the packets sequence number and the expected sequence number as specified in ANSI E1.31-2018 Section 6.7.2 Sequence Numbering. /// - /// Returns a UniversesTerminated error if a packet is received with the stream_terminated flag set indicating that the source is no longer - /// sending on that universe and the announce_stream_termination_flag is set to true. + /// Returns a `UniversesTerminated` error if a packet is received with the `stream_terminated` flag set indicating that the source is no longer + /// sending on that universe and the `announce_stream_termination_flag` is set to true. /// - /// Will return an DmxMergeError if there is an issue merging or replacing new and existing waiting data. + /// Will return an `DmxMergeError` if there is an issue merging or replacing new and existing waiting data. fn handle_data_packet( &mut self, cid: Uuid, @@ -792,14 +792,14 @@ impl SacnReceiver { /// Note this is just a record keeping operation, it doesn't actually effect the real sACN sender it /// just updates the record of what universes are expected on this receiver. /// - /// If the src_cid/source_name/universe isn't currently registered then this method has no effect. + /// If the `src_cid/source_name/universe` isn't currently registered then this method has no effect. /// This is intentional as it allows calling this function multiple times without worrying about failure because /// it comes to the same result. /// E.g. when a source terminates it sends 3 termination packets but a receiver should only terminate once. /// /// # Arguments: /// - /// src_cid: The CID of the source which is terminating a universe. + /// `src_cid`: The CID of the source which is terminating a universe. /// /// universe: The sACN universe to remove. fn terminate_stream(&mut self, src_cid: Uuid, universe: u16) { @@ -816,14 +816,14 @@ impl SacnReceiver { /// Takes the given data and tries to add it to the waiting data. /// - /// Note that a receiver will only store a single packet of data per data_universe at once. + /// Note that a receiver will only store a single packet of data per `data_universe` at once. /// /// If there is waiting data for the same universe as the data then it will be merged as per the - /// merge_func which by default keeps the highest priority data, if the data has the same priority + /// `merge_func` which by default keeps the highest priority data, if the data has the same priority /// then the newest data is kept. /// /// # Errors - /// Will return an DmxMergeError if there is an issue merging or replacing new and existing waiting data. + /// Will return an `DmxMergeError` if there is an issue merging or replacing new and existing waiting data. fn store_waiting_data(&mut self, data: DMXData) -> Result<()> { match self.waiting_data.remove(&data.universe) { Some(existing) => { @@ -852,10 +852,10 @@ impl SacnReceiver { /// it shall hold that E1.31 Data Packet until the arrival of the appropriate E1.31 Synchronization Packet before acting on it. /// /// Arguments: - /// sync_pkt: The E1.31 synchronisation part of the synchronisation packet to handle. + /// `sync_pkt`: The E1.31 synchronisation part of the synchronisation packet to handle. /// /// # Errors - /// Returns an OutOfSequence error if a packet is received out of order as detected by the different between + /// Returns an `OutOfSequence` error if a packet is received out of order as detected by the different between /// the packets sequence number and the expected sequence number as specified in ANSI E1.31-2018 Section 6.7.2 Sequence Numbering. fn handle_sync_packet( &mut self, @@ -886,7 +886,7 @@ impl SacnReceiver { /// Returns an empty Vec if there is no data waiting. /// /// Arguments: - /// sync_uni: The synchronisation universe of the data that should be retrieved. + /// `sync_uni`: The synchronisation universe of the data that should be retrieved. fn rtrv_waiting_data(&mut self, sync_uni: u16) -> Vec { // Get the universes (used as keys) to remove and then move the corresponding data out of the waiting data and into the result. // This prevents having to copy DMXData. @@ -909,12 +909,12 @@ impl SacnReceiver { res } - /// Takes the given DiscoveredSacnSource and updates the record of discovered sacn sources. + /// Takes the given `DiscoveredSacnSource` and updates the record of discovered sacn sources. /// /// This adds the new source deleting any previous source with the same name. /// /// Arguments: - /// src: The DiscoveredSacnSource to update the record of discovered sacn sources with. + /// src: The `DiscoveredSacnSource` to update the record of discovered sacn sources with. fn update_discovered_srcs(&mut self, src: DiscoveredSacnSource) { if let Some(index) = find_discovered_src(&self.discovered_sources, &src.cid) { self.discovered_sources.remove(index); @@ -925,7 +925,7 @@ impl SacnReceiver { /// Handles the given universe discovery packet. /// /// This universe discovery packet might be the whole thing or may be just one page of a discovery packet. - /// This method puts the pages to produce the DiscoveredSacnSource which is stored in the receiver. + /// This method puts the pages to produce the `DiscoveredSacnSource` which is stored in the receiver. /// /// Returns the source name if a source was fully discovered or None if the source was only partially discovered. /// @@ -933,7 +933,7 @@ impl SacnReceiver { /// /// cid: the source CID. /// - /// discovery_pkt: The universe discovery part of the universe discovery packet to handle. + /// `discovery_pkt`: The universe discovery part of the universe discovery packet to handle. fn handle_universe_discovery_packet( &mut self, cid: Uuid, @@ -993,7 +993,7 @@ impl SacnReceiver { None // No source fully discovered. } - /// Goes through all the waiting data and removes any which has timed out as a sync-packet for it hasn't been received within the E131_NETWORK_DATA_LOSS_TIMEOUT + /// Goes through all the waiting data and removes any which has timed out as a sync-packet for it hasn't been received within the `E131_NETWORK_DATA_LOSS_TIMEOUT` /// period as specified by ANSI E1.31-2018 Section 11.1.2. fn check_waiting_data_timeouts(&mut self) { self.waiting_data @@ -1009,7 +1009,7 @@ impl SacnReceiver { } } -/// By implementing the Drop trait for SacnNetworkReceiver it means that the user doesn't have to explicitly clean up the receiver +/// By implementing the Drop trait for `SacnNetworkReceiver` it means that the user doesn't have to explicitly clean up the receiver /// and if it goes out of reference it will clean itself up. impl Drop for SacnReceiver { fn drop(&mut self) { @@ -1035,14 +1035,14 @@ impl Drop for SacnReceiver { /// /// Arguments: /// -/// srcs: The Vec of DiscoveredSacnSources to search. +/// srcs: The Vec of `DiscoveredSacnSources` to search. /// /// cid: The CID (uuid) of the source to find. fn find_discovered_src(srcs: &[DiscoveredSacnSource], cid: &Uuid) -> Option { (0..srcs.len()).find(|&i| srcs[i].cid == *cid) } -/// In general the lower level transport layer is handled by SacnNetworkReceiver (which itself wraps a Socket). +/// In general the lower level transport layer is handled by `SacnNetworkReceiver` (which itself wraps a Socket). /// Windows and linux handle multicast sockets differently. /// This is built for / tested with Windows 10 1909. #[cfg(target_os = "windows")] @@ -1050,11 +1050,11 @@ impl SacnNetworkReceiver { /// Creates a new DMX receiver on the interface specified by the given address. /// /// If the given address is an IPv4 address then communication will only work between IPv4 devices, if the given address is IPv6 then communication - /// will only work between IPv6 devices by default but IPv4 receiving can be enabled using set_ipv6_only(false). + /// will only work between IPv6 devices by default but IPv4 receiving can be enabled using `set_ipv6_only(false)`. /// /// # Errors - /// Will return an error if the SacnReceiver fails to bind to a socket with the given ip. - /// For more details see socket2::Socket::new(). + /// Will return an error if the `SacnReceiver` fails to bind to a socket with the given ip. + /// For more details see `socket2::Socket::new()`. fn new(ip: SocketAddr) -> Result { Ok(SacnNetworkReceiver { socket: create_win_socket(ip)?, @@ -1063,11 +1063,11 @@ impl SacnNetworkReceiver { }) } - /// Connects this SacnNetworkReceiver to the multicast address which corresponds to the given universe to allow receiving packets for that universe. + /// Connects this `SacnNetworkReceiver` to the multicast address which corresponds to the given universe to allow receiving packets for that universe. /// /// # Errors - /// Will return an Error if the given universe cannot be converted to an Ipv4 or Ipv6 multicast_addr depending on if the Receiver is bound to an - /// IPv4 or IPv6 address. See packet::universe_to_ipv4_multicast_addr and packet::universe_to_ipv6_multicast_addr. + /// Will return an Error if the given universe cannot be converted to an Ipv4 or Ipv6 `multicast_addr` depending on if the Receiver is bound to an + /// IPv4 or IPv6 address. See `packet::universe_to_ipv4_multicast_addr` and `packet::universe_to_ipv6_multicast_addr`. /// /// Will return an Io error if cannot join the universes corresponding multicast group address. fn listen_multicast_universe(&self, universe: u16) -> Result<()> { @@ -1080,11 +1080,11 @@ impl SacnNetworkReceiver { join_win_multicast(&self.socket, multicast_addr, self.addr.ip()) } - /// Removes this SacnNetworkReceiver from the multicast group which corresponds to the given universe. + /// Removes this `SacnNetworkReceiver` from the multicast group which corresponds to the given universe. /// /// # Errors - /// Will return an Error if the given universe cannot be converted to an Ipv4 or Ipv6 multicast_addr depending on if the Receiver is bound to an - /// IPv4 or IPv6 address. See packet::universe_to_ipv4_multicast_addr and packet::universe_to_ipv6_multicast_addr. + /// Will return an Error if the given universe cannot be converted to an Ipv4 or Ipv6 `multicast_addr` depending on if the Receiver is bound to an + /// IPv4 or IPv6 address. See `packet::universe_to_ipv4_multicast_addr` and `packet::universe_to_ipv6_multicast_addr`. fn mute_multicast_universe(&mut self, universe: u16) -> Result<()> { let multicast_addr = if self.addr.is_ipv4() { universe_to_ipv4_multicast_addr(universe)? // "Failed to convert universe to IPv4 multicast addr" @@ -1095,17 +1095,17 @@ impl SacnNetworkReceiver { leave_win_multicast(&self.socket, multicast_addr) } - /// Sets the value of the is_multicast_enabled flag to the given value. + /// Sets the value of the `is_multicast_enabled` flag to the given value. /// /// If set to false then the receiver won't attempt to join any more multicast groups. /// - /// This method does not attempt to leave multicast groups already joined through previous listen_universe calls. + /// This method does not attempt to leave multicast groups already joined through previous `listen_universe` calls. /// /// # Arguments - /// val: The new value for the is_multicast_enabled flag. + /// val: The new value for the `is_multicast_enabled` flag. /// /// # Errors - /// Will return an OsOperationUnsupported error if attempting to set the flag to true in an environment that multicast + /// Will return an `OsOperationUnsupported` error if attempting to set the flag to true in an environment that multicast /// isn't supported i.e. Ipv6 on Windows. fn set_is_multicast_enabled(&mut self, val: bool) -> Result<()> { if val && self.is_ipv6() { @@ -1125,7 +1125,7 @@ impl SacnNetworkReceiver { } /// If set to true then only receive over IPv6. If false then receiving will be over both IPv4 and IPv6. - /// This will return an error if the SacnReceiver wasn't created using an IPv6 address to bind to. + /// This will return an error if the `SacnReceiver` wasn't created using an IPv6 address to bind to. fn set_only_v6(&mut self, val: bool) -> Result<()> { if self.addr.is_ipv4() { Err(SacnError::IpVersionError()) @@ -1137,22 +1137,22 @@ impl SacnNetworkReceiver { /// Returns a packet if there is one available. /// /// The packet may not be ready to transmit if it is awaiting synchronisation. - /// Will only block if set_timeout was called with a timeout of None so otherwise (and by default) it won't + /// Will only block if `set_timeout` was called with a timeout of None so otherwise (and by default) it won't /// block so may return a WouldBlock/TimedOut error to indicate that there was no data ready. /// /// IMPORTANT NOTE: - /// An explicit lifetime is given to the AcnRootLayerProtocol which comes from the lifetime of the given buffer. - /// The compiler will prevent usage of the returned AcnRootLayerProtocol after the buffer is dropped normally but may not in the case + /// An explicit lifetime is given to the `AcnRootLayerProtocol` which comes from the lifetime of the given buffer. + /// The compiler will prevent usage of the returned `AcnRootLayerProtocol` after the buffer is dropped normally but may not in the case /// of unsafe code . /// /// Arguments: /// buf: The buffer to use for storing the received data into. This buffer shouldn't be accessed or used directly as the data - /// is returned formatted properly in the AcnRootLayerProtocol. This buffer is used as memory space for the returned AcnRootLayerProtocol. + /// is returned formatted properly in the `AcnRootLayerProtocol`. This buffer is used as memory space for the returned `AcnRootLayerProtocol`. /// /// # Errors /// May return an error if there is an issue receiving data from the underlying socket, see (recv)[fn.recv.Socket]. /// - /// May return an error if there is an issue parsing the data from the underlying socket, see (parse)[fn.AcnRootLayerProtocol::parse.packet]. + /// May return an error if there is an issue parsing the data from the underlying socket, see (parse)[`fn.AcnRootLayerProtocol::parse.packet`]. fn recv<'a>( &mut self, buf: &'a mut [u8; RCV_BUF_DEFAULT_SIZE], @@ -1171,12 +1171,12 @@ impl SacnNetworkReceiver { /// timeout: The new timeout for the receive operation, a value of None means the recv operation will become blocking. /// /// Errors: - /// A timeout with Duration 0 will cause an error. See (set_read_timeout)[fn.set_read_timeout.Socket]. + /// A timeout with Duration 0 will cause an error. See (`set_read_timeout`)[`fn.set_read_timeout.Socket`]. fn set_timeout(&mut self, timeout: Option) -> Result<()> { Ok(self.socket.set_read_timeout(timeout)?) } - /// Returns true if this SacnNetworkReceiver is bound to an Ipv6 address. + /// Returns true if this `SacnNetworkReceiver` is bound to an Ipv6 address. fn is_ipv6(&self) -> bool { self.addr.is_ipv6() } @@ -1325,7 +1325,7 @@ impl Clone for DMXData { } } -/// DMXData has a total ordering based on the universe, then sync-universe and finally values. +/// `DMXData` has a total ordering based on the universe, then sync-universe and finally values. impl Ord for DMXData { fn cmp(&self, other: &Self) -> Ordering { self.universe @@ -1335,14 +1335,14 @@ impl Ord for DMXData { } } -/// See Ord trait implementation for DMXData. +/// See Ord trait implementation for `DMXData`. impl PartialOrd for DMXData { fn partial_cmp(&self, other: &Self) -> Option { Some(self.cmp(other)) } } -/// DMXData is taken to be equivalent iff: +/// `DMXData` is taken to be equivalent iff: /// - The universes are the same /// - The synchronisation universes are the same /// - The values are all the same @@ -1354,11 +1354,11 @@ impl PartialEq for DMXData { } } -/// See PartialEq trait implementation for DMXData. +/// See `PartialEq` trait implementation for `DMXData`. impl Eq for DMXData {} impl DiscoveredSacnSource { - /// Returns true if all the pages sent by this DiscoveredSacnSource have been received. + /// Returns true if all the pages sent by this `DiscoveredSacnSource` have been received. /// /// This is based on each page containing a last-page value which indicates the number of the last page expected. pub fn has_all_pages(&mut self) -> bool { @@ -1378,7 +1378,7 @@ impl DiscoveredSacnSource { true } - /// Returns all the universes being send by this SacnSource as discovered through the universe discovery mechanism. + /// Returns all the universes being send by this `SacnSource` as discovered through the universe discovery mechanism. /// /// Intentionally abstracts over the underlying concept of pages as this is purely an E1.31 Universe Discovery concept and is otherwise transparent. pub fn get_all_universes(&self) -> Vec { @@ -1555,7 +1555,7 @@ fn leave_unix_multicast(socket: &Socket, addr: SockAddr, interface_addr: IpAddr) /// addr: The address that the newly created socket should bind to. /// /// # Errors -/// Will return an error if the socket cannot be created, see (Socket::new)[fn.new.Socket]. +/// Will return an error if the socket cannot be created, see (`Socket::new`)[fn.new.Socket]. /// /// Will return an error if the socket cannot be bound to the given address, see (bind)[fn.bind.Socket]. #[cfg(target_os = "windows")] @@ -1585,9 +1585,9 @@ fn create_win_socket(addr: SocketAddr) -> Result { /// /// # Errors /// Will return an error if the given socket cannot be joined to the given multicast group address. -/// See join_multicast_v4[fn.join_multicast_v4.Socket] and join_multicast_v6[fn.join_multicast_v6.Socket] +/// See `join_multicast_v4`[`fn.join_multicast_v4.Socket`] and `join_multicast_v6`[`fn.join_multicast_v6.Socket`] /// -/// Will return OsOperationUnsupported error if attempt to leave an Ipv6 multicast group as all Ipv6 multicast operations are currently unsupported in Rust on Windows. +/// Will return `OsOperationUnsupported` error if attempt to leave an Ipv6 multicast group as all Ipv6 multicast operations are currently unsupported in Rust on Windows. #[cfg(target_os = "windows")] fn join_win_multicast(socket: &Socket, addr: SockAddr, interface_addr: IpAddr) -> Result<()> { match addr.family() as i32 { @@ -1643,9 +1643,9 @@ fn join_win_multicast(socket: &Socket, addr: SockAddr, interface_addr: IpAddr) - /// /// # Errors /// Will return an error if the given socket cannot leave the given multicast group address. -/// See leave_multicast_v4[fn.leave_multicast_v4.Socket] and leave_multicast_v6[fn.leave_multicast_v6.Socket] +/// See `leave_multicast_v4`[`fn.leave_multicast_v4.Socket`] and `leave_multicast_v6`[`fn.leave_multicast_v6.Socket`] /// -/// Will return OsOperationUnsupported error if attempt to leave an Ipv6 multicast group as all Ipv6 multicast operations are currently unsupported in Rust on Windows. +/// Will return `OsOperationUnsupported` error if attempt to leave an Ipv6 multicast group as all Ipv6 multicast operations are currently unsupported in Rust on Windows. #[cfg(target_os = "windows")] fn leave_win_multicast(socket: &Socket, addr: SockAddr) -> Result<()> { match addr.family() as i32 { @@ -1685,7 +1685,7 @@ fn leave_win_multicast(socket: &Socket, addr: SockAddr) -> Result<()> { /// Stores a sequence number and a timestamp. /// -/// Used internally within SequenceNumbering for tracking the last received timestamps of each packet-type, source, universe combination. +/// Used internally within `SequenceNumbering` for tracking the last received timestamps of each packet-type, source, universe combination. /// /// This is then used to workout timeouts to trigger network data loss as per ANSI E1.31-2018 Section 6.7.1. #[derive(Copy, Clone)] @@ -1723,9 +1723,9 @@ struct SequenceNumbering { } impl SequenceNumbering { - /// Creates a new SequenceNumbering for tracking sequence numbers for the various types of packets. + /// Creates a new `SequenceNumbering` for tracking sequence numbers for the various types of packets. /// - /// This implementation uses HashMaps internally to allow O(1) checking and updating of sequence numbers. + /// This implementation uses `HashMaps` internally to allow O(1) checking and updating of sequence numbers. fn new() -> SequenceNumbering { SequenceNumbering { data_sequences: HashMap::new(), @@ -1740,12 +1740,12 @@ impl SequenceNumbering { } /// Checks the timeouts for all packet types, sources and universes with sequence numbers registed. - /// Removes any universes for which the last_recv time was at least the given timeout amount of time ago. + /// Removes any universes for which the `last_recv` time was at least the given timeout amount of time ago. /// Any sources which have no universes after this operation are also removed. /// /// #Arguments /// - /// announce_timeout: A flag, if true it indicates than a UniverseTimeout error should be thrown if a universe times out on a source. + /// `announce_timeout`: A flag, if true it indicates than a `UniverseTimeout` error should be thrown if a universe times out on a source. fn check_timeouts(&mut self, announce_timeout: bool) -> Result<()> { check_timeouts( &mut self.data_sequences, @@ -1759,25 +1759,25 @@ impl SequenceNumbering { ) } - /// Checks the sequence number is correct for a data packet with the given sequence_number and universe from the given source with given cid. - /// Uses the given source_limit to check that it isn't exceeded. + /// Checks the sequence number is correct for a data packet with the given `sequence_number` and universe from the given source with given cid. + /// Uses the given `source_limit` to check that it isn't exceeded. /// /// Returns Ok(()) if the packet is detected in-order. /// /// # Arguments - /// source_limit: The limit on the number of sources which are allowed, None indicates no limit, if there is a limit then a SourcesExceededError may be returned. + /// `source_limit`: The limit on the number of sources which are allowed, None indicates no limit, if there is a limit then a `SourcesExceededError` may be returned. /// /// cid: The Uuid of the source that send the packet. /// - /// sequence_number: The sequence number of the packet to check. + /// `sequence_number`: The sequence number of the packet to check. /// /// universe: The data universe of the packet. /// /// # Errors - /// Returns an OutOfSequence error if a packet is received out of order as detected by the different between + /// Returns an `OutOfSequence` error if a packet is received out of order as detected by the different between /// the packets sequence number and the expected sequence number as specified in ANSI E1.31-2018 Section 6.7.2 Sequence Numbering. /// - /// Return a SourcesExceededError if the cid of the source is new and would cause the number of sources to exceed the given source_limit. + /// Return a `SourcesExceededError` if the cid of the source is new and would cause the number of sources to exceed the given `source_limit`. fn check_data_seq_number( &mut self, source_limit: Option, @@ -1796,25 +1796,25 @@ impl SequenceNumbering { ) } - /// Checks the sequence number is correct for a sync packet with the given sequence_number and universe from the given source with given cid. - /// Uses the given source_limit to check that it isn't exceeded. + /// Checks the sequence number is correct for a sync packet with the given `sequence_number` and universe from the given source with given cid. + /// Uses the given `source_limit` to check that it isn't exceeded. /// /// Returns Ok(()) if the packet is detected in-order. /// /// # Arguments - /// source_limit: The limit on the number of sources which are allowed, None indicates no limit, if there is a limit then a SourcesExceededError may be returned. + /// `source_limit`: The limit on the number of sources which are allowed, None indicates no limit, if there is a limit then a `SourcesExceededError` may be returned. /// /// cid: The Uuid of the source that send the packet. /// - /// sequence_number: The sequence number of the packet to check. + /// `sequence_number`: The sequence number of the packet to check. /// /// universe: The sync universe of the packet /// /// # Errors - /// Returns an OutOfSequence error if a packet is received out of order as detected by the different between + /// Returns an `OutOfSequence` error if a packet is received out of order as detected by the different between /// the packets sequence number and the expected sequence number as specified in ANSI E1.31-2018 Section 6.7.2 Sequence Numbering. /// - /// Return a SourcesExceededError if the cid of the source is new and would cause the number of sources to exceed the given source_limit. + /// Return a `SourcesExceededError` if the cid of the source is new and would cause the number of sources to exceed the given `source_limit`. fn check_sync_seq_number( &mut self, source_limit: Option, @@ -1838,7 +1838,7 @@ impl SequenceNumbering { /// /// # Arguments: /// - /// src_cid: The CID of the source to remove the sequence numbers of. + /// `src_cid`: The CID of the source to remove the sequence numbers of. /// /// universe: The universe being sent by the source from which to remove the sequence numbers. fn remove_seq_numbers(&mut self, src_cid: Uuid, universe: u16) -> Result<()> { @@ -1852,18 +1852,18 @@ impl SequenceNumbering { /// Returns Ok(()) if the packet is detected in-order. /// /// # Arguments -/// src_sequences: A mutable hashmap which relates sources identified by Uuid to another hashmap which itself relates universes to sequence numbers. The given hashmap of +/// `src_sequences`: A mutable hashmap which relates sources identified by Uuid to another hashmap which itself relates universes to sequence numbers. The given hashmap of /// sequences should be for the specific packet-type being checked as different packet-types have their own sequence numbers even from the same source. -/// source_limit: The limit on the number of sources which are allowed, None indicates no limit, if there is a limit then a SourcesExceededError may be returned. +/// `source_limit`: The limit on the number of sources which are allowed, None indicates no limit, if there is a limit then a `SourcesExceededError` may be returned. /// cid: The Uuid of the source that send the packet. -/// sequence_number: The sequence number of the packet to check. +/// `sequence_number`: The sequence number of the packet to check. /// universe: The universe of the packet (this is the data universe for data packets and the sync universe for synchronisation packets). /// /// # Errors -/// Returns an OutOfSequence error if a packet is received out of order as detected by the different between +/// Returns an `OutOfSequence` error if a packet is received out of order as detected by the different between /// the packets sequence number and the expected sequence number as specified in ANSI E1.31-2018 Section 6.7.2 Sequence Numbering. /// -/// Return a SourcesExceededError if the cid of the source is new and would cause the number of sources to exceed the given source_limit. +/// Return a `SourcesExceededError` if the cid of the source is new and would cause the number of sources to exceed the given `source_limit`. fn check_seq_number( src_sequences: &mut HashMap>, source_limit: Option, @@ -1952,12 +1952,12 @@ fn check_seq_number( } /// Checks the timeouts for all sources and universes for the given sequences. -/// Removes any universes for which the last_recv time was at least the given timeout amount of time ago. +/// Removes any universes for which the `last_recv` time was at least the given timeout amount of time ago. /// Any sources which have no universes after this operation are also removed. /// /// #Arguments /// -/// src_sequences: The source sequence numbers to check the timeout of. +/// `src_sequences`: The source sequence numbers to check the timeout of. /// /// timeout: The exclusive length of time permitted since a source last sent on a universe. /// If the time elapsed since the last received data that is equal to or great than the timeout then the source is said to have timed out. @@ -2014,16 +2014,16 @@ fn check_timeouts( /// This removes the source entirely if there are no universes left. /// /// # Arguments -/// src_sequences: The sequence numbers for each source and universe. +/// `src_sequences`: The sequence numbers for each source and universe. /// -/// src_cid: The CID for the source to remove the universe from. +/// `src_cid`: The CID for the source to remove the universe from. /// /// universe: The universe to remove from the source. /// /// # Errors -/// Returns a SourceNotFound error if the given src_cid isn't in the given collection of sources/sequence-numbers. +/// Returns a `SourceNotFound` error if the given `src_cid` isn't in the given collection of sources/sequence-numbers. /// -/// Returns a UniverseNotFound error if the given universe isn't registered to the given source and so cannot be removed. +/// Returns a `UniverseNotFound` error if the given universe isn't registered to the given source and so cannot be removed. fn remove_source_universe_seq( src_sequences: &mut HashMap>, src_cid: Uuid, @@ -2057,7 +2057,7 @@ fn remove_source_universe_seq( /// This can be changed if required as part of the mechanism described in ANSI E1.31-2018, Section 6.2.3.4 Requirements for Merging and Arbitrating. /// /// The first argument (i) is the existing data, n is the new data. -/// This function is only valid if both inputs have the same universe, sync addr, start_code and the data contains at least the first value (the start code). +/// This function is only valid if both inputs have the same universe, sync addr, `start_code` and the data contains at least the first value (the start code). /// If this doesn't hold an error will be returned. /// Other merge functions may allow merging different start codes or not check for them. pub fn discard_lowest_priority_then_previous(i: &DMXData, n: &DMXData) -> Result { @@ -2076,7 +2076,7 @@ pub fn discard_lowest_priority_then_previous(i: &DMXData, n: &DMXData) -> Result /// /// The first argument (i) is the existing data, n is the new data. /// -/// This function is only valid if both inputs have the same universe, sync addr, start_code and the data contains at least the first value (the start code). +/// This function is only valid if both inputs have the same universe, sync addr, `start_code` and the data contains at least the first value (the start code). /// If this doesn't hold an error will be returned. /// Other merge functions may allow merging different start codes or not check for them. pub fn htp_dmx_merge(i: &DMXData, n: &DMXData) -> Result { diff --git a/src/sacn_parse_pack_error.rs b/src/sacn_parse_pack_error.rs index 469649a..0fce059 100644 --- a/src/sacn_parse_pack_error.rs +++ b/src/sacn_parse_pack_error.rs @@ -21,7 +21,7 @@ pub enum ParsePacketError { #[error("Error when parsing data into packet, msg: {0}")] ParseInvalidData(String), - /// Attempted to parse a priority value that is outwith the allowed range of [0, E131_MAX_PRIORITY]. + /// Attempted to parse a priority value that is outwith the allowed range of [0, `E131_MAX_PRIORITY`]. /// As per ANSI E1.31-2018 Section 6.2.3 /// /// # Arguments @@ -31,14 +31,14 @@ pub enum ParsePacketError { )] ParseInvalidPriority(u8), - /// Attempted to parse a page value that is invalid - e.g. the page value is higher than the last_page value. + /// Attempted to parse a page value that is invalid - e.g. the page value is higher than the `last_page` value. /// /// # Arguments /// msg: A message providing further details (if any) as to why the page was invalid. #[error("Error when parsing page value, msg: {0}")] ParseInvalidPage(String), - /// Attempted to parse a sync address value that is outwith the allowed range of [0, E131_MAX_MULTICAST_UNIVERSE]. + /// Attempted to parse a sync address value that is outwith the allowed range of [0, `E131_MAX_MULTICAST_UNIVERSE`]. /// As per ANSI E1.31-2018 Section 9.1.1. /// /// # Arguments @@ -48,7 +48,7 @@ pub enum ParsePacketError { )] ParseInvalidSyncAddr(u16), - /// Attempted to parse a universe value that is outwith the allowed range of [1, E131_MAX_MULTICAST_UNIVERSE]. + /// Attempted to parse a universe value that is outwith the allowed range of [1, `E131_MAX_MULTICAST_UNIVERSE`]. /// As per ANSI E1.31-2018 Section 9.1.1. /// /// # Arguments diff --git a/src/source.rs b/src/source.rs index 89a8166..3f8b5bf 100644 --- a/src/source.rs +++ b/src/source.rs @@ -36,17 +36,17 @@ use uuid::Uuid; /// The name of the thread which runs periodically to perform various actions such as universe discovery adverts for the source. const SND_UPDATE_THREAD_NAME: &str = "rust_sacn_snd_update_thread"; -/// The default startcode used to send stream termination packets when the SacnSource is closed. +/// The default startcode used to send stream termination packets when the `SacnSource` is closed. const DEFAULT_TERMINATE_START_CODE: u8 = 0; /// The poll rate of the update thread. -/// Discovery updates are sent every E131_UNIVERSE_DISCOVERY_INTERVAL so the poll rate must be lower than or equal to this. +/// Discovery updates are sent every `E131_UNIVERSE_DISCOVERY_INTERVAL` so the poll rate must be lower than or equal to this. // const DEFAULT_POLL_PERIOD: Duration = E131_UNIVERSE_DISCOVERY_INTERVAL; const DEFAULT_POLL_PERIOD: Duration = Duration::from_secs(1); /// A DMX over sACN sender. /// -/// SacnSource is used for sending sACN packets over an IP network. +/// `SacnSource` is used for sending sACN packets over an IP network. /// /// # Examples /// @@ -81,23 +81,23 @@ pub struct SacnSource { /// Protected by a Mutex lock to allow concurrent access between user threads and the update thread below. internal: Arc>, - /// Update thread which performs actions every DEFAULT_POLL_PERIOD such as checking if a universe + /// Update thread which performs actions every `DEFAULT_POLL_PERIOD` such as checking if a universe /// discovery packet should be sent. update_thread: Option>, } -/// Internal sACN sender, this does most of the work however is encapsulated within SacnSource -/// to allow access by the update_thread which is used to manage sending periodic universe discovery packets. +/// Internal sACN sender, this does most of the work however is encapsulated within `SacnSource` +/// to allow access by the `update_thread` which is used to manage sending periodic universe discovery packets. #[derive(Debug)] struct SacnSourceInternal { /// Underlying UDP socket used for sending sACN packets on the network. socket: Socket, - /// The address of this SacnSourceInternal on the network. + /// The address of this `SacnSourceInternal` on the network. addr: SocketAddr, - /// The unique ID of this SacnSourceInternal. - /// It is the job of the user of the library to ensure that the cid is given on creation of the SacnSourceInternal is unique. + /// The unique ID of this `SacnSourceInternal`. + /// It is the job of the user of the library to ensure that the cid is given on creation of the `SacnSourceInternal` is unique. cid: Uuid, /// The human readable name of this source. @@ -121,7 +121,7 @@ struct SacnSourceInternal { /// This may never contain duplicate universe values. universes: Vec, - /// Flag that indicates if the SacnSourceInternal is running (the update thread should be triggering periodic discovery packets). + /// Flag that indicates if the `SacnSourceInternal` is running (the update thread should be triggering periodic discovery packets). running: bool, /// The time that the last universe discovery advert was send. @@ -132,20 +132,20 @@ struct SacnSourceInternal { } impl SacnSource { - /// Constructs a new SacnSource with the given name, binding to an IPv4 address. + /// Constructs a new `SacnSource` with the given name, binding to an IPv4 address. /// This generates a new CID automatically using random values. /// /// # Errors - /// See (with_cid_ip)[with_cid_ip] + /// See (`with_cid_ip`)[`with_cid_ip`] pub fn new_v4(name: &str) -> Result { let cid = Uuid::new_v4(); SacnSource::with_cid_v4(name, cid) } - /// Constructs a new SacnSource with the given name and specified CID binding to an IPv4 address. + /// Constructs a new `SacnSource` with the given name and specified CID binding to an IPv4 address. /// /// # Errors - /// See (with_cid_ip)[with_cid_ip] + /// See (`with_cid_ip`)[`with_cid_ip`] pub fn with_cid_v4(name: &str, cid: Uuid) -> Result { let ip = SocketAddr::new( IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)), @@ -154,20 +154,20 @@ impl SacnSource { SacnSource::with_cid_ip(name, cid, ip) } - /// Constructs a new SacnSource with the given name, binding to an IPv6 address. - /// By default this will only receive IPv6 data but IPv4 can also be enabled by calling set_ipv6_only(false). + /// Constructs a new `SacnSource` with the given name, binding to an IPv6 address. + /// By default this will only receive IPv6 data but IPv4 can also be enabled by calling `set_ipv6_only(false)`. /// /// # Errors - /// See (with_cid_ip)[with_cid_ip] + /// See (`with_cid_ip`)[`with_cid_ip`] pub fn new_v6(name: &str) -> Result { let cid = Uuid::new_v4(); SacnSource::with_cid_v6(name, cid) } - /// Constructs a new SacnSource with the given name and specified CID binding to an IPv6 address. + /// Constructs a new `SacnSource` with the given name and specified CID binding to an IPv6 address. /// /// # Errors - /// See (with_cid_ip)[with_cid_ip] + /// See (`with_cid_ip`)[`with_cid_ip`] pub fn with_cid_v6(name: &str, cid: Uuid) -> Result { let ip = SocketAddr::new( IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)), @@ -176,23 +176,23 @@ impl SacnSource { SacnSource::with_cid_ip(name, cid, ip) } - /// Constructs a new SacnSource with the given name and binding to the supplied ip. + /// Constructs a new `SacnSource` with the given name and binding to the supplied ip. /// /// # Errors - /// See (with_cid_ip)[with_cid_ip] + /// See (`with_cid_ip`)[`with_cid_ip`] pub fn with_ip(name: &str, ip: SocketAddr) -> Result { SacnSource::with_cid_ip(name, Uuid::new_v4(), ip) } - /// Constructs a new SacnSource with the given name, cid and binding to the supplied ip. + /// Constructs a new `SacnSource` with the given name, cid and binding to the supplied ip. /// /// # Errors /// Io: Returned if the underlying UDP socket cannot be created and bound or if the thread used for sending periodic /// discovery adverts fails to be created. Causes can be distinguished by looking at the error chain. /// - /// UnsupportedIpVersion: Returned if the SocketAddr is not IPv4 or IPv6. + /// `UnsupportedIpVersion`: Returned if the `SocketAddr` is not IPv4 or IPv6. /// - /// MalformedSourceName: Returned if the given source name is longer than the maximum allowed size of E131_SOURCE_NAME_FIELD_LENGTH. + /// `MalformedSourceName`: Returned if the given source name is longer than the maximum allowed size of `E131_SOURCE_NAME_FIELD_LENGTH`. pub fn with_cid_ip(name: &str, cid: Uuid, ip: SocketAddr) -> Result { if name.len() > E131_SOURCE_NAME_FIELD_LENGTH { return Err(SacnError::MalformedSourceName( @@ -232,18 +232,18 @@ impl SacnSource { /// /// This allows sending data to those universes or using them as synchronisation addresses as well as adding them to /// the list of universes that appear in universe discovery packets that are sent (depending on the - /// set_is_sending_discovery flag) periodically. + /// `set_is_sending_discovery` flag) periodically. /// - /// This is more efficient than repeated calls to register_universe as it means only 1 mutex unlock is required. + /// This is more efficient than repeated calls to `register_universe` as it means only 1 mutex unlock is required. /// /// # Arguments /// universes: The sACN universes to register for usage as data universes and/or synchronisation addresses. Note that sACN /// universes start at 1 not 0. /// /// # Errors - /// IllegalUniverse: Returned if a universe is outwith the range permitted by ANSI E1.31-2018. + /// `IllegalUniverse`: Returned if a universe is outwith the range permitted by ANSI E1.31-2018. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn register_universes(&mut self, universes: &[u16]) -> Result<()> { unlock_internal_mut(&mut self.internal)?.register_universes(universes) @@ -253,18 +253,18 @@ impl SacnSource { /// /// This allows sending data to those universes or using them as synchronisation addresses as well as adding them to /// the list of universes that appear in universe discovery packets that are sent (depending on the - /// set_is_sending_discovery flag) periodically. + /// `set_is_sending_discovery` flag) periodically. /// - /// If registering multiple universes see (register_universes)[register_universes]. + /// If registering multiple universes see (`register_universes`)[`register_universes`]. /// /// # Arguments /// universe: The sACN universe to register for usage as a data universe and/or synchronisation address. Note that sACN /// universes start at 1 not 0. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the range permitted by ANSI E1.31-2018. + /// `IllegalUniverse`: Returned if the universe is outwith the range permitted by ANSI E1.31-2018. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn register_universe(&mut self, universe: u16) -> Result<()> { unlock_internal_mut(&mut self.internal)?.register_universe(universe) @@ -274,17 +274,17 @@ impl SacnSource { /// /// # Arguments /// - /// universe: The sACN universes that the data should be set on, the data will be split over these universes with each UNIVERSE_CHANNEL_CAPACITY + /// universe: The sACN universes that the data should be set on, the data will be split over these universes with each `UNIVERSE_CHANNEL_CAPACITY` /// sized chunk sent to the next universe. /// /// data: The data that should be sent, must have a length greater than 0. /// - /// priority: The E131 priority that the data should be sent with, must be less than E131_MAX_PRIORITY (const.E131_MAX_PRIORITY.packet), - /// if a value of None is provided then the default of E131_DEFAULT_PRIORITY (const.E131_DEFAULT_PRIORITY.packet) is used. + /// priority: The E131 priority that the data should be sent with, must be less than `E131_MAX_PRIORITY` (`const.E131_MAX_PRIORITY.packet`), + /// if a value of None is provided then the default of `E131_DEFAULT_PRIORITY` (`const.E131_DEFAULT_PRIORITY.packet`) is used. /// - /// dst_ip: The destination IP, can be Ipv4 or Ipv6, None if should be sent using ip multicast. + /// `dst_ip`: The destination IP, can be Ipv4 or Ipv6, None if should be sent using ip multicast. /// - /// sync_address: The address to use for synchronisation, must be a valid universe, None indicates no synchronisation. If synchronisation is required a + /// `sync_address`: The address to use for synchronisation, must be a valid universe, None indicates no synchronisation. If synchronisation is required a /// reasonable default address to use is the first universe that this data is being sent to. /// /// As per ANSI E1.31-2018 Section 6.6.1 this method shouldn't be called at a higher refresher rate than specified in ANSI E1.11 [DMX] unless @@ -293,21 +293,21 @@ impl SacnSource { /// Note as per ANSI-E1.31-2018 Appendix B.1 it is recommended to have a small delay before sending the follow up sync packet. /// /// # Errors - /// SenderAlreadyTerminated: Returned if this method is called on an SacnReceiverInternal that has already terminated. + /// `SenderAlreadyTerminated`: Returned if this method is called on an `SacnReceiverInternal` that has already terminated. /// - /// InvalidInput: Returned if the data array has length 0 or if an insufficient number of universes for the given data are provided (each universe takes 513 bytes of data). + /// `InvalidInput`: Returned if the data array has length 0 or if an insufficient number of universes for the given data are provided (each universe takes 513 bytes of data). /// - /// InvalidPriority: Returned if the priority is greater than the allowed maximum priority of E131_MAX_PRIORITY. + /// `InvalidPriority`: Returned if the priority is greater than the allowed maximum priority of `E131_MAX_PRIORITY`. /// - /// IllegalUniverse: Returned if the universe is outwith the allowed range as specified by ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range as specified by ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on the given SacnSourceInternal. + /// `UniverseNotRegistered`: Returned if the universe is not registered on the given `SacnSourceInternal`. /// - /// ExceedUniverseCapacity: Returned if the data has a length greater than the maximum allowed within a universe (packet::UNIVERSE_CHANNEL_CAPACITY). + /// `ExceedUniverseCapacity`: Returned if the data has a length greater than the maximum allowed within a universe (`packet::UNIVERSE_CHANNEL_CAPACITY`). /// - /// Io: Returned if the data fails to be sent on the socket, see send_to(fn.send_to.Socket). + /// Io: Returned if the data fails to be sent on the socket, see `send_to(fn.send_to.Socket)`. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn send( &mut self, @@ -334,18 +334,18 @@ impl SacnSource { /// /// # Arguments /// universe: The universe of this synchronisation packet. - /// dst_ip: The destination IP address for this packet or None if it should be sent using multicast. + /// `dst_ip`: The destination IP address for this packet or None if it should be sent using multicast. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on the given SacnSourceInternal. + /// `UniverseNotRegistered`: Returned if the universe is not registered on the given `SacnSourceInternal`. /// /// Io: Returned if the packet fails to be sent using the underlying network socket. /// - /// SacnParsePackError: Returned if the sync packet fails to be packed. + /// `SacnParsePackError`: Returned if the sync packet fails to be packed. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn send_sync_packet(&mut self, universe: u16, dst_ip: Option) -> Result<()> { unlock_internal_mut(&mut self.internal)?.send_sync_packet(universe, dst_ip) @@ -354,22 +354,22 @@ impl SacnSource { /// Terminates sending on the given universe. /// /// # Errors: - /// IllegalUniverse: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on this source. + /// `UniverseNotRegistered`: Returned if the universe is not registered on this source. /// /// Io: Returned if the termination packets fail to be sent on the socket. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn terminate_stream(&mut self, universe: u16, start_code: u8) -> Result<()> { unlock_internal_mut(&mut self.internal)?.terminate_stream(universe, start_code) } - /// Returns the ACN CID device identifier of the SacnSourceInternal. + /// Returns the ACN CID device identifier of the `SacnSourceInternal`. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn cid(&self) -> Result { Ok(*unlock_internal(&self.internal)?.cid()) @@ -381,7 +381,7 @@ impl SacnSource { /// cid: The new CID identifier for this source. It is left to the user to ensure that this is always unique within the network the source is in. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn set_cid(&mut self, cid: Uuid) -> Result<()> { unlock_internal_mut(&mut self.internal)?.set_cid(cid); @@ -391,7 +391,7 @@ impl SacnSource { /// Returns the ACN source name. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn name(&self) -> Result { Ok(unlock_internal(&self.internal)?.name().into()) @@ -403,43 +403,43 @@ impl SacnSource { /// name: The new name for the source, it is left to the user to ensure this is unique within the sACN network. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. /// - /// MalformedSourceName: Returned to indicate that the given source name is longer than the maximum allowed as per E131_SOURCE_NAME_FIELD_LENGTH. + /// `MalformedSourceName`: Returned to indicate that the given source name is longer than the maximum allowed as per `E131_SOURCE_NAME_FIELD_LENGTH`. pub fn set_name(&mut self, name: &str) -> Result<()> { unlock_internal_mut(&mut self.internal)?.set_name(name) } - /// Returns true if SacnSourceInternal is in preview mode, false if not. + /// Returns true if `SacnSourceInternal` is in preview mode, false if not. /// - /// For details of preview_mode see (set_preview_mode)[set_preview_mode]. + /// For details of `preview_mode` see (`set_preview_mode`)[`set_preview_mode`]. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn preview_mode(&self) -> Result { Ok(unlock_internal(&self.internal)?.preview_mode()) } - /// Sets the value of the Preview_Data flag in packets from this SacnSource. + /// Sets the value of the `Preview_Data` flag in packets from this `SacnSource`. /// /// # Arguments - /// preview_mode: If true then all data packets from this SacnSource will have the Preview_Data flag set to true indicating that the data is not + /// `preview_mode`: If true then all data packets from this `SacnSource` will have the `Preview_Data` flag set to true indicating that the data is not /// for live output. If false then the flag will be set to false. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn set_preview_mode(&mut self, preview_mode: bool) -> Result<()> { unlock_internal_mut(&mut self.internal)?.set_preview_mode(preview_mode); Ok(()) } - /// Sets the is_sending_discovery flag to the given value. + /// Sets the `is_sending_discovery` flag to the given value. /// /// # Arguments - /// val: The new value for the is_sending_discovery flag, if true then source will send periodic universe discovery packets + /// val: The new value for the `is_sending_discovery` flag, if true then source will send periodic universe discovery packets /// and if false it won't. pub fn set_is_sending_discovery(&mut self, val: bool) { self.internal.lock().unwrap().set_is_sending_discovery(val); @@ -453,12 +453,12 @@ impl SacnSource { /// Sets the multicast time to live. /// /// # Arguments - /// multicast_ttl: The new time to live value for network packets sent using multicast. + /// `multicast_ttl`: The new time to live value for network packets sent using multicast. /// /// # Errors /// Io: Returned if the multicast TTL fails to be set on the underlying socket. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn set_multicast_ttl(&mut self, multicast_ttl: u32) -> Result<()> { unlock_internal_mut(&mut self.internal)?.set_multicast_ttl(multicast_ttl) @@ -469,7 +469,7 @@ impl SacnSource { /// # Errors /// Io: Returned if the TTL cannot be retrieved from the underlying socket. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn ttl(&self) -> Result { unlock_internal(&self.internal)?.ttl() @@ -483,7 +483,7 @@ impl SacnSource { /// # Errors /// Io: Returned if the TTL value cannot be changed. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn set_ttl(&mut self, ttl: u32) -> Result<()> { unlock_internal_mut(&mut self.internal)?.set_ttl(ttl) @@ -492,12 +492,12 @@ impl SacnSource { /// Sets if multicast loop is enabled. /// /// # Arguments: - /// multicast_loop: If true then multicast loop is enabled, if false it is not. + /// `multicast_loop`: If true then multicast loop is enabled, if false it is not. /// /// # Errors - /// Io: Returned if the set_multicast_loop option fails to be set on the socket. + /// Io: Returned if the `set_multicast_loop` option fails to be set on the socket. /// - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn set_multicast_loop_v4(&mut self, multicast_loop: bool) -> Result<()> { unlock_internal_mut(&mut self.internal)?.set_multicast_loop_v4(multicast_loop) @@ -506,7 +506,7 @@ impl SacnSource { /// Returns true if multicast loop is enabled, false if not. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn multicast_loop(&self) -> Result { unlock_internal(&self.internal)?.multicast_loop() @@ -515,14 +515,14 @@ impl SacnSource { /// Returns the universes currently registered on this source. /// /// # Errors - /// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering + /// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. pub fn universes(&self) -> Result> { Ok(unlock_internal(&self.internal)?.universes()) } } -/// By implementing the Drop trait for SacnSource it means that the user doesn't have to explicitly clean up the source +/// By implementing the Drop trait for `SacnSource` it means that the user doesn't have to explicitly clean up the source /// and if it goes out of reference it will clean itself up and send the required termination packets etc. impl Drop for SacnSource { fn drop(&mut self) { @@ -550,9 +550,9 @@ impl Drop for SacnSource { } impl SacnSourceInternal { - /// Constructs a new SacnSourceInternal with DMX START code set to 0 with specified CID and binding IP address. + /// Constructs a new `SacnSourceInternal` with DMX START code set to 0 with specified CID and binding IP address. /// - /// By default for an IPv6 address this will only receive IPv6 data but IPv4 can also be enabled by calling set_ipv6_only(false). + /// By default for an IPv6 address this will only receive IPv6 data but IPv4 can also be enabled by calling `set_ipv6_only(false)`. /// By default the TTL for ipv4 packets is 1 to keep them within the local network. /// /// # Arguments: @@ -561,9 +561,9 @@ impl SacnSourceInternal { /// ip: The address that this source should bind to. /// /// # Errors - /// Io: Returned if the underlying socket cannot be created or the IP cannot be bound to the underlying socket. See (UdpBuilder::new_v4)[fn.new_v4.UdpBuilder], (UdpBuilder::new_v6)[fn.new_v6.UdpBuilder] and (Socket::bind)[fn.bind.Socket2]. + /// Io: Returned if the underlying socket cannot be created or the IP cannot be bound to the underlying socket. See (`UdpBuilder::new_v4`)[`fn.new_v4.UdpBuilder`], (`UdpBuilder::new_v6`)[`fn.new_v6.UdpBuilder`] and (`Socket::bind`)[fn.bind.Socket2]. /// - /// UnsupportedIpVersion: Returned if the SockAddr is not IPv4 or IPv6. + /// `UnsupportedIpVersion`: Returned if the `SockAddr` is not IPv4 or IPv6. fn with_cid_ip(name: &str, cid: Uuid, ip: SocketAddr) -> Result { let socket = if ip.is_ipv4() { Socket::new(Domain::IPV4, Type::DGRAM, None).unwrap() @@ -601,13 +601,13 @@ impl SacnSourceInternal { Ok(ds) } - /// Sets the is_sending_discovery flag to the given value. + /// Sets the `is_sending_discovery` flag to the given value. /// - /// If is_sending_discovery is set to false then no discovery adverts for this source - /// will be sent otherwise (and by default) they will be sent every UNIVERSE_DISCOVERY_INTERVAL. + /// If `is_sending_discovery` is set to false then no discovery adverts for this source + /// will be sent otherwise (and by default) they will be sent every `UNIVERSE_DISCOVERY_INTERVAL`. /// /// # Arguments: - /// val: The new value of the is_sending_discovery flag. + /// val: The new value of the `is_sending_discovery` flag. fn set_is_sending_discovery(&mut self, val: bool) { self.is_sending_discovery = val; } @@ -620,7 +620,7 @@ impl SacnSourceInternal { /// universes: The sACN universe to register. Note that sACN universes start at 1 not 0. /// /// # Errors - /// See register_universe(fn.register_universe.source) for more details. + /// See `register_universe(fn.register_universe.source)` for more details. fn register_universes(&mut self, universes: &[u16]) -> Result<()> { for u in universes { self.register_universe(*u)?; @@ -633,7 +633,7 @@ impl SacnSourceInternal { /// If a universe is already registered then this method has no effect. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the allowed range, see (is_universe_in_range)[fn.is_universe_in_range.packet]. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range, see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. fn register_universe(&mut self, universe: u16) -> Result<()> { is_universe_in_range(universe)?; @@ -656,9 +656,9 @@ impl SacnSourceInternal { /// De-registers the given universe for sending with this source. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the allowed range, see (is_universe_in_range)[fn.is_universe_in_range.packet]. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range, see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. /// - /// UniverseNotFound: Returned if the given universe was never registered originally. + /// `UniverseNotFound`: Returned if the given universe was never registered originally. fn deregister_universe(&mut self, universe: u16) -> Result<()> { is_universe_in_range(universe)?; @@ -675,12 +675,12 @@ impl SacnSourceInternal { } } - /// Checks if the given universe is a valid universe to send on (within allowed range) and that it is registered with this SacnSourceInternal. + /// Checks if the given universe is a valid universe to send on (within allowed range) and that it is registered with this `SacnSourceInternal`. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the allowed range, see (is_universe_in_range)[fn.is_universe_in_range.packet]. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range, see (`is_universe_in_range`)[`fn.is_universe_in_range.packet`]. /// - /// UniverseNotRegistered: Returned if the universe is not registered on the given SacnSourceInternal. + /// `UniverseNotRegistered`: Returned if the universe is not registered on the given `SacnSourceInternal`. fn universe_allowed(&self, u: &u16) -> Result<()> { is_universe_in_range(*u)?; @@ -695,17 +695,17 @@ impl SacnSourceInternal { /// /// # Arguments /// - /// universe: The sACN universes that the data should be set on, the data will be split over these universes with each UNIVERSE_CHANNEL_CAPACITY + /// universe: The sACN universes that the data should be set on, the data will be split over these universes with each `UNIVERSE_CHANNEL_CAPACITY` /// sized chunk sent to the next universe. /// /// data: The data that should be sent, must have a length greater than 0. /// - /// priority: The E131 priority that the data should be sent with, must be less than E131_MAX_PRIORITY (const.E131_MAX_PRIORITY.packet), - /// if a value of None is provided then the default of E131_DEFAULT_PRIORITY (const.E131_DEFAULT_PRIORITY.packet) is used. + /// priority: The E131 priority that the data should be sent with, must be less than `E131_MAX_PRIORITY` (`const.E131_MAX_PRIORITY.packet`), + /// if a value of None is provided then the default of `E131_DEFAULT_PRIORITY` (`const.E131_DEFAULT_PRIORITY.packet`) is used. /// - /// dst_ip: The destination IP, can be Ipv4 or Ipv6, None if should be sent using ip multicast. + /// `dst_ip`: The destination IP, can be Ipv4 or Ipv6, None if should be sent using ip multicast. /// - /// sync_address: The address to use for synchronisation, must be a valid universe, None indicates no synchronisation. If synchronisation is required a + /// `sync_address`: The address to use for synchronisation, must be a valid universe, None indicates no synchronisation. If synchronisation is required a /// reasonable default address to use is the first universe that this data is being sent to. /// /// As per ANSI E1.31-2018 Section 6.6.1 this method shouldn't be called at a higher refresher rate than specified in ANSI E1.11 [DMX] unless @@ -714,19 +714,19 @@ impl SacnSourceInternal { /// Note as per ANSI-E1.31-2018 Appendix B.1 it is recommended to have a small delay before sending the follow up sync packet. /// /// # Errors - /// SenderAlreadyTerminated: Returned if this method is called on an SacnReceiverInternal that has already terminated. + /// `SenderAlreadyTerminated`: Returned if this method is called on an `SacnReceiverInternal` that has already terminated. /// - /// InvalidInput: Returned if the data array has length 0 or if an insufficient number of universes for the given data are provided (each universe takes 513 bytes of data). + /// `InvalidInput`: Returned if the data array has length 0 or if an insufficient number of universes for the given data are provided (each universe takes 513 bytes of data). /// - /// InvalidPriority: Returned if the priority is greater than the allowed maximum priority of E131_MAX_PRIORITY. + /// `InvalidPriority`: Returned if the priority is greater than the allowed maximum priority of `E131_MAX_PRIORITY`. /// - /// IllegalUniverse: Returned if the universe is outwith the allowed range as specified by ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range as specified by ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on the given SacnSourceInternal. + /// `UniverseNotRegistered`: Returned if the universe is not registered on the given `SacnSourceInternal`. /// - /// ExceedUniverseCapacity: Returned if the data has a length greater than the maximum allowed within a universe (packet::UNIVERSE_CHANNEL_CAPACITY). + /// `ExceedUniverseCapacity`: Returned if the data has a length greater than the maximum allowed within a universe (`packet::UNIVERSE_CHANNEL_CAPACITY`). /// - /// Io: Returned if the data fails to be sent on the socket, see send_to(fn.send_to.Socket). + /// Io: Returned if the data fails to be sent on the socket, see `send_to(fn.send_to.Socket)`. fn send( &self, universes: &[u16], @@ -788,23 +788,23 @@ impl SacnSourceInternal { /// # Arguments /// universe: The sACN universe that the data should be set on. /// - /// data: The data that should be sent, must be less than or equal in length to UNIVERSE_CHANNEL_CAPACITY(const.UNIVERSE_CHANNEL_CAPACITY.packet). + /// data: The data that should be sent, must be less than or equal in length to `UNIVERSE_CHANNEL_CAPACITY(const.UNIVERSE_CHANNEL_CAPACITY.packet)`. /// - /// priority: The E131 priority that the data should be sent with, must be less than E131_MAX_PRIORITY (const.E131_MAX_PRIORITY.packet), default E131_DEFAULT_PRIORITY. + /// priority: The E131 priority that the data should be sent with, must be less than `E131_MAX_PRIORITY` (`const.E131_MAX_PRIORITY.packet`), default `E131_DEFAULT_PRIORITY`. /// - /// dst_ip: The destination IP, can be Ipv4 or Ipv6, None if should be sent using ip multicast. + /// `dst_ip`: The destination IP, can be Ipv4 or Ipv6, None if should be sent using ip multicast. /// - /// sync_address: The address to use for synchronisation, must be a valid universe, 0 indicates no synchronisation. + /// `sync_address`: The address to use for synchronisation, must be a valid universe, 0 indicates no synchronisation. /// /// # Errors - /// InvalidInput: Returned if the priority is greater than the allowed maximum priority of E131_MAX_PRIORITY. + /// `InvalidInput`: Returned if the priority is greater than the allowed maximum priority of `E131_MAX_PRIORITY`. /// - /// ExceedUniverseCapacity: Returned if the data has a length greater than the maximum allowed within a universe. + /// `ExceedUniverseCapacity`: Returned if the data has a length greater than the maximum allowed within a universe. /// - /// IllegalUniverse: Returned if the given universe is outwith the allowed range of universes, - /// see (universe_to_ipv4_multicast_addr)[fn.universe_to_ipv4_multicast_addr.packet] and (universe_to_ipv6_multicast_addr)[fn.universe_to_ipv6_multicast_addr.packet]. + /// `IllegalUniverse`: Returned if the given universe is outwith the allowed range of universes, + /// see (`universe_to_ipv4_multicast_addr`)[`fn.universe_to_ipv4_multicast_addr.packet`] and (`universe_to_ipv6_multicast_addr`)[`fn.universe_to_ipv6_multicast_addr.packet`]. /// - /// Io: Returned if the data fails to be sent on the socket, see send_to(fn.send_to.Socket). + /// Io: Returned if the data fails to be sent on the socket, see `send_to(fn.send_to.Socket)`. fn send_universe( &self, universe: u16, @@ -886,16 +886,16 @@ impl SacnSourceInternal { /// /// # Arguments /// universe: The universe of this synchronisation packet. - /// dst_ip: The destination IP address for this packet or None if it should be sent using multicast. + /// `dst_ip`: The destination IP address for this packet or None if it should be sent using multicast. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on the given SacnSourceInternal. + /// `UniverseNotRegistered`: Returned if the universe is not registered on the given `SacnSourceInternal`. /// /// Io: Returned if the packet fails to be sent using the underlying network socket. /// - /// SacnParsePackError: Returned if the sync packet fails to be packed. + /// `SacnParsePackError`: Returned if the sync packet fails to be packed. fn send_sync_packet(&self, universe: u16, dst_ip: Option) -> Result<()> { self.universe_allowed(&universe)?; @@ -937,16 +937,16 @@ impl SacnSourceInternal { /// Sends a stream termination packet for the given universe. /// /// In normal usage this method would be called three times to send three packets for termination as per - /// ANSI E1.31-2018 Section 6.2.6, Stream_Terminated: Bit 6. + /// ANSI E1.31-2018 Section 6.2.6, `Stream_Terminated`: Bit 6. /// /// # Arguments /// universe: The universe of this synchronisation packet. - /// dst_ip: The destination IP address for this packet or None if it should be sent using multicast. + /// `dst_ip`: The destination IP address for this packet or None if it should be sent using multicast. /// /// # Errors - /// IllegalUniverse: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on the given SacnSourceInternal. + /// `UniverseNotRegistered`: Returned if the universe is not registered on the given `SacnSourceInternal`. /// /// Io: Returned if the termination packets fail to be sent on the underlying socket. fn send_terminate_stream_pkt( @@ -1007,17 +1007,17 @@ impl SacnSourceInternal { /// Terminates a universe stream. /// - /// Terminates a stream to the specified universe by sending packets with the Stream_Terminated flag set to 1. - /// Number of packets sent as per section 6.2.6 , Stream_Terminated: Bit 6 of ANSI E1.31-2018. + /// Terminates a stream to the specified universe by sending packets with the `Stream_Terminated` flag set to 1. + /// Number of packets sent as per section 6.2.6 , `Stream_Terminated`: Bit 6 of ANSI E1.31-2018. /// /// Arguments: /// universe: The universe that is being terminated. - /// start_code: used for the first byte of the otherwise empty data payload to indicate the start_code of the data. + /// `start_code`: used for the first byte of the otherwise empty data payload to indicate the `start_code` of the data. /// /// # Errors: - /// IllegalUniverse: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. + /// `IllegalUniverse`: Returned if the universe is outwith the allowed range of sACN universes as defined in ANSI E1.31-2018 Section 6.2.7. /// - /// UniverseNotRegistered: Returned if the universe is not registered on this source. + /// `UniverseNotRegistered`: Returned if the universe is not registered on this source. /// /// Io: Returned if the termination packets fail to be sent on the socket. fn terminate_stream(&mut self, universe: u16, start_code: u8) -> Result<()> { @@ -1031,10 +1031,10 @@ impl SacnSourceInternal { /// Terminates the DMX source. /// - /// This includes terminating each registered universe with the start_code given. + /// This includes terminating each registered universe with the `start_code` given. /// /// Arguments: - /// start_code: used for the first byte of the otherwise empty data payload to indicate the start_code of the data. + /// `start_code`: used for the first byte of the otherwise empty data payload to indicate the `start_code` of the data. /// /// # Errors: /// Io: Returned if the termination packets fail to be sent on the underlying socket. @@ -1052,7 +1052,7 @@ impl SacnSourceInternal { /// This packet may be broken down into multiple pages internally resulting in multiple UDP packets. /// /// # Errors - /// See (send_universe_discovery_detailed)[fn.send_universe_discovery_detailed.source]. + /// See (`send_universe_discovery_detailed`)[`fn.send_universe_discovery_detailed.source`]. fn send_universe_discovery(&self) -> Result<()> { // Given a u16 universe field and self.universes containing no duplicates it means that the maximum total number of universes (65536, ignoring sACN restrictions) // divided by the number of universes per page (512) is 128 which therefore fits into the discovery universe 8 bit page field making this cast safe. @@ -1081,14 +1081,14 @@ impl SacnSourceInternal { /// /// page: The page number of this universe discovery page. /// - /// last_page: The last page that is expected as part of this universe discovery packet. + /// `last_page`: The last page that is expected as part of this universe discovery packet. /// /// universes: The universes to include on the page. /// /// # Errors /// Io: Returned if the discovery packet fails to be sent on the socket. /// - /// SacnParsePackError: Returned if the discovery packet cannot be packed to send. + /// `SacnParsePackError`: Returned if the discovery packet cannot be packed to send. fn send_universe_discovery_detailed( &self, page: u8, @@ -1122,7 +1122,7 @@ impl SacnSourceInternal { Ok(()) } - /// Returns the ACN CID device identifier of the SacnSourceInternal. + /// Returns the ACN CID device identifier of the `SacnSourceInternal`. fn cid(&self) -> &Uuid { &self.cid } @@ -1146,7 +1146,7 @@ impl SacnSourceInternal { /// name: The new name for the source, it is left to the user to ensure this is unique within the sACN network. /// /// # Errors - /// MalformedSourceName: Returned to indicate that the given source name is longer than the maximum allowed as per E131_SOURCE_NAME_FIELD_LENGTH. + /// `MalformedSourceName`: Returned to indicate that the given source name is longer than the maximum allowed as per `E131_SOURCE_NAME_FIELD_LENGTH`. fn set_name(&mut self, name: &str) -> Result<()> { if name.len() > E131_SOURCE_NAME_FIELD_LENGTH { return Err(SacnError::MalformedSourceName( @@ -1158,15 +1158,15 @@ impl SacnSourceInternal { Ok(()) } - /// Returns if SacnSourceInternal is in preview mode. + /// Returns if `SacnSourceInternal` is in preview mode. fn preview_mode(&self) -> bool { self.preview_data } - /// Sets the value of the Preview_Data flag in packets from this SacnSourceInternal. + /// Sets the value of the `Preview_Data` flag in packets from this `SacnSourceInternal`. /// /// # Arguments - /// preview_mode: If true then all data packets from this SacnSourceInternal will have the Preview_Data flag set to true indicating that the data is not + /// `preview_mode`: If true then all data packets from this `SacnSourceInternal` will have the `Preview_Data` flag set to true indicating that the data is not /// for live output. If false then the flag will be set to false. fn set_preview_mode(&mut self, preview_mode: bool) { self.preview_data = preview_mode; @@ -1175,7 +1175,7 @@ impl SacnSourceInternal { /// Sets the multicast time to live. /// /// # Arguments - /// multicast_ttl: The new time to live value for network packets sent using multicast. + /// `multicast_ttl`: The new time to live value for network packets sent using multicast. /// /// # Errors /// Io: Returned if the multicast TTL fails to be set on the underlying socket. @@ -1210,10 +1210,10 @@ impl SacnSourceInternal { /// Sets if multicast loop is enabled. /// /// # Arguments: - /// multicast_loop: If true then multicast loop is enabled, if false it is not. + /// `multicast_loop`: If true then multicast loop is enabled, if false it is not. /// /// # Errors - /// Io: Returned if the set_multicast_loop option fails to be set on the socket. + /// Io: Returned if the `set_multicast_loop` option fails to be set on the socket. fn set_multicast_loop_v4(&self, multicast_loop: bool) -> Result<()> { Ok(self.socket.set_multicast_loop_v4(multicast_loop)?) } @@ -1229,17 +1229,17 @@ impl SacnSourceInternal { } } -/// Returns the locked internal SacnSourceInternal used within the SacnSource. +/// Returns the locked internal `SacnSourceInternal` used within the `SacnSource`. /// /// This centralises the locking of the source to a single point within the code allowing any changes to the mechanism to be made in one place. /// -/// This differs to (unlock_internal_mut) as it takes an immutable reference to internal. +/// This differs to (`unlock_internal_mut`) as it takes an immutable reference to internal. /// /// # Arguments -/// internal: The SacnSourceInternal to unlock encapsulated within an Arc and Mutex. +/// internal: The `SacnSourceInternal` to unlock encapsulated within an Arc and Mutex. /// /// # Errors -/// SourceCorrupt: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering +/// `SourceCorrupt`: Returned if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. fn unlock_internal( internal: &Arc>, @@ -1256,17 +1256,17 @@ fn unlock_internal( } } -/// Returns the locked internal SacnSourceInternal used within the SacnSource. +/// Returns the locked internal `SacnSourceInternal` used within the `SacnSource`. /// /// This centralises the locking of the source to a single point within the code allowing any changes to the mechanism to be made in one place. /// -/// This differs to (unlock_internal) as it takes an mutable reference to internal. +/// This differs to (`unlock_internal`) as it takes an mutable reference to internal. /// /// # Arguments -/// internal: The SacnSourceInternal to unlock encapsulated within an Arc and Mutex. +/// internal: The `SacnSourceInternal` to unlock encapsulated within an Arc and Mutex. /// /// # Errors -/// Returns an SourceCorrupt error if the Mutex used to control access to the internal sender is poisoned by a thread encountering +/// Returns an `SourceCorrupt` error if the Mutex used to control access to the internal sender is poisoned by a thread encountering /// a panic while accessing causing the source to be left in a potentially inconsistent state. fn unlock_internal_mut( internal: &mut Arc>, @@ -1288,12 +1288,12 @@ fn unlock_internal_mut( /// Is responsible for sending the periodic universe discovery packets. /// /// # Arguments: -/// src: A reference to the SacnSourceInternal for which to send the universe discovery packet with/from. +/// src: A reference to the `SacnSourceInternal` for which to send the universe discovery packet with/from. /// /// # Errors -/// Returns a SourceCorrupt error if the internal source mutex has been corrupted, see (unlock_internal)[unlock_internal]. +/// Returns a `SourceCorrupt` error if the internal source mutex has been corrupted, see (`unlock_internal`)[`unlock_internal`]. /// -/// Returns an error if a discovery packet cannot be sent, see (send_universe_discovery)[fn.send_universe_discovery.source]. +/// Returns an error if a discovery packet cannot be sent, see (`send_universe_discovery`)[`fn.send_universe_discovery.source`]. fn perform_periodic_update(src: &mut Arc>) -> Result<()> { let mut unwrap_src = unlock_internal_mut(src)?; if unwrap_src.is_sending_discovery From d5f53c31ee8cd30696f3db469018121822e66d5f Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sat, 3 Jan 2026 17:11:43 -0800 Subject: [PATCH 02/11] add embark lints to config --- .cargo/config.toml | 82 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/.cargo/config.toml b/.cargo/config.toml index 747a437..ca2a5ff 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,2 +1,82 @@ [alias] -test_ip = "test --test ipv4_tests -- --ignored --test-threads=1" \ No newline at end of file +test_ip = "test --test ipv4_tests -- --ignored --test-threads=1" + +[target.'cfg(all())'] +rustflags = [ + # BEGIN - Embark standard lints v6 for Rust 1.55+ + # do not change or add/remove here, but one can add exceptions after this section + # for more info see: + "-Dunsafe_code", + "-Wclippy::all", + "-Wclippy::await_holding_lock", + "-Wclippy::char_lit_as_u8", + "-Wclippy::checked_conversions", + "-Wclippy::dbg_macro", + "-Wclippy::debug_assert_with_mut_call", + "-Wclippy::doc_markdown", + "-Wclippy::empty_enum", + "-Wclippy::enum_glob_use", + "-Wclippy::exit", + "-Wclippy::expl_impl_clone_on_copy", + "-Wclippy::explicit_deref_methods", + "-Wclippy::explicit_into_iter_loop", + "-Wclippy::fallible_impl_from", + "-Wclippy::filter_map_next", + "-Wclippy::flat_map_option", + "-Wclippy::float_cmp_const", + "-Wclippy::fn_params_excessive_bools", + "-Wclippy::from_iter_instead_of_collect", + "-Wclippy::if_let_mutex", + "-Wclippy::implicit_clone", + "-Wclippy::imprecise_flops", + "-Wclippy::inefficient_to_string", + "-Wclippy::invalid_upcast_comparisons", + "-Wclippy::large_digit_groups", + "-Wclippy::large_stack_arrays", + "-Wclippy::large_types_passed_by_value", + "-Wclippy::let_unit_value", + "-Wclippy::linkedlist", + "-Wclippy::lossy_float_literal", + "-Wclippy::macro_use_imports", + "-Wclippy::manual_ok_or", + "-Wclippy::map_err_ignore", + "-Wclippy::map_flatten", + "-Wclippy::map_unwrap_or", + "-Wclippy::match_on_vec_items", + "-Wclippy::match_same_arms", + "-Wclippy::match_wild_err_arm", + "-Wclippy::match_wildcard_for_single_variants", + "-Wclippy::mem_forget", + "-Wclippy::mismatched_target_os", + "-Wclippy::missing_enforced_import_renames", + "-Wclippy::mut_mut", + "-Wclippy::mutex_integer", + "-Wclippy::needless_borrow", + "-Wclippy::needless_continue", + "-Wclippy::needless_for_each", + "-Wclippy::option_option", + "-Wclippy::path_buf_push_overwrite", + "-Wclippy::ptr_as_ptr", + "-Wclippy::rc_mutex", + "-Wclippy::ref_option_ref", + "-Wclippy::rest_pat_in_fully_bound_structs", + "-Wclippy::same_functions_in_if_condition", + "-Wclippy::semicolon_if_nothing_returned", + "-Wclippy::single_match_else", + "-Wclippy::string_add_assign", + "-Wclippy::string_add", + "-Wclippy::string_lit_as_bytes", + "-Wclippy::string_to_string", + "-Wclippy::todo", + "-Wclippy::trait_duplication_in_bounds", + "-Wclippy::unimplemented", + "-Wclippy::unnested_or_patterns", + "-Wclippy::unused_self", + "-Wclippy::useless_transmute", + "-Wclippy::verbose_file_reads", + "-Wclippy::zero_sized_map_values", + "-Wfuture_incompatible", + "-Wnonstandard_style", + "-Wrust_2018_idioms", + # END - Embark standard lints v6 for Rust 1.55+ +] From 6fff093b695adb547b87a1e346dd62f7c4a3a8e1 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 13:37:40 -0800 Subject: [PATCH 03/11] add minimum supported version 1.88 due to `if let` chains --- Cargo.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.toml b/Cargo.toml index 5bad785..3685904 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,6 +3,7 @@ name = "sacn" description = "A Rust implementation of the ANSI E1.31 Streaming ACN protocol, tested against protocol version ANSI E1.31-2018." version = "0.11.1" edition = "2024" +rust-version = "1.88" readme = "README.md" keywords = ["acn", "sacn", "dmx", "e131", "ansi"] authors = ["Lukas Schmierer ", "Paul Lancaster "] From d063afb99b53105450097ecbd65a663ecb571611 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 13:39:02 -0800 Subject: [PATCH 04/11] clippy::unused_extern_crates --- src/lib.rs | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index acd6939..020a051 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -195,19 +195,6 @@ pub mod sacn_parse_pack_error; /// The errors used within the sACN crate, parse/pack errors are seperated out into sacn_parse_pack_error. pub mod error; -extern crate libc; -/// The library is built on top of socket2 to provide the underlying UDP networking interface. -extern crate socket2; - -/// The core crate is used for string processing during packet parsing/packing as well as to provide access to the Hash trait. -extern crate core; - -/// The byteorder crate is used for marshalling data on/off the network in Network Byte Order. -extern crate byteorder; - -/// The uuid crate is used for working with/generating UUIDs which sACN uses as part of the cid field in the protocol. -extern crate uuid; - /// The packet module handles the sACN packets including parsing/packing and sACN related constants. pub mod packet; From f9385b53975233b5b74f5372cf18323a068d49bc Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 13:42:48 -0800 Subject: [PATCH 05/11] clippy::elided_lifetimes_in_paths --- src/receive.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/receive.rs b/src/receive.rs index 2144d9c..0a38307 100644 --- a/src/receive.rs +++ b/src/receive.rs @@ -247,7 +247,7 @@ struct UniversePage { /// Allows debug ({:?}) printing of the `SacnReceiver`, used during debugging. impl fmt::Debug for SacnReceiver { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "{:?}", self.receiver)?; write!(f, "{:?}", self.waiting_data)?; write!(f, "{:?}", self.universes)?; @@ -540,8 +540,8 @@ impl SacnReceiver { let mut buf: [u8; RCV_BUF_DEFAULT_SIZE] = [0; RCV_BUF_DEFAULT_SIZE]; match self.receiver.recv(&mut buf) { Ok(pkt) => { - let pdu: E131RootLayer = pkt.pdu; - let data: E131RootLayerData = pdu.data; + let pdu = pkt.pdu; + let data = pdu.data; let res = match data { DataPacket(d) => self.handle_data_packet(pdu.cid, d)?, SynchronizationPacket(s) => self.handle_sync_packet(pdu.cid, s)?, @@ -719,7 +719,7 @@ impl SacnReceiver { fn handle_data_packet( &mut self, cid: Uuid, - data_pkt: DataPacketFramingLayer, + data_pkt: DataPacketFramingLayer<'_>, ) -> Result>> { if data_pkt.preview_data && !self.process_preview_data { // Don't process preview data unless receiver has process_preview_data flag set. @@ -937,9 +937,9 @@ impl SacnReceiver { fn handle_universe_discovery_packet( &mut self, cid: Uuid, - discovery_pkt: UniverseDiscoveryPacketFramingLayer, + discovery_pkt: UniverseDiscoveryPacketFramingLayer<'_>, ) -> Option { - let data: UniverseDiscoveryPacketUniverseDiscoveryLayer = discovery_pkt.data; + let data = discovery_pkt.data; let page: u8 = data.page; let last_page: u8 = data.last_page; From 585d6d558debed0b4e56fea0a65ebf8f80d87b57 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 13:54:04 -0800 Subject: [PATCH 06/11] test and example clippy --- examples/demo_rcv/src/main.rs | 2 -- examples/demo_src/src/main.rs | 2 -- examples/simple-receiver.rs | 3 --- examples/sine-wave-sender.rs | 2 -- src/receive.rs | 6 +++--- tests/data_parse_tests.rs | 3 --- tests/discovery_parse_tests.rs | 3 --- tests/ipv4_tests.rs | 4 ---- tests/ipv6_tests.rs | 4 ---- tests/src_tests.rs | 3 --- tests/sync_parse_tests.rs | 3 --- 11 files changed, 3 insertions(+), 32 deletions(-) diff --git a/examples/demo_rcv/src/main.rs b/examples/demo_rcv/src/main.rs index b753473..ac93d1f 100644 --- a/examples/demo_rcv/src/main.rs +++ b/examples/demo_rcv/src/main.rs @@ -28,8 +28,6 @@ pub mod error; use error::errors::{DemoError, Result}; -extern crate sacn; - use sacn::packet::ACN_SDT_MULTICAST_PORT; use sacn::receive::{DMXData, DiscoveredSacnSource, SacnReceiver}; diff --git a/examples/demo_src/src/main.rs b/examples/demo_src/src/main.rs index e32a295..2c22363 100644 --- a/examples/demo_src/src/main.rs +++ b/examples/demo_src/src/main.rs @@ -30,8 +30,6 @@ pub mod error; use error::errors::Result; -extern crate sacn; - use sacn::packet::{ACN_SDT_MULTICAST_PORT, UNIVERSE_CHANNEL_CAPACITY}; use sacn::source::SacnSource; diff --git a/examples/simple-receiver.rs b/examples/simple-receiver.rs index dd37d83..d27b314 100644 --- a/examples/simple-receiver.rs +++ b/examples/simple-receiver.rs @@ -7,9 +7,6 @@ // // Simply listens on the given universe and shows the current data. -extern crate crossterm; -extern crate sacn; - use crossterm::style::Print; use crossterm::{cursor, execute, queue, terminal}; use std::io::{self, Stdout, Write}; diff --git a/examples/sine-wave-sender.rs b/examples/sine-wave-sender.rs index da046aa..98f8542 100644 --- a/examples/sine-wave-sender.rs +++ b/examples/sine-wave-sender.rs @@ -7,8 +7,6 @@ // // Uses the sACN library to send a sine wave on all channels on universe 1 to localhost. -extern crate sacn; - use sacn::packet::{ACN_SDT_MULTICAST_PORT, UNIVERSE_CHANNEL_CAPACITY}; use sacn::source::SacnSource; diff --git a/src/receive.rs b/src/receive.rs index 0a38307..cde7e73 100644 --- a/src/receive.rs +++ b/src/receive.rs @@ -2178,7 +2178,7 @@ mod test { let last_page: u8 = 0; let universes: Vec = vec![0, 1, 2, 3, 4, 5]; - let discovery_pkt: UniverseDiscoveryPacketFramingLayer = + let discovery_pkt: UniverseDiscoveryPacketFramingLayer<'_> = UniverseDiscoveryPacketFramingLayer { source_name: name.into(), @@ -2231,7 +2231,7 @@ mod test { universes_page_2.push(i); } - let discovery_pkt_1: UniverseDiscoveryPacketFramingLayer = + let discovery_pkt_1: UniverseDiscoveryPacketFramingLayer<'_> = UniverseDiscoveryPacketFramingLayer { source_name: name.into(), @@ -2247,7 +2247,7 @@ mod test { }, }; - let discovery_pkt_2: UniverseDiscoveryPacketFramingLayer = + let discovery_pkt_2: UniverseDiscoveryPacketFramingLayer<'_> = UniverseDiscoveryPacketFramingLayer { source_name: name.into(), diff --git a/tests/data_parse_tests.rs b/tests/data_parse_tests.rs index ebab81f..8d884ee 100644 --- a/tests/data_parse_tests.rs +++ b/tests/data_parse_tests.rs @@ -9,9 +9,6 @@ // // This file was adapted as part of a University of St Andrews Computer Science BSC Senior Honours Dissertation Project. -extern crate sacn; -extern crate uuid; - #[cfg(test)] pub mod data_parse_tests { diff --git a/tests/discovery_parse_tests.rs b/tests/discovery_parse_tests.rs index 2eceae0..2d186a1 100644 --- a/tests/discovery_parse_tests.rs +++ b/tests/discovery_parse_tests.rs @@ -1,8 +1,5 @@ #![cfg_attr(rustfmt, rustfmt_skip)] -extern crate sacn; -extern crate uuid; - #[cfg(test)] pub mod discovery_parse_tests { diff --git a/tests/ipv4_tests.rs b/tests/ipv4_tests.rs index 717d1f2..7cf5c28 100644 --- a/tests/ipv4_tests.rs +++ b/tests/ipv4_tests.rs @@ -8,10 +8,6 @@ // // This file was created as part of a University of St Andrews Computer Science BSC Senior Honours Dissertation Project. -extern crate sacn; -extern crate uuid; -extern crate socket2; - use std::io::Read; use std::{array, thread}; use std::thread::sleep; diff --git a/tests/ipv6_tests.rs b/tests/ipv6_tests.rs index ec310da..55acd34 100644 --- a/tests/ipv6_tests.rs +++ b/tests/ipv6_tests.rs @@ -7,10 +7,6 @@ // // This file was created as part of a University of St Andrews Computer Science BSC Senior Honours Dissertation Project. -extern crate sacn; -extern crate socket2; -extern crate uuid; - pub mod ipv4_tests; const TEST_NETWORK_INTERFACE_IPV6: [&'static str; 3] = [ diff --git a/tests/src_tests.rs b/tests/src_tests.rs index 83592c5..d456ea9 100644 --- a/tests/src_tests.rs +++ b/tests/src_tests.rs @@ -7,9 +7,6 @@ // // This file was created as part of a University of St Andrews Computer Science BSC Senior Honours Dissertation Project. -extern crate sacn; -extern crate uuid; - use sacn::error::errors::*; use sacn::packet::*; diff --git a/tests/sync_parse_tests.rs b/tests/sync_parse_tests.rs index 6cf4fb9..6081f62 100644 --- a/tests/sync_parse_tests.rs +++ b/tests/sync_parse_tests.rs @@ -1,6 +1,3 @@ -extern crate sacn; -extern crate uuid; - #[cfg(test)] pub mod sync_parse_tests { From ce5e4446905ea128042aa702744b08d432550f36 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 13:54:35 -0800 Subject: [PATCH 07/11] cargo fmt --- src/receive.rs | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/src/receive.rs b/src/receive.rs index cde7e73..2d83fa8 100644 --- a/src/receive.rs +++ b/src/receive.rs @@ -202,7 +202,7 @@ pub struct DiscoveredSacnSource { /// The name of the source, no protocol guarantee this will be unique but if it isn't then universe discovery may not work correctly. pub name: String, - /// The unique CID of the source. This should be unique across all devices on the network. + /// The unique CID of the source. This should be unique across all devices on the network. pub cid: Uuid, /// The time at which the discovered source was last updated / a discovery packet was received by the source. @@ -808,8 +808,7 @@ impl SacnReceiver { let _ = self.sequences.remove_seq_numbers(src_cid, universe); // As with sequence numbers the source might not be found which is acceptable. - if let Some(index) = find_discovered_src(&self.discovered_sources, &src_cid) - { + if let Some(index) = find_discovered_src(&self.discovered_sources, &src_cid) { self.discovered_sources[index].terminate_universe(universe); } } @@ -930,9 +929,9 @@ impl SacnReceiver { /// Returns the source name if a source was fully discovered or None if the source was only partially discovered. /// /// Arguments: - /// + /// /// cid: the source CID. - /// + /// /// `discovery_pkt`: The universe discovery part of the universe discovery packet to handle. fn handle_universe_discovery_packet( &mut self, @@ -952,10 +951,7 @@ impl SacnReceiver { }; // See if some pages that belong to the source that this page belongs to have already been received. - match find_discovered_src( - &self.partially_discovered_sources, - &cid - ) { + match find_discovered_src(&self.partially_discovered_sources, &cid) { Some(index) => { // Some pages have already been received from this source. self.partially_discovered_sources[index] @@ -1034,9 +1030,9 @@ impl Drop for SacnReceiver { /// returns the index of the src in the Vec or None if not found. /// /// Arguments: -/// +/// /// srcs: The Vec of `DiscoveredSacnSources` to search. -/// +/// /// cid: The CID (uuid) of the source to find. fn find_discovered_src(srcs: &[DiscoveredSacnSource], cid: &Uuid) -> Option { (0..srcs.len()).find(|&i| srcs[i].cid == *cid) @@ -2262,11 +2258,13 @@ mod test { universes: universes_page_2.clone().into(), }, }; - let res: Option = dmx_rcv.handle_universe_discovery_packet(src_cid, discovery_pkt_1); + let res: Option = + dmx_rcv.handle_universe_discovery_packet(src_cid, discovery_pkt_1); assert!(res.is_none()); // Should be none because first packet isn't complete as its only the first page. - let res2: Option = dmx_rcv.handle_universe_discovery_packet(src_cid, discovery_pkt_2); + let res2: Option = + dmx_rcv.handle_universe_discovery_packet(src_cid, discovery_pkt_2); assert!(res2.is_some()); // Source should be discovered because the second and last page is now received. assert_eq!(res2.unwrap(), name); From 2f7cf487ae95cf109f56c18510469fb59643e5a2 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 14:36:17 -0800 Subject: [PATCH 08/11] clippy --- src/packet.rs | 14 ++++-- src/receive.rs | 119 +++++++++++++++++++++++-------------------------- src/source.rs | 28 +++++------- 3 files changed, 76 insertions(+), 85 deletions(-) diff --git a/src/packet.rs b/src/packet.rs index ffffd00..2ca317b 100644 --- a/src/packet.rs +++ b/src/packet.rs @@ -1471,8 +1471,12 @@ fn parse_universe_list<'a>(buf: &[u8], length: usize) -> Result> if buf.len() < length * E131_UNIVERSE_FIELD_LENGTH { return Err(SacnError::SacnParsePackError( - ParsePacketError::ParseInsufficientData( - format!("The given buffer of length {} bytes cannot be parsed into the given number of universes {}", buf.len(), length).to_string()))); + ParsePacketError::ParseInsufficientData(format!( + "The given buffer of length {} bytes cannot be parsed into the given number of universes {}", + buf.len(), + length + )), + )); } while i < (length * E131_UNIVERSE_FIELD_LENGTH) { @@ -1485,8 +1489,10 @@ fn parse_universe_list<'a>(buf: &[u8], length: usize) -> Result> i += E131_UNIVERSE_FIELD_LENGTH; // Jump to the next universe. } else { return Err(SacnError::SacnParsePackError( - ParsePacketError::ParseInvalidUniverseOrder( - format!("Universe {u} is out of order, discovery packet universe list must be in accending order!").to_string()))); + ParsePacketError::ParseInvalidUniverseOrder(format!( + "Universe {u} is out of order, discovery packet universe list must be in accending order!" + )), + )); } } diff --git a/src/receive.rs b/src/receive.rs index 2d83fa8..1cbfa94 100644 --- a/src/receive.rs +++ b/src/receive.rs @@ -21,7 +21,10 @@ use socket2::{Domain, Protocol, SockAddr, Socket, Type}; /// Mass import as a very large amount of packet is used here (upwards of 20 items) and this is much cleaner. -use crate::packet::{E131RootLayerData::*, *}; +use crate::packet::{ + E131RootLayerData::{DataPacket, SynchronizationPacket, UniverseDiscoveryPacket}, + *, +}; /// Same reasoning as for packet meaning all sacn errors are imported. use crate::error::errors::*; @@ -401,17 +404,15 @@ impl SacnReceiver { } for u in universes { - match self.universes.binary_search(u) { - Err(i) => { - // Value not found, i is the position it should be inserted - self.universes.insert(i, *u); + if let Err(i) = self.universes.binary_search(u) { + // Value not found, i is the position it should be inserted + self.universes.insert(i, *u); - if self.is_multicast_enabled() { - self.receiver.listen_multicast_universe(*u)?; - } - } - Ok(_) => { // If value found then don't insert to avoid duplicates. + if self.is_multicast_enabled() { + self.receiver.listen_multicast_universe(*u)?; } + } else { + // If value found then don't insert to avoid duplicates. } } @@ -756,7 +757,7 @@ impl SacnReceiver { let vals: Vec = data_pkt.data.property_values.into_owned(); let dmx_data: DMXData = DMXData { universe: data_pkt.universe, - values: vals.to_vec(), + values: vals.clone(), sync_uni: data_pkt.synchronization_address, priority: data_pkt.priority, src_cid: Some(cid), @@ -773,7 +774,7 @@ impl SacnReceiver { let vals: Vec = data_pkt.data.property_values.into_owned(); let dmx_data: DMXData = DMXData { universe: data_pkt.universe, - values: vals.to_vec(), + values: vals.clone(), sync_uni: data_pkt.synchronization_address, priority: data_pkt.priority, src_cid: Some(cid), @@ -951,38 +952,35 @@ impl SacnReceiver { }; // See if some pages that belong to the source that this page belongs to have already been received. - match find_discovered_src(&self.partially_discovered_sources, &cid) { - Some(index) => { - // Some pages have already been received from this source. - self.partially_discovered_sources[index] - .pages - .push(uni_page); - self.partially_discovered_sources[index].last_updated = Instant::now(); - if self.partially_discovered_sources[index].has_all_pages() { - let discovered_src: DiscoveredSacnSource = - self.partially_discovered_sources.remove(index); - self.update_discovered_srcs(discovered_src); - return Some(discovery_pkt.source_name.to_string()); - } + if let Some(index) = find_discovered_src(&self.partially_discovered_sources, &cid) { + // Some pages have already been received from this source. + self.partially_discovered_sources[index] + .pages + .push(uni_page); + self.partially_discovered_sources[index].last_updated = Instant::now(); + if self.partially_discovered_sources[index].has_all_pages() { + let discovered_src: DiscoveredSacnSource = + self.partially_discovered_sources.remove(index); + self.update_discovered_srcs(discovered_src); + return Some(discovery_pkt.source_name.to_string()); } - None => { - // This is the first page received from this source. - let discovered_src: DiscoveredSacnSource = DiscoveredSacnSource { - name: discovery_pkt.source_name.to_string(), - cid, - last_page, - pages: vec![uni_page], - last_updated: Instant::now(), - }; + } else { + // This is the first page received from this source. + let discovered_src: DiscoveredSacnSource = DiscoveredSacnSource { + name: discovery_pkt.source_name.to_string(), + cid, + last_page, + pages: vec![uni_page], + last_updated: Instant::now(), + }; - if page == 0 && page == last_page { - // Indicates that this is a single page universe discovery packet. - self.update_discovered_srcs(discovered_src); - return Some(discovery_pkt.source_name.to_string()); - } else { - // Indicates that this is a page in a set of pages as part of a sources universe discovery. - self.partially_discovered_sources.push(discovered_src); - } + if page == 0 && page == last_page { + // Indicates that this is a single page universe discovery packet. + self.update_discovered_srcs(discovered_src); + return Some(discovery_pkt.source_name.to_string()); + } else { + // Indicates that this is a page in a set of pages as part of a sources universe discovery. + self.partially_discovered_sources.push(discovered_src); } } @@ -1308,7 +1306,7 @@ impl SacnNetworkReceiver { impl Clone for DMXData { fn clone(&self) -> DMXData { - let new_vals = self.values.to_vec(); // https://stackoverflow.com/questions/21369876/what-is-the-idiomatic-rust-way-to-copy-clone-a-vector-in-a-parameterized-functio (26/12/2019) + let new_vals = self.values.clone(); // https://stackoverflow.com/questions/21369876/what-is-the-idiomatic-rust-way-to-copy-clone-a-vector-in-a-parameterized-functio (26/12/2019) DMXData { universe: self.universe, values: new_vals, @@ -1361,16 +1359,10 @@ impl DiscoveredSacnSource { // https://rust-lang-nursery.github.io/rust-cookbook/algorithms/sorting.html (31/12/2019) self.pages.sort_by(|a, b| a.page.cmp(&b.page)); for i in 0..=self.last_page { - if self - .pages - .get(i as usize) - .map(|p| p.page != i) - .unwrap_or(true) - { + if self.pages.get(i as usize).is_none_or(|p| p.page != i) { return false; } } - true } @@ -1388,7 +1380,7 @@ impl DiscoveredSacnSource { /// Removes the given universe from the list of universes being sent by this discovered source. pub fn terminate_universe(&mut self, universe: u16) { for p in &mut self.pages { - p.universes.retain(|x| *x != universe) + p.universes.retain(|x| *x != universe); } } } @@ -1622,7 +1614,9 @@ fn join_win_multicast(socket: &Socket, addr: SockAddr, interface_addr: IpAddr) - } }, x => { - return Err(SacnError::UnsupportedIpVersion(format!("IP version not recognised as AF_INET (Ipv4) or AF_INET6 (Ipv6) - family value (as i32): {x}").to_string())); + return Err(SacnError::UnsupportedIpVersion(format!( + "IP version not recognised as AF_INET (Ipv4) or AF_INET6 (Ipv6) - family value (as i32): {x}" + ))); } }; @@ -1672,7 +1666,9 @@ fn leave_win_multicast(socket: &Socket, addr: SockAddr) -> Result<()> { } }, x => { - return Err(SacnError::UnsupportedIpVersion(format!("IP version not recognised as AF_INET (Ipv4) or AF_INET6 (Ipv6) - family value (as i32): {x}").to_string())); + return Err(SacnError::UnsupportedIpVersion(format!( + "IP version not recognised as AF_INET (Ipv4) or AF_INET6 (Ipv6) - family value (as i32): {x}" + ))); } }; @@ -1888,17 +1884,14 @@ fn check_seq_number( let expected_seq = match src_sequences.get(&cid) { Some(src) => { - match src.get(&universe) { + if let Some(s) = src.get(&universe) { // Get the sequence number within the source for the specific universe. - Some(s) => { - // Indicates that the source / universe combination is known. - *s - } - None => { - // Indicates that this is the first time (or the first time since it timed out) the universe has been received from this source. - let initial_seq_num = sequence_number.wrapping_sub(1); - TimedStampedSeqNo::new(initial_seq_num, Instant::now()) - } + // Indicates that the source / universe combination is known. + *s + } else { + // Indicates that this is the first time (or the first time since it timed out) the universe has been received from this source. + let initial_seq_num = sequence_number.wrapping_sub(1); + TimedStampedSeqNo::new(initial_seq_num, Instant::now()) } } None => { diff --git a/src/source.rs b/src/source.rs index 3f8b5bf..e77727f 100644 --- a/src/source.rs +++ b/src/source.rs @@ -211,15 +211,11 @@ impl SacnSource { update_thread: Some(trd_builder.spawn(move || { while trd_src.lock().unwrap().running { thread::sleep(DEFAULT_POLL_PERIOD); - match perform_periodic_update(&mut trd_src) { - Err(e) => { - println!("Periodic error: {e:?}"); - } - - _ => { - // In-case of an error on the discovery thread the source continues to operate and tries again. - // As no unsafe code blocks are used the rust compiler guarantees this is memory safe. - } + if let Err(e) = perform_periodic_update(&mut trd_src) { + println!("Periodic error: {e:?}"); + } else { + // In-case of an error on the discovery thread the source continues to operate and tries again. + // As no unsafe code blocks are used the rust compiler guarantees this is memory safe. } } })?), @@ -639,17 +635,13 @@ impl SacnSourceInternal { if self.universes.is_empty() { self.universes.push(universe); + } else if let Err(i) = self.universes.binary_search(&universe) { + // Value not found, i is the position it should be inserted + self.universes.insert(i, universe); } else { - match self.universes.binary_search(&universe) { - Err(i) => { - // Value not found, i is the position it should be inserted - self.universes.insert(i, universe); - } - Ok(_) => { - // If value found then don't insert to avoid duplicates. - } - } + // If value found then don't insert to avoid duplicates. } + Ok(()) } From 33f8d19a10e72c2c6b2c6016228a58eb31a6f551 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 14:38:25 -0800 Subject: [PATCH 09/11] Update config.toml --- .cargo/config.toml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.cargo/config.toml b/.cargo/config.toml index ca2a5ff..14d3089 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -29,6 +29,8 @@ rustflags = [ "-Wclippy::if_let_mutex", "-Wclippy::implicit_clone", "-Wclippy::imprecise_flops", + # to be enabled at a later date + # "-Wclippy::indexing_slicing", "-Wclippy::inefficient_to_string", "-Wclippy::invalid_upcast_comparisons", "-Wclippy::large_digit_groups", @@ -42,12 +44,10 @@ rustflags = [ "-Wclippy::map_err_ignore", "-Wclippy::map_flatten", "-Wclippy::map_unwrap_or", - "-Wclippy::match_on_vec_items", "-Wclippy::match_same_arms", "-Wclippy::match_wild_err_arm", "-Wclippy::match_wildcard_for_single_variants", "-Wclippy::mem_forget", - "-Wclippy::mismatched_target_os", "-Wclippy::missing_enforced_import_renames", "-Wclippy::mut_mut", "-Wclippy::mutex_integer", @@ -78,5 +78,6 @@ rustflags = [ "-Wfuture_incompatible", "-Wnonstandard_style", "-Wrust_2018_idioms", + "-Wunexpected_cfgs", # END - Embark standard lints v6 for Rust 1.55+ ] From 0329033e6994647b8e605c3733fa64d2951b1332 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Sun, 4 Jan 2026 14:41:23 -0800 Subject: [PATCH 10/11] Update rust.yml --- .github/workflows/rust.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 8632676..6d43c78 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -18,6 +18,9 @@ jobs: - name: Build run: cargo build --verbose + - name: Clippy + run: cargo clippy + - name: Run tests run: cargo test --verbose @@ -38,6 +41,9 @@ jobs: - name: Build run: cargo build --verbose + - name: Clippy + run: cargo clippy + - name: Run tests run: cargo test --verbose @@ -49,6 +55,9 @@ jobs: - name: Build run: cargo build --verbose + - name: Clippy + run: cargo clippy + - name: Run tests run: cargo test --verbose From 91fba250a8bf5f410a670a2f337f4cf144540b96 Mon Sep 17 00:00:00 2001 From: bruingineer Date: Mon, 5 Jan 2026 12:37:46 -0800 Subject: [PATCH 11/11] cargo clippy --- src/receive.rs | 12 ++++++------ src/source.rs | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/receive.rs b/src/receive.rs index d946139..fc373ea 100644 --- a/src/receive.rs +++ b/src/receive.rs @@ -569,8 +569,8 @@ impl SacnReceiver { match self.receiver.recv(&mut buf) { Ok(pkt) => { - let pdu: E131RootLayer = pkt.pdu; - let data: E131RootLayerData = pdu.data; + let pdu = pkt.pdu; + let data = pdu.data; let res = match data { DataPacket(d) => self.handle_data_packet(pdu.cid, d)?, SynchronizationPacket(s) => self.handle_sync_packet(pdu.cid, s)?, @@ -589,9 +589,9 @@ impl SacnReceiver { // return the data, otherwise continue if no data is ready if let Some(r) = res { return Ok(r); - } else { - continue; } + + // end of loop } Err(err) => @@ -605,8 +605,8 @@ impl SacnReceiver { std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut ) => { - // socket read timedout. start new loop to compute new remaining which will return if deadline has passed - continue; + // socket read timedout. + // start new loop to compute new remaining which will return if deadline has passed } _ => { // Not a timeout/wouldblock error meaning the recv should stop with the given error. diff --git a/src/source.rs b/src/source.rs index e77727f..f40c577 100644 --- a/src/source.rs +++ b/src/source.rs @@ -747,7 +747,7 @@ impl SacnSourceInternal { // Check that the synchronisation universe is also valid. if synchronisation_addr.is_some() { self.universe_allowed(&synchronisation_addr.unwrap()) - .map_err(|_| SacnError::IllegalSyncUniverse(synchronisation_addr.unwrap()))?; + .map_err(|_e| SacnError::IllegalSyncUniverse(synchronisation_addr.unwrap()))?; } // + 1 as there must be at least 1 universe required as the data isn't empty then additional universes for any more.