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

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

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
 
Receiveroperator= (const Receiver &other)=delete
 
 Receiver (Receiver &&other)=default
 
Receiveroperator= (Receiver &&other)=default
 
etcpal::Error Startup (const Settings &settings, NotifyHandler &notify_handler)
 Start listening for sACN data on a universe. More...
 
etcpal::Error Startup (const Settings &settings, NotifyHandler &notify_handler, std::vector< SacnMcastInterface > &netints)
 Start listening for sACN data on a universe. More...
 
void Shutdown ()
 Stop listening for sACN data on a universe. More...
 
etcpal::Expected< uint16_t > GetUniverse () const
 Get the universe this receiver is listening to. More...
 
etcpal::Expected< SacnRecvUniverseSubrangeGetFootprint () const
 Get the footprint within the universe this receiver is listening to. More...
 
etcpal::Error ChangeUniverse (uint16_t new_universe_id)
 Change the universe this receiver is listening to. More...
 
etcpal::Error ChangeFootprint (const SacnRecvUniverseSubrange &new_footprint)
 Change the footprint within the universe this receiver is listening to. TODO: Not yet implemented. More...
 
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. More...
 
std::vector< EtcPalMcastNetintIdGetNetworkInterfaces ()
 Obtain a vector of this receiver's network interfaces. More...
 
constexpr Handle handle () const
 Get the current handle to the underlying C receiver. More...
 

Static Public Member Functions

static void SetExpiredWait (uint32_t wait_ms)
 Set the expired notification wait time. More...
 
static uint32_t GetExpiredWait ()
 Get the current value of the expired notification wait time. More...
 
static etcpal::Error ResetNetworking ()
 Resets the underlying network sockets and packet receipt state for all sACN receivers. More...
 
static etcpal::Error ResetNetworking (std::vector< SacnMcastInterface > &netints)
 Resets underlying network sockets and packet receipt state, determines network interfaces for all receivers. More...
 
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. More...
 

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

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_footprintNew 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_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.

◆ 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_idNew universe number that this receiver should listen to.
[in]new_footprintNew 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()

constexpr 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_netintsIf !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_netintsIf !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_listsVector 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_msWait 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]settingsConfiguration parameters for the sACN receiver and this class instance.
[in]notify_handlerThe 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]settingsConfiguration parameters for the sACN receiver and this class instance.
[in]notify_handlerThe notification interface to call back to the application.
[in,out]netintsOptional. 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: