sACN  2.0.2
Implementation of ANSI E1.31 (Streaming ACN)
View other versions:
sACN Receiver

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

Data Structures

struct  SacnRecvUniverseSubrange
 
struct  SacnRecvUniverseData
 
struct  SacnRemoteSource
 
struct  SacnLostSource
 
struct  SacnReceiverCallbacks
 
struct  SacnReceiverConfig
 
struct  SacnReceiverNetintList
 

Macros

#define SACN_RECEIVER_INVALID   -1
 
#define SACN_RECEIVER_INFINITE_SOURCES   0
 Constant for "infinite" when listening or merging sACN universes. More...
 
#define SACN_DEFAULT_EXPIRED_WAIT_MS   1000u
 The default expired notification wait time. More...
 
#define SACN_RECEIVER_CONFIG_DEFAULT_INIT
 

Typedefs

typedef int sacn_receiver_t
 
typedef struct SacnRecvUniverseSubrange SacnRecvUniverseSubrange
 
typedef struct SacnRecvUniverseData SacnRecvUniverseData
 
typedef struct SacnRemoteSource SacnRemoteSource
 
typedef struct SacnLostSource SacnLostSource
 
typedef void(* SacnUniverseDataCallback) (sacn_receiver_t receiver_handle, const EtcPalSockAddr *source_addr, const SacnRemoteSource *source_info, const SacnRecvUniverseData *universe_data, void *context)
 Notify that new universe data within the configured footprint has been received. More...
 
typedef void(* SacnSourcesLostCallback) (sacn_receiver_t handle, uint16_t universe, const SacnLostSource *lost_sources, size_t num_lost_sources, void *context)
 Notify that one or more sources have entered a source loss state. More...
 
typedef void(* SacnSamplingPeriodStartedCallback) (sacn_receiver_t handle, uint16_t universe, void *context)
 Notify that a receiver's sampling period has begun. More...
 
typedef void(* SacnSamplingPeriodEndedCallback) (sacn_receiver_t handle, uint16_t universe, void *context)
 Notify that a receiver's sampling period has ended. More...
 
typedef void(* SacnSourcePapLostCallback) (sacn_receiver_t handle, uint16_t universe, const SacnRemoteSource *source, void *context)
 Notify that a source has stopped transmission of per-address priority packets. More...
 
typedef void(* SacnSourceLimitExceededCallback) (sacn_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. More...
 
typedef struct SacnReceiverCallbacks SacnReceiverCallbacks
 
typedef struct SacnReceiverConfig SacnReceiverConfig
 
typedef struct SacnReceiverNetintList SacnReceiverNetintList
 

Functions

void sacn_receiver_config_init (SacnReceiverConfig *config)
 Initialize an sACN Receiver Config struct to default values. More...
 
etcpal_error_t sacn_receiver_create (const SacnReceiverConfig *config, sacn_receiver_t *handle, const SacnNetintConfig *netint_config)
 Create a new sACN receiver to listen for sACN data on a universe. More...
 
etcpal_error_t sacn_receiver_destroy (sacn_receiver_t handle)
 Destroy a sACN receiver instance. More...
 
etcpal_error_t sacn_receiver_get_universe (sacn_receiver_t handle, uint16_t *universe_id)
 Get the universe on which a sACN receiver is currently listening. More...
 
etcpal_error_t sacn_receiver_get_footprint (sacn_receiver_t handle, SacnRecvUniverseSubrange *footprint)
 Get the footprint within the universe on which a sACN receiver is currently listening. More...
 
etcpal_error_t sacn_receiver_change_universe (sacn_receiver_t handle, uint16_t new_universe_id)
 Change the universe on which an sACN receiver is listening. More...
 
etcpal_error_t sacn_receiver_change_footprint (sacn_receiver_t handle, const SacnRecvUniverseSubrange *new_footprint)
 Change the footprint within the universe on which an sACN receiver is listening. TODO: Not yet implemented. More...
 
etcpal_error_t sacn_receiver_change_universe_and_footprint (sacn_receiver_t handle, uint16_t new_universe_id, const SacnRecvUniverseSubrange *new_footprint)
 Change the universe and footprint on which an sACN receiver is listening. TODO: Not yet implemented. More...
 
etcpal_error_t sacn_receiver_reset_networking (const SacnNetintConfig *sys_netint_config)
 Resets underlying network sockets and packet receipt state, determines network interfaces for all receivers. More...
 
etcpal_error_t sacn_receiver_reset_networking_per_receiver (const SacnNetintConfig *sys_netint_config, const SacnReceiverNetintList *per_receiver_netint_lists, size_t num_per_receiver_netint_lists)
 Resets underlying network sockets and packet receipt state, determines network interfaces for each receiver. More...
 
size_t sacn_receiver_get_network_interfaces (sacn_receiver_t handle, EtcPalMcastNetintId *netints, size_t netints_size)
 Obtain a list of a receiver's network interfaces. More...
 
void sacn_receiver_set_expired_wait (uint32_t wait_ms)
 Set the expired notification wait time. More...
 
uint32_t sacn_receiver_get_expired_wait ()
 Get the current value of the expired notification wait time. More...
 

sACN receiver flags

Valid values for the flags member in the SacnReceiverConfig struct.

#define SACN_RECEIVER_OPTS_FILTER_PREVIEW_DATA   0x1
 

Detailed Description

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

Macro Definition Documentation

◆ SACN_DEFAULT_EXPIRED_WAIT_MS

#define SACN_DEFAULT_EXPIRED_WAIT_MS   1000u

The default expired notification wait time.

The default amount of time the library will wait after a universe enters a source loss condition before calling the sources_lost() callback. Can be changed with sacn_receiver_set_expired_wait().

◆ SACN_RECEIVER_CONFIG_DEFAULT_INIT

#define SACN_RECEIVER_CONFIG_DEFAULT_INIT
Value:
{ \
0, {NULL, NULL, NULL, NULL, NULL, NULL}, {1, DMX_ADDRESS_COUNT}, SACN_RECEIVER_INFINITE_SOURCES, 0, \
kSacnIpV4AndIpV6 \
}
#define DMX_ADDRESS_COUNT
Definition: common.h:55
#define SACN_RECEIVER_INFINITE_SOURCES
Constant for "infinite" when listening or merging sACN universes.
Definition: receiver.h:68

A default-value initializer for an SacnReceiverConfig struct.

◆ SACN_RECEIVER_INFINITE_SOURCES

#define SACN_RECEIVER_INFINITE_SOURCES   0

Constant for "infinite" when listening or merging sACN universes.

When using dynamic memory, this constant can be passed in when creating a receiver or a merger. It represents an infinite number of sources on that universe.

◆ SACN_RECEIVER_INVALID

#define SACN_RECEIVER_INVALID   -1

An invalid sACN receiver handle value.

◆ SACN_RECEIVER_OPTS_FILTER_PREVIEW_DATA

#define SACN_RECEIVER_OPTS_FILTER_PREVIEW_DATA   0x1

Filter preview data. If set, any sACN data with the Preview flag set will be dropped for this universe.

Typedef Documentation

◆ sacn_receiver_t

typedef int sacn_receiver_t

A handle to an sACN receiver.

◆ SacnLostSource

Information about a sACN source that was lost.

◆ SacnReceiverCallbacks

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

◆ SacnReceiverConfig

A set of configuration information for an sACN receiver.

◆ SacnReceiverNetintList

A set of network interfaces for a particular receiver.

◆ SacnRecvUniverseData

A complete description of newly received universe data within the configured footprint.

◆ SacnRecvUniverseSubrange

Defines a range of addresses within a sACN universe.

◆ SacnRemoteSource

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

◆ SacnSamplingPeriodEndedCallback

typedef void(* SacnSamplingPeriodEndedCallback) (sacn_receiver_t handle, uint16_t universe, void *context)

Notify that a receiver's sampling period has ended.

Parameters
[in]handleHandle to the receiver instance for which the sampling period ended.
[in]universeThe universe this receiver is monitoring.
[in]contextContext pointer that was given at the creation of the receiver instance.

◆ SacnSamplingPeriodStartedCallback

typedef void(* SacnSamplingPeriodStartedCallback) (sacn_receiver_t handle, uint16_t universe, void *context)

Notify that a receiver's sampling period has begun.

Parameters
[in]handleHandle to the receiver instance for which the sampling period started.
[in]universeThe universe this receiver is monitoring.
[in]contextContext pointer that was given at the creation of the receiver instance.

◆ SacnSourceLimitExceededCallback

typedef void(* SacnSourceLimitExceededCallback) (sacn_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.

If SACN_DYNAMIC_MEM was defined to 1 when sACN was compiled (the default on non-embedded platforms), and the configuration you pass to sacn_receiver_create() has source_count_max set to SACN_RECEIVER_INFINITE_SOURCES, this callback will never be called and may be set to NULL.

If SACN_DYNAMIC_MEM was defined to 0 when sACN was compiled, source_count_max is only used if it's less than SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE, otherwise SACN_RECEIVER_MAX_SOURCES_PER_UNIVERSE is used instead.

This callback is rate-limited: it will only be called when the first sACN packet is received from a source beyond the limit specified. After that, it will not be called again until the number of sources sending drops below that limit and then hits it again.

Parameters
[in]handleHandle to the receiver instance for which the source limit has been exceeded.
[in]universeThe universe this receiver is monitoring.
[in]contextContext pointer that was given at the creation of the receiver instance.

◆ SacnSourcePapLostCallback

typedef void(* SacnSourcePapLostCallback) (sacn_receiver_t handle, uint16_t universe, const SacnRemoteSource *source, void *context)

Notify that a source has stopped transmission of per-address priority packets.

If SACN_ETC_PRIORITY_EXTENSION was defined to 0 when sACN was compiled, this callback will never be called and may be set to NULL. This is only called due to a timeout condition; a termination bit is treated as the termination of the entire stream and will result in a sources_lost() notification.

Parameters
[in]handleHandle to the receiver instance for which a source stopped sending per-address priority.
[in]universeThe universe this receiver is monitoring.
[in]sourceInformation about the source that has stopped transmission of per-address priority.
[in]contextContext pointer that was given at the creation of the receiver instance.

◆ SacnSourcesLostCallback

typedef void(* SacnSourcesLostCallback) (sacn_receiver_t handle, uint16_t universe, const SacnLostSource *lost_sources, size_t num_lost_sources, void *context)

Notify that one or more sources have entered a source loss state.

This could be due to timeout or explicit termination. Sources are grouped using an algorithm designed to prevent level jumps when multiple sources are lost simultaneously. See Source Loss Behavior for more information.

Parameters
[in]handleHandle to the receiver instance for which sources were lost.
[in]universeThe universe this receiver is monitoring.
[in]lost_sourcesArray of structs describing the source or sources that have been lost.
[in]num_lost_sourcesSize of the lost_sources array.
[in]contextContext pointer that was given at the creation of the receiver instance.

◆ SacnUniverseDataCallback

typedef void(* SacnUniverseDataCallback) (sacn_receiver_t receiver_handle, const EtcPalSockAddr *source_addr, const SacnRemoteSource *source_info, const SacnRecvUniverseData *universe_data, void *context)

Notify that new universe data within the configured footprint has been received.

This will not be called if the Stream_Terminated bit is set, or if the Preview_Data bit is set and preview packets are being filtered.

Start code 0xDD packets will only trigger this notification if SACN_ETC_PRIORITY_EXTENSION is set to 1. This callback will be called for all other start codes received, even those without a startcode of 0x00 or 0xDD.

This notification will not be called for a source until the first NULL start code packet is received. After that happens, this notification is always called immediately during the sampling period, if SACN_ETC_PRIORITY_EXTENSION is set to 0, or if the start code is not 0x00 or 0xDD. Otherwise, this notification won't be called until both 0x00 and 0xDD start codes are received (in which case the 0xDD notification comes first), or the 0xDD timer has expired and a 0x00 packet is received.

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_handleHandle to the receiver instance for which universe data was received.
[in]source_addrThe network address from which the sACN packet originated.
[in]source_infoInformation about the source that sent this data.
[in]universe_dataThe universe data (and relevant information about that data), starting from the first slot of the currently configured footprint.
[in]contextContext pointer that was given at the creation of the receiver instance.

Function Documentation

◆ sacn_receiver_change_footprint()

etcpal_error_t sacn_receiver_change_footprint ( sacn_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 successfully, the receiver is in a sampling period for the new footprint and will provide SamplingPeriodStarted() and SamplingPeriodEnded() notifications, as well as UniverseData() notifications as packets are received for the new footprint.

Parameters
[in]handleHandle to the receiver for which to change the universe.
[in]new_footprintNew footprint that this receiver should listen to.
Returns
kEtcPalErrNotImpl: Not yet implemented.

◆ sacn_receiver_change_universe()

etcpal_error_t sacn_receiver_change_universe ( sacn_receiver_t  handle,
uint16_t  new_universe_id 
)

Change the universe on which an sACN receiver is listening.

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 universe and will provide SamplingPeriodStarted() and SamplingPeriodEnded() notifications, as well as UniverseData() notifications as packets are received for the universe. If this call fails, the caller must call sacn_receiver_destroy for the receiver, because the receiver may be in an invalid state.

Parameters
[in]handleHandle to the receiver for which to change the universe.
[in]new_universe_idNew 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.

◆ sacn_receiver_change_universe_and_footprint()

etcpal_error_t sacn_receiver_change_universe_and_footprint ( sacn_receiver_t  handle,
uint16_t  new_universe_id,
const SacnRecvUniverseSubrange new_footprint 
)

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

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

Parameters
[in]handleHandle to the receiver for which to change the universe.
[in]new_universe_idNew universe number that this receiver should listen to.
[in]new_footprintNew footprint within the universe.
Returns
kEtcPalErrNotImpl: Not yet implemented.

◆ sacn_receiver_config_init()

void sacn_receiver_config_init ( SacnReceiverConfig config)

Initialize an sACN Receiver Config struct to default values.

Parameters
[out]configConfig struct to initialize.

◆ sacn_receiver_create()

etcpal_error_t sacn_receiver_create ( const SacnReceiverConfig config,
sacn_receiver_t handle,
const SacnNetintConfig netint_config 
)

Create a new sACN receiver to listen for sACN data on a universe.

A 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 SamplingPeriodStarted() and SamplingPeriodEnded() notifications, as well as UniverseData() 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]configConfiguration parameters for the sACN receiver to be created.
[out]handleFilled in on success with a handle to the sACN receiver.
[in,out]netint_configOptional. 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: 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.

◆ sacn_receiver_destroy()

etcpal_error_t sacn_receiver_destroy ( sacn_receiver_t  handle)

Destroy a sACN receiver instance.

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

Parameters
[in]handleHandle to the receiver to destroy.
Returns
kEtcPalErrOk: Receiver destroyed successfully.
kEtcPalErrNotInit: Module not initialized.
kEtcPalErrNotFound: Handle does not correspond to a valid receiver.
kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_receiver_get_expired_wait()

uint32_t sacn_receiver_get_expired_wait ( )

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 sending a sources_lost() notification. However, the wait may be longer due to the source loss algorithm (see Source Loss Behavior).

Returns
Wait time in milliseconds.

◆ sacn_receiver_get_footprint()

etcpal_error_t sacn_receiver_get_footprint ( sacn_receiver_t  handle,
SacnRecvUniverseSubrange footprint 
)

Get the footprint within the universe on which a sACN 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]handleHandle to the receiver that we want to query.
[out]footprintThe retrieved footprint.
Returns
kEtcPalErrOk: Footprint retrieved successfully.
kEtcPalErrInvalid: Invalid parameter provided.
kEtcPalErrNotInit: Module not initialized.
kEtcPalErrNotFound: Handle does not correspond to a valid receiver.
kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_receiver_get_network_interfaces()

size_t sacn_receiver_get_network_interfaces ( sacn_receiver_t  handle,
EtcPalMcastNetintId netints,
size_t  netints_size 
)

Obtain a list of a receiver's network interfaces.

Parameters
[in]handleHandle to the receiver for which to obtain the list of network interfaces.
[out]netintsA pointer to an application-owned array where the network interface list will be written.
[in]netints_sizeThe size of the provided netints array.
Returns
The total number of network interfaces for the receiver. If this is greater than netints_size, then only netints_size entries were written to the netints array. If the receiver was not found, 0 is returned.

◆ sacn_receiver_get_universe()

etcpal_error_t sacn_receiver_get_universe ( sacn_receiver_t  handle,
uint16_t *  universe_id 
)

Get the universe on which a sACN receiver is currently listening.

Parameters
[in]handleHandle to the receiver that we want to query.
[out]universe_idThe retrieved universe.
Returns
kEtcPalErrOk: Universe retrieved successfully.
kEtcPalErrInvalid: Invalid parameter provided.
kEtcPalErrNotInit: Module not initialized.
kEtcPalErrNotFound: Handle does not correspond to a valid receiver.
kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_receiver_reset_networking()

etcpal_error_t sacn_receiver_reset_networking ( const SacnNetintConfig sys_netint_config)

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 sacn_receiver_destroy 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
[in,out]sys_netint_configOptional. 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_receiver_reset_networking_per_receiver()

etcpal_error_t sacn_receiver_reset_networking_per_receiver ( const SacnNetintConfig sys_netint_config,
const SacnReceiverNetintList per_receiver_netint_lists,
size_t  num_per_receiver_netint_lists 
)

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 sacn_receiver_destroy 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
[in,out]sys_netint_configOptional. 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_listsLists of interfaces the application wants to use for each receiver. Must not be NULL. Must include all receivers, and nothing more. The status codes are filled in whenever SacnReceiverNetintList::netints is non-NULL.
[in]num_per_receiver_netint_listsThe size of netint_lists. Must not be 0.
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.

◆ sacn_receiver_set_expired_wait()

void sacn_receiver_set_expired_wait ( uint32_t  wait_ms)

Set the expired notification wait time.

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

Parameters
[in]wait_msWait time in milliseconds.