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

#include <merge_receiver.h>

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

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

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

struct	Source
	Information about a remote sACN source being tracked by a merge receiver. More...

Public Types
using	Handle = etcpal::OpaqueId<detail::MergeReceiverHandleType, sacn_merge_receiver_t, SACN_MERGE_RECEIVER_INVALID>

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

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

	MergeReceiver (MergeReceiver &&other)=default

MergeReceiver &	operator= (MergeReceiver &&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 merge receiver is listening to.

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

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

etcpal::Error	ChangeFootprint (const SacnRecvUniverseSubrange &new_footprint)
	Change the footprint within the universe this merge 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 merge receiver is listening to. TODO: Not yet implemented.

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

etcpal::Expected< Source >	GetSource (sacn_remote_source_t source_handle)
	Gets a copy of the information for the specified merge receiver source.

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

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

static etcpal::Error	ResetNetworking (std::vector< SacnMcastInterface > &netints)
	Resets underlying network sockets and packet receipt state, determines network interfaces for all merge 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 merge receiver.

Detailed Description

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

This API is used to minimally wrap the sACN Receiver and DMX Merger logic together so an application can receive and merge sACN sources in software.

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

Member Typedef Documentation

◆ Handle

using Handle = etcpal::OpaqueId<detail::MergeReceiverHandleType, sacn_merge_receiver_t, SACN_MERGE_RECEIVER_INVALID>

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

Constructor & Destructor Documentation

◆ MergeReceiver()

MergeReceiver ( MergeReceiver && other )

default

Move a merge receiver instance.

Member Function Documentation

◆ ChangeFootprint()

etcpal::Error ChangeFootprint ( const SacnRecvUniverseSubrange & new_footprint )

inline

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

After this call completes, a new sampling period will occur, and then underlying updates will generate new calls to HandleMergedData().

Parameters

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

Returns: kEtcPalErrNotImpl: Not yet implemented.

◆ ChangeUniverse()

etcpal::Error ChangeUniverse ( uint16_t new_universe_id )

inline

Change the universe this class is listening to.

An sACN merge receiver can only listen on one universe at a time. After this call completes, a new sampling period will occur, and then underlying updates will generate new calls to HandleMergedData(). 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 merge receiver should listen to.

Returns: kEtcPalErrOk: Universe changed successfully.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrExists: A merge receiver already exists which is listening on the specified new universe.; kEtcPalErrNotFound: Handle does not correspond to a valid merge 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 merge receiver is listening to. TODO: Not yet implemented.

After this call completes, a new sampling period will occur, and then underlying updates will generate new calls to HandleMergedData().

Parameters

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

Returns: kEtcPalErrNotImpl: Not yet implemented.

◆ GetFootprint()

etcpal::Expected< SacnRecvUniverseSubrange > GetFootprint ( ) const

inline

Get the footprint within the universe this merge 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 merge receiver's network interfaces.

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

◆ GetSource()

etcpal::Expected< MergeReceiver::Source > GetSource ( sacn_remote_source_t source_handle )

inline

Gets a copy of the information for the specified merge receiver source.

Parameters

[in] source_handle Handle to the source to obtain information for.

Returns: A copy of the source's information if found.; kEtcPalErrNotFound: The merge receiver has no knowledge of the specified source.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ GetUniverse()

etcpal::Expected< uint16_t > GetUniverse ( ) const

inline

Get the universe this merge 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()

MergeReceiver::Handle handle ( ) const

inlineconstexpr

Get the current handle to the underlying C merge receiver.

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

◆ operator=()

MergeReceiver & operator= ( MergeReceiver && other )

default

Move a merge receiver instance.

◆ ResetNetworking() [1/3]

etcpal::Error ResetNetworking ( )

inlinestatic

Resets the underlying network sockets and packet receipt state for all sACN merge 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 (and by extension, merge 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 (including every merge receiver) is set to all system interfaces.

After this call completes, a new sampling period occurs, and then underlying updates will generate new calls to HandleMergedData(). If this call fails, the caller must call Shutdown() for each merge receiver, because the merge 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 merge 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 (and by extension, merge 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 (including merge receivers) will be configured to use all of those interfaces.

After this call completes, a new sampling period occurs, and then underlying updates will generate new calls to HandleMergedData(). If this call fails, the caller must call Shutdown() for each merge receiver, because the merge 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 merge 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 (and by extension, merge 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 merge receiver.

After this call completes, a new sampling period occurs, and then underlying updates will generate new calls to HandleMergedData(). If this call fails, the caller must call Shutdown() for each merge receiver, because the merge 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 merge receiver. This will only return kEtcPalErrNoNetints if none of the interfaces work for a merge 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 merge receiver. Must not be empty. Must include all merge receivers, and nothing more. The status codes are filled in whenever MergeReceiver::NetintList::netints is !empty.

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

◆ Shutdown()

void Shutdown ( )

inline

Stop listening for sACN data on a universe.

Tears down the merge receiver and any sources currently being tracked on the merge 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 merge receiver can listen on one universe at a time, and each universe can only be listened to by one merge receiver at at time.

Note that a merge 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 merge receiver and this class instance.
[in]	notify_handler	The notification interface to call back to the application.

Returns: kEtcPalErrOk: Merge Receiver created successfully.; kEtcPalErrNoNetints: None of the network interfaces were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrExists: A merge receiver already exists which is listening on the specified universe.; kEtcPalErrNoMem: No room to allocate memory for this merge receiver, or maximum merge receivers reached.; 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 merge receiver can listen on one universe at a time, and each universe can only be listened to by one merge receiver at at time.

Note that a merge 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 merge 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: Merge 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 merge receiver already exists which is listening on the specified universe.; kEtcPalErrNoMem: No room to allocate memory for this merge receiver, or maximum merge receivers reached.; 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/merge_receiver.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Handle

Constructor & Destructor Documentation

◆ MergeReceiver()

Member Function Documentation

◆ ChangeFootprint()

◆ ChangeUniverse()

◆ ChangeUniverseAndFootprint()

◆ GetFootprint()

◆ GetNetworkInterfaces()

◆ GetSource()

◆ GetUniverse()

◆ handle()

◆ operator=()

◆ ResetNetworking() [1/3]

◆ ResetNetworking() [2/3]

◆ ResetNetworking() [3/3]

◆ Shutdown()

◆ Startup() [1/2]

◆ Startup() [2/2]