An instance of sACN Receiver functionality; see Using the sACN Receiver API. More...

#include <receiver.h>

Data Structures
struct	NetintList
	A set of network interfaces for a particular receiver. More...

class	NotifyHandler
	A base class for a class that receives notification callbacks from a sACN receiver. More...

struct	Settings
	A set of configuration settings that a receiver needs to initialize. More...

Public Types
using	Handle = etcpal::OpaqueId<detail::ReceiverHandleType, sacn_receiver_t, SACN_RECEIVER_INVALID>

Public Member Functions
	Receiver (const Receiver &other)=delete

Receiver &	operator= (const Receiver &other)=delete

	Receiver (Receiver &&other)=default

Receiver &	operator= (Receiver &&other)=default

etcpal::Error	Startup (const Settings &settings, NotifyHandler &notify_handler)
	Start listening for sACN data on a universe.

etcpal::Error	Startup (const Settings &settings, NotifyHandler &notify_handler, std::vector< SacnMcastInterface > &netints)
	Start listening for sACN data on a universe.

void	Shutdown ()
	Stop listening for sACN data on a universe.

etcpal::Expected< uint16_t >	GetUniverse () const
	Get the universe this receiver is listening to.

etcpal::Expected< SacnRecvUniverseSubrange >	GetFootprint () const
	Get the footprint within the universe this receiver is listening to.

etcpal::Error	ChangeUniverse (uint16_t new_universe_id)
	Change the universe this receiver is listening to.

etcpal::Error	ChangeFootprint (const SacnRecvUniverseSubrange &new_footprint)
	Change the footprint within the universe this receiver is listening to. TODO: Not yet implemented.

etcpal::Error	ChangeUniverseAndFootprint (uint16_t new_universe_id, const SacnRecvUniverseSubrange &new_footprint)
	Change the universe and footprint this receiver is listening to. TODO: Not yet implemented.

std::vector< EtcPalMcastNetintId >	GetNetworkInterfaces ()
	Obtain a vector of this receiver's network interfaces.

constexpr Handle	handle () const
	Get the current handle to the underlying C receiver.

Static Public Member Functions
static void	SetExpiredWait (uint32_t wait_ms)
	Set the expired notification wait time.

static uint32_t	GetExpiredWait ()
	Get the current value of the expired notification wait time.

static etcpal::Error	ResetNetworking ()
	Resets the underlying network sockets and packet receipt state for all sACN receivers.

static etcpal::Error	ResetNetworking (std::vector< SacnMcastInterface > &netints)
	Resets underlying network sockets and packet receipt state, determines network interfaces for all receivers.

static etcpal::Error	ResetNetworking (std::vector< SacnMcastInterface > &sys_netints, std::vector< NetintList > &netint_lists)
	Resets underlying network sockets and packet receipt state, determines network interfaces for each receiver.

Detailed Description

An instance of sACN Receiver functionality; see Using the sACN Receiver API.

Components that receive sACN are referred to as sACN Receivers. Use this API to act as an sACN Receiver.

See Using the sACN Receiver API for a detailed description of how to use this API.

Member Typedef Documentation

◆ Handle

using Handle = etcpal::OpaqueId<detail::ReceiverHandleType, sacn_receiver_t, SACN_RECEIVER_INVALID>

A handle type used by the sACN library to identify receiver instances.

Constructor & Destructor Documentation

◆ Receiver()

Receiver ( Receiver && other )

default

Move a device instance.

Member Function Documentation

◆ ChangeFootprint()

etcpal::Error ChangeFootprint ( const SacnRecvUniverseSubrange & new_footprint )

inline

Change the footprint within the universe this receiver is listening to. TODO: Not yet implemented.

After this call completes successfully, the receiver is in a sampling period for the new footprint and will provide HandleSamplingPeriodStarted() and HandleSamplingPeriodEnded() notifications, as well as HandleUniverseData() notifications as packets are received for the new footprint.

Parameters

[in] new_footprint New footprint that this receiver should listen to.

Returns: kEtcPalErrNotImpl: Not yet implemented.

◆ ChangeUniverse()

etcpal::Error ChangeUniverse ( uint16_t new_universe_id )

inline

Change the universe this receiver is listening to.

An sACN receiver can only listen on one universe at a time. After this call completes successfully, the receiver is in a sampling period for the new universe and will provide HandleSamplingPeriodStarted() and HandleSamplingPeriodEnded() notifications, as well as HandleUniverseData() notifications as packets are received for the new universe. If this call fails, the caller must call Shutdown() on this class, because it may be in an invalid state.

Parameters

[in] new_universe_id New universe number that this receiver should listen to.

Returns: kEtcPalErrOk: Universe changed successfully.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrExists: A receiver already exists which is listening on the specified new universe.; kEtcPalErrNotFound: Handle does not correspond to a valid receiver.; kEtcPalErrSys: An internal library or system call error occurred.

◆ ChangeUniverseAndFootprint()

etcpal::Error ChangeUniverseAndFootprint	(	uint16_t	new_universe_id,
		const SacnRecvUniverseSubrange &	new_footprint )

inline

Change the universe and footprint this receiver is listening to. TODO: Not yet implemented.

After this call completes successfully, the receiver is in a sampling period for the new footprint and will provide HandleSamplingPeriodStarted() and HandleSamplingPeriodEnded() notifications, as well as HandleUniverseData() notifications as packets are received for the new footprint.

Parameters

[in]	new_universe_id	New universe number that this receiver should listen to.
[in]	new_footprint	New footprint within the universe.

Returns: kEtcPalErrNotImpl: Not yet implemented.

◆ GetExpiredWait()

uint32_t GetExpiredWait ( )

inlinestatic

Get the current value of the expired notification wait time.

The library will wait at least this long after a source loss condition has been encountered before calling HandleSourcesLost(). However, the wait may be longer due to the source loss algorithm (see Source Loss Behavior).

Returns: Wait time in milliseconds.

◆ GetFootprint()

etcpal::Expected< SacnRecvUniverseSubrange > GetFootprint ( ) const

inline

Get the footprint within the universe this receiver is listening to.

TODO: At this time, custom footprints are not supported by this library, so the full 512-slot footprint is returned.

Returns: If valid, the value is the footprint. Otherwise, this is the underlying error the C library call returned.

◆ GetNetworkInterfaces()

std::vector< EtcPalMcastNetintId > GetNetworkInterfaces ( )

inline

Obtain a vector of this receiver's network interfaces.

Returns: A vector of this receiver's network interfaces.

◆ GetUniverse()

etcpal::Expected< uint16_t > GetUniverse ( ) const

inline

Get the universe this receiver is listening to.

Returns: If valid, the value is the universe id. Otherwise, this is the underlying error the C library call returned.

◆ handle()

Receiver::Handle handle ( ) const

inlineconstexpr

Get the current handle to the underlying C receiver.

Returns: The handle, which will only be valid if the receiver has been successfully created using Startup().

◆ operator=()

Receiver & operator= ( Receiver && other )

default

Move a device instance.

◆ ResetNetworking() [1/3]

etcpal::Error ResetNetworking ( )

inlinestatic

Resets the underlying network sockets and packet receipt state for all sACN receivers.

This is the overload of ResetNetworking that uses all network interfaces.

This is typically used when the application detects that the list of networking interfaces has changed. The receiver API will no longer be limited to specific interfaces (the list passed into sacn::Init(), if any, is overridden for the receiver API, but not the other APIs). Every receiver is set to all system interfaces.

After this call completes successfully, every receiver is in a sampling period for their universes and will provide SamplingPeriodStarted() and SamplingPeriodEnded() notifications, as well as UniverseData() notifications as packets are received for their universes. If this call fails, the caller must call Shutdown() for each receiver, because the receivers may be in an invalid state.

Note that the networking reset is considered successful if it is able to successfully use any of the network interfaces. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Returns: kEtcPalErrOk: Networking reset successfully.; kEtcPalErrNoNetints: None of the network interfaces were usable by the library.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ ResetNetworking() [2/3]

etcpal::Error ResetNetworking ( std::vector< SacnMcastInterface > & sys_netints )

inlinestatic

Resets underlying network sockets and packet receipt state, determines network interfaces for all receivers.

This is typically used when the application detects that the list of networking interfaces has changed. This changes the list of system interfaces the receiver API will be limited to (the list passed into sacn::Init(), if any, is overridden for the receiver API, but not the other APIs). Then all receivers will be configured to use all of those interfaces.

After this call completes successfully, every receiver is in a sampling period for their universes and will provide SamplingPeriodStarted() and SamplingPeriodEnded() notifications, as well as UniverseData() notifications as packets are received for their universes. If this call fails, the caller must call Shutdown() for each receiver, because the receivers may be in an invalid state.

Note that the networking reset is considered successful if it is able to successfully use any of the network interfaces passed in. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Parameters

sys_netints If !empty, this is the list of system interfaces the receiver API will be limited to, and the status codes are filled in. If empty, the receiver API is allowed to use all available system interfaces.

Returns: kEtcPalErrOk: Networking reset successfully.; kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ ResetNetworking() [3/3]

etcpal::Error ResetNetworking	(	std::vector< SacnMcastInterface > &	sys_netints,
		std::vector< NetintList > &	per_receiver_netint_lists )

inlinestatic

Resets underlying network sockets and packet receipt state, determines network interfaces for each receiver.

This is typically used when the application detects that the list of networking interfaces has changed. This changes the list of system interfaces the receiver API will be limited to (the list passed into sacn::Init(), if any, is overridden for the receiver API, but not the other APIs). Then the network interfaces are specified for each receiver.

After this call completes successfully, every receiver is in a sampling period for their universes and will provide SamplingPeriodStarted() and SamplingPeriodEnded() notifications, as well as UniverseData() notifications as packets are received for their universes. If this call fails, the caller must call Shutdown() for each receiver, because the receivers may be in an invalid state.

Note that the networking reset is considered successful if it is able to successfully use any of the network interfaces passed in for each receiver. This will only return kEtcPalErrNoNetints if none of the interfaces work for a receiver.

Parameters

	sys_netints	If !empty, this is the list of system interfaces the receiver API will be limited to, and the status codes are filled in. If empty, the receiver API is allowed to use all available system interfaces.
[in,out]	per_receiver_netint_lists	Vector of lists of interfaces the application wants to use for each receiver. Must not be empty. Must include all receivers, and nothing more. The status codes are filled in whenever Receiver::NetintList::netints is !empty.

Returns: kEtcPalErrOk: Networking reset successfully.; kEtcPalErrNoNetints: None of the network interfaces provided for a receiver were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ SetExpiredWait()

void SetExpiredWait ( uint32_t wait_ms )

inlinestatic

Set the expired notification wait time.

The library will wait at least this long after a source loss condition has been encountered before calling HandleSourcesLost(). However, the wait may be longer due to the source loss algorithm (see Source Loss Behavior).

Parameters

[in] wait_ms Wait time in milliseconds.

◆ Shutdown()

void Shutdown ( )

inline

Stop listening for sACN data on a universe.

Tears down the receiver and any sources currently being tracked on the receiver's universe. Stops listening for sACN on that universe.

◆ Startup() [1/2]

etcpal::Error Startup	(	const Settings &	settings,
		NotifyHandler &	notify_handler )

inline

Start listening for sACN data on a universe.

This is the overload of Startup that uses all network interfaces.

An sACN receiver can listen on one universe at a time, and each universe can only be listened to by one receiver at at time.

Note that a receiver is considered as successfully created if it is able to successfully use any of the network interfaces. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Parameters

[in]	settings	Configuration parameters for the sACN receiver and this class instance.
[in]	notify_handler	The notification interface to call back to the application.

Returns: kEtcPalErrOk: Receiver created successfully.; kEtcPalErrNoNetints: None of the network interfaces were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrExists: A receiver already exists which is listening on the specified universe.; kEtcPalErrNoMem: No room to allocate memory for this receiver.; kEtcPalErrNotFound: A network interface ID given was not found on the system.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Startup() [2/2]

etcpal::Error Startup	(	const Settings &	settings,
		NotifyHandler &	notify_handler,
		std::vector< SacnMcastInterface > &	netints )

inline

Start listening for sACN data on a universe.

An sACN receiver can listen on one universe at a time, and each universe can only be listened to by one receiver at at time.

After this call completes successfully, the receiver is in a sampling period for the universe and will provide HandleSamplingPeriodStarted() and HandleSamplingPeriodEnded() notifications, as well as HandleUniverseData() notifications as packets are received for the universe.

Note that a receiver is considered as successfully created if it is able to successfully use any of the network interfaces passed in. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Parameters

[in]	settings	Configuration parameters for the sACN receiver and this class instance.
[in]	notify_handler	The notification interface to call back to the application.
[in,out]	netints	Optional. If !empty, this is the list of interfaces the application wants to use, and the status codes are filled in. If empty, all available interfaces are tried and this vector isn't modified.

Returns: kEtcPalErrOk: Receiver created successfully.; kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrExists: A receiver already exists which is listening on the specified universe.; kEtcPalErrNoMem: No room to allocate memory for this receiver.; kEtcPalErrNotFound: A network interface ID given was not found on the system.; kEtcPalErrSys: An internal library or system call error occurred.

The documentation for this class was generated from the following file:

include/sacn/cpp/receiver.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Handle

Constructor & Destructor Documentation

◆ Receiver()

Member Function Documentation

◆ ChangeFootprint()

◆ ChangeUniverse()

◆ ChangeUniverseAndFootprint()

◆ GetExpiredWait()

◆ GetFootprint()

◆ GetNetworkInterfaces()

◆ GetUniverse()

◆ handle()

◆ operator=()

◆ ResetNetworking() [1/3]

◆ ResetNetworking() [2/3]

◆ ResetNetworking() [3/3]

◆ SetExpiredWait()

◆ Shutdown()

◆ Startup() [1/2]

◆ Startup() [2/2]