sACN
2.0.2
Implementation of ANSI E1.31 (Streaming ACN)
|
View other versions:
|
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. | |
#define | SACN_DEFAULT_EXPIRED_WAIT_MS 1000u |
The default expired notification wait time. | |
#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. | |
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. | |
typedef void(* | SacnSamplingPeriodStartedCallback) (sacn_receiver_t handle, uint16_t universe, void *context) |
Notify that a receiver's sampling period has begun. | |
typedef void(* | SacnSamplingPeriodEndedCallback) (sacn_receiver_t handle, uint16_t universe, void *context) |
Notify that a receiver's sampling period has ended. | |
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. | |
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. | |
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. | |
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. | |
etcpal_error_t | sacn_receiver_destroy (sacn_receiver_t handle) |
Destroy a sACN receiver instance. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
void | sacn_receiver_set_expired_wait (uint32_t wait_ms) |
Set the expired notification wait time. | |
uint32_t | sacn_receiver_get_expired_wait () |
Get the current value of the expired notification wait time. | |
sACN receiver flags | |
Valid values for the flags member in the SacnReceiverConfig struct. | |
#define | SACN_RECEIVER_OPTS_FILTER_PREVIEW_DATA 0x1 |
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.
#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().
#define SACN_RECEIVER_CONFIG_DEFAULT_INIT |
A default-value initializer for an SacnReceiverConfig struct.
#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.
#define SACN_RECEIVER_INVALID -1 |
An invalid sACN receiver handle value.
#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 int sacn_receiver_t |
A handle to an sACN receiver.
typedef struct SacnLostSource SacnLostSource |
Information about a sACN source that was lost.
typedef struct SacnReceiverCallbacks SacnReceiverCallbacks |
A set of callback functions that the library uses to notify the application about sACN events.
typedef struct SacnReceiverConfig SacnReceiverConfig |
A set of configuration information for an sACN receiver.
typedef struct SacnReceiverNetintList SacnReceiverNetintList |
A set of network interfaces for a particular receiver.
typedef struct SacnRecvUniverseData SacnRecvUniverseData |
A complete description of newly received universe data within the configured footprint.
typedef struct SacnRecvUniverseSubrange SacnRecvUniverseSubrange |
Defines a range of addresses within a sACN universe.
typedef struct SacnRemoteSource SacnRemoteSource |
Information about a remote sACN source being tracked by a receiver.
typedef void(* SacnSamplingPeriodEndedCallback) (sacn_receiver_t handle, uint16_t universe, void *context) |
Notify that a receiver's sampling period has ended.
[in] | handle | Handle to the receiver instance for which the sampling period ended. |
[in] | universe | The universe this receiver is monitoring. |
[in] | context | Context pointer that was given at the creation of the receiver instance. |
typedef void(* SacnSamplingPeriodStartedCallback) (sacn_receiver_t handle, uint16_t universe, void *context) |
Notify that a receiver's sampling period has begun.
[in] | handle | Handle to the receiver instance for which the sampling period started. |
[in] | universe | The universe this receiver is monitoring. |
[in] | context | Context pointer that was given at the creation of the receiver instance. |
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.
[in] | handle | Handle to the receiver instance for which the source limit has been exceeded. |
[in] | universe | The universe this receiver is monitoring. |
[in] | context | Context pointer that was given at the creation of the receiver instance. |
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.
[in] | handle | Handle to the receiver instance for which a source stopped sending per-address priority. |
[in] | universe | The universe this receiver is monitoring. |
[in] | source | Information about the source that has stopped transmission of per-address priority. |
[in] | context | Context pointer that was given at the creation of the receiver instance. |
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.
[in] | handle | Handle to the receiver instance for which sources were lost. |
[in] | universe | The universe this receiver is monitoring. |
[in] | lost_sources | Array of structs describing the source or sources that have been lost. |
[in] | num_lost_sources | Size of the lost_sources array. |
[in] | context | Context pointer that was given at the creation of the receiver instance. |
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.
[in] | receiver_handle | Handle to the receiver instance for which universe data was received. |
[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 receiver instance. |
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.
[in] | handle | Handle to the receiver for which to change the universe. |
[in] | new_footprint | New footprint that this receiver should listen to. |
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.
[in] | handle | Handle to the receiver for which to change the universe. |
[in] | new_universe_id | New universe number that this receiver should listen to. |
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.
[in] | handle | Handle to the receiver for which to change the universe. |
[in] | new_universe_id | New universe number that this receiver should listen to. |
[in] | new_footprint | New footprint within the universe. |
void sacn_receiver_config_init | ( | SacnReceiverConfig * | config | ) |
Initialize an sACN Receiver Config struct to default values.
[out] | config | Config struct to initialize. |
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.
[in] | config | Configuration parameters for the sACN receiver to be created. |
[out] | handle | Filled in on success with a handle to the sACN 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. |
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.
[in] | handle | Handle to the receiver to destroy. |
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).
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.
[in] | handle | Handle to the receiver that we want to query. |
[out] | footprint | The retrieved footprint. |
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.
[in] | handle | Handle to the 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. |
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.
[in] | handle | Handle to the receiver that we want to query. |
[out] | universe_id | The retrieved universe. |
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.
[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. |
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.
[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 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_lists | The size of netint_lists. Must not be 0. |
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).
[in] | wait_ms | Wait time in milliseconds. |