The sACN Merge Receiver API; see Using the sACN Merge Receiver API. More...

Data Structures
struct	SacnRecvMergedData

struct	SacnMergeReceiverCallbacks

struct	SacnMergeReceiverConfig

struct	SacnMergeReceiverNetintList

struct	SacnMergeReceiverSource

Macros
#define	SACN_MERGE_RECEIVER_INVALID SACN_RECEIVER_INVALID

#define	SACN_MERGE_RECEIVER_CONFIG_DEFAULT_INIT

Typedefs
typedef int	sacn_merge_receiver_t

typedef struct SacnRecvMergedData	SacnRecvMergedData

typedef void(*	SacnMergeReceiverMergedDataCallback) (sacn_merge_receiver_t handle, const SacnRecvMergedData merged_data, void context)
	Notify that a new data packet has been received and merged.

typedef void(*	SacnMergeReceiverNonDmxCallback) (sacn_merge_receiver_t receiver_handle, const EtcPalSockAddr source_addr, const SacnRemoteSource source_info, const SacnRecvUniverseData universe_data, void context)
	Notify that a non-data packet has been received.

typedef void(*	SacnMergeReceiverSourceLimitExceededCallback) (sacn_merge_receiver_t handle, uint16_t universe, void *context)
	Notify that more than the configured maximum number of sources are currently sending on the universe being listened to.

typedef struct SacnMergeReceiverCallbacks	SacnMergeReceiverCallbacks

typedef struct SacnMergeReceiverConfig	SacnMergeReceiverConfig

typedef struct SacnMergeReceiverNetintList	SacnMergeReceiverNetintList

typedef struct SacnMergeReceiverSource	SacnMergeReceiverSource

Functions
void	sacn_merge_receiver_config_init (SacnMergeReceiverConfig *config)
	Initialize an sACN Merge Receiver Config struct to default values.

etcpal_error_t	sacn_merge_receiver_create (const SacnMergeReceiverConfig config, sacn_merge_receiver_t handle, const SacnNetintConfig *netint_config)
	Create a new sACN Merge Receiver to listen and merge sACN data on a universe.

etcpal_error_t	sacn_merge_receiver_destroy (sacn_merge_receiver_t handle)
	Destroy a sACN Merge Receiver instance.

etcpal_error_t	sacn_merge_receiver_get_universe (sacn_merge_receiver_t handle, uint16_t *universe_id)
	Get the universe on which a sACN Merge Receiver is currently listening.

etcpal_error_t	sacn_merge_receiver_get_footprint (sacn_merge_receiver_t handle, SacnRecvUniverseSubrange *footprint)
	Get the footprint within the universe on which a sACN Merge Receiver is currently listening.

etcpal_error_t	sacn_merge_receiver_change_universe (sacn_merge_receiver_t handle, uint16_t new_universe_id)
	Change the universe on which a sACN Merge Receiver is listening.

etcpal_error_t	sacn_merge_receiver_change_footprint (sacn_merge_receiver_t handle, const SacnRecvUniverseSubrange *new_footprint)
	Change the footprint within the universe on which an sACN receiver is listening. TODO: Not yet implemented.

etcpal_error_t	sacn_merge_receiver_change_universe_and_footprint (sacn_merge_receiver_t handle, uint16_t new_universe_id, const SacnRecvUniverseSubrange *new_footprint)
	Change the universe and footprint on which an sACN merge receiver is listening. TODO: Not yet implemented.

etcpal_error_t	sacn_merge_receiver_reset_networking (const SacnNetintConfig *sys_netint_config)
	Resets underlying network sockets and packet receipt state, determines network interfaces for all merge receivers.

etcpal_error_t	sacn_merge_receiver_reset_networking_per_receiver (const SacnNetintConfig sys_netint_config, const SacnMergeReceiverNetintList per_receiver_netint_lists, size_t num_per_receiver_netint_lists)
	Resets underlying network sockets and packet receipt state, determines network interfaces for each merge receiver.

size_t	sacn_merge_receiver_get_network_interfaces (sacn_merge_receiver_t handle, EtcPalMcastNetintId *netints, size_t netints_size)
	Obtain a list of a merge receiver's network interfaces.

etcpal_error_t	sacn_merge_receiver_get_source (sacn_merge_receiver_t merge_receiver_handle, sacn_remote_source_t source_handle, SacnMergeReceiverSource *source_info)
	Gets a copy of the information for the specified merge receiver source.

Detailed Description

The sACN Merge Receiver API; 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.

Macro Definition Documentation

◆ SACN_MERGE_RECEIVER_CONFIG_DEFAULT_INIT

#define SACN_MERGE_RECEIVER_CONFIG_DEFAULT_INIT

Value:

  {                                                                                                             \
    0, {NULL, NULL, NULL, NULL}, {1, DMX_ADDRESS_COUNT}, SACN_RECEIVER_INFINITE_SOURCES, true, kSacnIpV4AndIpV6 \
  }

A default-value initializer for an SacnMergeReceiverConfig struct.

◆ SACN_MERGE_RECEIVER_INVALID

#define SACN_MERGE_RECEIVER_INVALID SACN_RECEIVER_INVALID

An invalid sACN merge_receiver handle value.

Typedef Documentation

◆ sacn_merge_receiver_t

typedef int sacn_merge_receiver_t

A handle to an sACN Merge Receiver.

◆ SacnMergeReceiverCallbacks

typedef struct SacnMergeReceiverCallbacks SacnMergeReceiverCallbacks

A set of callback functions that the library uses to notify the application about sACN events.

◆ SacnMergeReceiverConfig

typedef struct SacnMergeReceiverConfig SacnMergeReceiverConfig

A set of configuration information for an sACN merge receiver.

◆ SacnMergeReceiverMergedDataCallback

typedef void(* SacnMergeReceiverMergedDataCallback) (sacn_merge_receiver_t handle, const SacnRecvMergedData *merged_data, void *context)

Notify that a new data packet has been received and merged.

This callback will be called in multiple ways:

When a new non-preview data packet or per-address priority packet is received from the sACN Receiver module, it is immediately and synchronously passed to the DMX Merger. If the sampling period has not ended, the merged result is not passed to this callback until the sampling period ends. Otherwise, it is immediately and synchronously passed to this callback.
When a sACN source is no longer sending non-preview data or per-address priority packets, the lost source callback from the sACN Receiver module will be passed to the merger, after which the merged result is passed to this callback pending the sampling period.

This callback should be processed quickly, since it will interfere with the receipt and processing of other sACN packets on the universe.

Parameters

[in]	handle	The handle to the merge receiver instance.
[in]	merged_data	The merged data (and relevant information about that data), starting from the first slot of the currently configured footprint.
[in]	context	Context pointer that was given at the creation of the merge receiver instance.

◆ SacnMergeReceiverNetintList

typedef struct SacnMergeReceiverNetintList SacnMergeReceiverNetintList

A set of network interfaces for a particular merge receiver.

◆ SacnMergeReceiverNonDmxCallback

typedef void(* SacnMergeReceiverNonDmxCallback) (sacn_merge_receiver_t receiver_handle, const EtcPalSockAddr *source_addr, const SacnRemoteSource *source_info, const SacnRecvUniverseData *universe_data, void *context)

Notify that a non-data packet has been received.

When an established source sends a sACN data packet that doesn't contain DMX values or priorities, the raw data within the configured footprint is immediately and synchronously passed to this callback.

This callback should be processed quickly, since it will interfere with the receipt and processing of other sACN packets on the universe.

If the source is sending sACN Sync packets, this callback will only be called when the sync packet is received, if the source forces the packet, or if the source sends a data packet without a sync universe.

Todo: This version of the sACN library does not support sACN Sync. This paragraph will be valid in the future.

Parameters

[in]	receiver_handle	The handle to the merge receiver instance.
[in]	source_addr	The network address from which the sACN packet originated.
[in]	source_info	Information about the source that sent this data.
[in]	universe_data	The universe data (and relevant information about that data), starting from the first slot of the currently configured footprint.
[in]	context	Context pointer that was given at the creation of the merge receiver instance.

◆ SacnMergeReceiverSource

typedef struct SacnMergeReceiverSource SacnMergeReceiverSource

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

◆ SacnMergeReceiverSourceLimitExceededCallback

typedef void(* SacnMergeReceiverSourceLimitExceededCallback) (sacn_merge_receiver_t handle, uint16_t universe, void *context)

Notify that more than the configured maximum number of sources are currently sending on the universe being listened to.

This is a notification that is directly forwarded from the sACN Receiver module.

Parameters

[in]	handle	Handle to the merge receiver instance for which the source limit has been exceeded.
[in]	universe	The universe this merge receiver is monitoring.
[in]	context	Context pointer that was given at the creation of the merge receiver instance.

◆ SacnRecvMergedData

typedef struct SacnRecvMergedData SacnRecvMergedData

Newly updated merged data within the configured footprint.

Function Documentation

◆ sacn_merge_receiver_change_footprint()

etcpal_error_t sacn_merge_receiver_change_footprint	(	sacn_merge_receiver_t	handle,
		const SacnRecvUniverseSubrange *	new_footprint )

Change the footprint within the universe on which an sACN receiver is listening. TODO: Not yet implemented.

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

Parameters

[in]	handle	Handle to the merge receiver for which to change the universe.
[in]	new_footprint	New footprint that this receiver should listen to.

Returns: kEtcPalErrNotImpl: Not yet implemented.

◆ sacn_merge_receiver_change_universe()

etcpal_error_t sacn_merge_receiver_change_universe	(	sacn_merge_receiver_t	handle,
		uint16_t	new_universe_id )

Change the universe on which a sACN Merge Receiver is listening.

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 SacnMergeReceiverMergedDataCallback(). If this call fails, the caller must call sacn_merge_receiver_destroy for the merge receiver, because the merge receiver may be in an invalid state.

Parameters

[in]	handle	Handle to the merge receiver for which to change the universe.
[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.

◆ sacn_merge_receiver_change_universe_and_footprint()

etcpal_error_t sacn_merge_receiver_change_universe_and_footprint	(	sacn_merge_receiver_t	handle,
		uint16_t	new_universe_id,
		const SacnRecvUniverseSubrange *	new_footprint )

Change the universe and footprint on which an sACN merge receiver is listening. TODO: Not yet implemented.

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

Parameters

[in]	handle	Handle to the merge receiver for which to change the universe.
[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.

◆ sacn_merge_receiver_config_init()

void sacn_merge_receiver_config_init ( SacnMergeReceiverConfig * config )

Initialize an sACN Merge Receiver Config struct to default values.

Parameters

[out] config Config struct to initialize.

◆ sacn_merge_receiver_create()

etcpal_error_t sacn_merge_receiver_create	(	const SacnMergeReceiverConfig *	config,
		sacn_merge_receiver_t *	handle,
		const SacnNetintConfig *	netint_config )

Create a new sACN Merge Receiver to listen and merge 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 listed in the passed in. This will only return kEtcPalErrNoNetints if none of the interfaces work.

Parameters

[in]	config	Configuration parameters for the sACN Merge Receiver to be created.
[out]	handle	Filled in on success with a handle to the sACN Merge Receiver.
[in,out]	netint_config	Optional. If non-NULL, this is the list of interfaces the application wants to use, and the status codes are filled in. If NULL, all available interfaces are tried.

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.

◆ sacn_merge_receiver_destroy()

etcpal_error_t sacn_merge_receiver_destroy ( sacn_merge_receiver_t handle )

Destroy a sACN Merge Receiver instance.

Parameters

[in] handle Handle to the merge receiver to destroy.

Returns: kEtcPalErrOk: Merge receiver destroyed successfully.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid merge receiver.; kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_merge_receiver_get_footprint()

etcpal_error_t sacn_merge_receiver_get_footprint	(	sacn_merge_receiver_t	handle,
		SacnRecvUniverseSubrange *	footprint )

Get the footprint within the universe on which a sACN Merge Receiver is currently listening.

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

Parameters

[in]	handle	Handle to the merge receiver that we want to query.
[out]	footprint	The retrieved footprint.

Returns: kEtcPalErrOk: Footprint retrieved successfully.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid merge receiver.; kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_merge_receiver_get_network_interfaces()

size_t sacn_merge_receiver_get_network_interfaces	(	sacn_merge_receiver_t	handle,
		EtcPalMcastNetintId *	netints,
		size_t	netints_size )

Obtain a list of a merge receiver's network interfaces.

Parameters

[in]	handle	Handle to the merge receiver for which to obtain the list of network interfaces.
[out]	netints	A pointer to an application-owned array where the network interface list will be written.
[in]	netints_size	The size of the provided netints array.

Returns: The total number of network interfaces for the merge receiver. If this is greater than netints_size, then only netints_size entries were written to the netints array. If the merge receiver was not found, 0 is returned.

◆ sacn_merge_receiver_get_source()

etcpal_error_t sacn_merge_receiver_get_source	(	sacn_merge_receiver_t	merge_receiver_handle,
		sacn_remote_source_t	source_handle,
		SacnMergeReceiverSource *	source_info )

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

Parameters

[in]	merge_receiver_handle	Handle to the merge receiver receiving data from the source.
[in]	source_handle	Handle to the source to obtain information for.
[out]	source_info	The destination struct to copy the source information into.

Returns: kEtcPalErrOk: Source information obtained successfully.; kEtcPalErrNotFound: The specified merge receiver was either not found or did not have the specified source.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_merge_receiver_get_universe()

etcpal_error_t sacn_merge_receiver_get_universe	(	sacn_merge_receiver_t	handle,
		uint16_t *	universe_id )

Get the universe on which a sACN Merge Receiver is currently listening.

Parameters

[in]	handle	Handle to the merge receiver that we want to query.
[out]	universe_id	The retrieved universe.

Returns: kEtcPalErrOk: Universe retrieved successfully.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Handle does not correspond to a valid merge receiver.; kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_merge_receiver_reset_networking()

etcpal_error_t sacn_merge_receiver_reset_networking ( const SacnNetintConfig * sys_netint_config )

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 SacnMergeReceiverMergedDataCallback(). If this call fails, the caller must call sacn_merge_receiver_destroy 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

[in,out] sys_netint_config Optional. If non-NULL, this is the list of system interfaces the receiver API will be limited to, and the status codes are filled in. If NULL, 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.

◆ sacn_merge_receiver_reset_networking_per_receiver()

etcpal_error_t sacn_merge_receiver_reset_networking_per_receiver	(	const SacnNetintConfig *	sys_netint_config,
		const SacnMergeReceiverNetintList *	per_receiver_netint_lists,
		size_t	num_per_receiver_netint_lists )

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 SacnMergeReceiverMergedDataCallback(). If this call fails, the caller must call sacn_merge_receiver_destroy 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

[in,out]	sys_netint_config	Optional. If non-NULL, this is the list of system interfaces the receiver API will be limited to, and the status codes are filled in. If NULL, the receiver API is allowed to use all available system interfaces.
[in,out]	per_receiver_netint_lists	Lists of interfaces the application wants to use for each merge receiver. Must not be NULL. Must include all merge receivers, and nothing more. The status codes are filled in whenever SacnMergeReceiverNetintList::netints is non-NULL.
[in]	num_per_receiver_netint_lists	The size of netint_lists. Must not be 0.

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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SACN_MERGE_RECEIVER_CONFIG_DEFAULT_INIT

◆ SACN_MERGE_RECEIVER_INVALID

Typedef Documentation

◆ sacn_merge_receiver_t

◆ SacnMergeReceiverCallbacks

◆ SacnMergeReceiverConfig

◆ SacnMergeReceiverMergedDataCallback

◆ SacnMergeReceiverNetintList

◆ SacnMergeReceiverNonDmxCallback

◆ SacnMergeReceiverSource

◆ SacnMergeReceiverSourceLimitExceededCallback

◆ SacnRecvMergedData

Function Documentation

◆ sacn_merge_receiver_change_footprint()

◆ sacn_merge_receiver_change_universe()

◆ sacn_merge_receiver_change_universe_and_footprint()

◆ sacn_merge_receiver_config_init()

◆ sacn_merge_receiver_create()

◆ sacn_merge_receiver_destroy()

◆ sacn_merge_receiver_get_footprint()

◆ sacn_merge_receiver_get_network_interfaces()

◆ sacn_merge_receiver_get_source()

◆ sacn_merge_receiver_get_universe()

◆ sacn_merge_receiver_reset_networking()

◆ sacn_merge_receiver_reset_networking_per_receiver()