An instance of sACN Source Detector functionality. More...

#include <source_detector.h>

Data Structures
class	NotifyHandler
	A base class for a class that receives notification callbacks from a sACN Source Detector. More...

struct	Settings
	A set of configuration settings that a source detector needs to initialize. More...

Static Public Member Functions
static etcpal::Error	Startup (NotifyHandler &notify_handler)
	Start the sACN Source Detector with default settings.

static etcpal::Error	Startup (NotifyHandler &notify_handler, std::vector< SacnMcastInterface > &netints)
	Start the sACN Source Detector with default settings.

static etcpal::Error	Startup (const Settings &settings, NotifyHandler &notify_handler)
	Start the sACN Source Detector.

static etcpal::Error	Startup (const Settings &settings, NotifyHandler &notify_handler, std::vector< SacnMcastInterface > &netints)
	Start the sACN Source Detector.

static void	Shutdown ()
	Destroy the sACN Source Detector.

static etcpal::Error	ResetNetworking ()
	Resets the underlying network sockets and packet receipt state for the sACN Source Detector.

static etcpal::Error	ResetNetworking (std::vector< SacnMcastInterface > &netints)
	Resets the underlying network sockets and packet receipt state for the sACN Source Detector.

static std::vector< EtcPalMcastNetintId >	GetNetworkInterfaces ()
	Obtain the source detector's network interfaces.

Detailed Description

An instance of sACN Source Detector functionality.

sACN sources often periodically send Universe Discovery packets to announce what universes they are sourcing. Use this API to monitor such traffic for your own needs.

There can only ever be one instance of the source detector (thus the static interface), but that instance still needs to be created and can be destroyed.

Usage:

#include "sacn/cpp/source_detector.h"
 
EtcPalLogParams log_params = ETCPAL_LOG_PARAMS_INIT;
// Initialize log_params...
 
etcpal::Error init_result = sacn::Init(&log_params);
// Or, to init without worrying about logs from the sACN library...
etcpal::Error init_result = sacn::Init();
 
std::vector<SacnMcastInterface> my_netints;
// Assuming my_netints is initialized by the application...
 
MyNotifyHandler my_notify;  // MyNotifyHandler is an application-defined class for implementing notifications.
 
// If you want to specify specific network interfaces to use:
etcpal::Error startup_result = sacn::SourceDetector::Startup(my_notify, my_netints);
// Or, if you just want to use all network interfaces:
etcpal::Error startup_result = sacn::SourceDetector::Startup(my_notify);
// Check startup_result here...
 
// Now the thread is running and your callbacks will handle application-side processing.
 
// What if your network interfaces change? Update my_netints and call this:
etcpal::Error reset_result = sacn::SourceDetector::ResetNetworking(my_netints);
// Check reset_result here...
 
// To destroy the source detector, call this:
sacn::SourceDetector::Shutdown();
 
// During application shutdown, everything can be cleaned up by calling sacn::Deinit.
sacn::Deinit();

Callback demonstrations:

void MyNotifyHandler::HandleSourceUpdated(sacn::RemoteSourceHandle handle, const etcpal::Uuid& cid,
                                          const std::string& name, const std::vector<uint16_t>& sourced_universes)
{
  std::cout << "Source Detector: Source " << cid.ToString() << " (name " << name << ") ";
  if(!sourced_universes.empty())
  {
    std::cout << "is active on these universes: ";
    for(uint16_t univ : sourced_universes)
      std::cout << univ << " ";
    std::cout << "\n";
  }
  else
  {
    std::cout << "is not active on any universes.\n";
  }
}
 
void MyNotifyHandler::HandleSourceExpired(sacn::RemoteSourceHandle handle, const etcpal::Uuid& cid,
                                          const std::string& name)
{
  std::cout << "Source Detector: Source " << cid.ToString() << " (name " << name << ") has expired.\n";
}
 
void MyNotifyHandler::HandleMemoryLimitExceeded()
{
  std::cout << "Source Detector: Source/universe limit exceeded!\n";
}

Member Function Documentation

◆ GetNetworkInterfaces()

std::vector< EtcPalMcastNetintId > GetNetworkInterfaces ( )

inlinestatic

Obtain the source detector's network interfaces.

Returns: A vector of the source detector's network interfaces.

◆ ResetNetworking() [1/2]

etcpal::Error ResetNetworking ( )

inlinestatic

Resets the underlying network sockets and packet receipt state for the sACN Source Detector.

This is an override of ResetNetworking that uses all network interfaces.

This is typically used when the application detects that the list of networking interfaces has changed. The source detector API will no longer be limited to specific interfaces (the list passed into sacn::Init(), if any, is overridden for the source detector API, but not the other APIs). The source detector is set to all system interfaces.

After this call completes successfully, the detector will continue as if nothing had changed. New sources could be discovered, or old sources could expire. If this call fails, the caller must call Shutdown(), because the source detector 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: Network changed successfully.; kEtcPalErrNoNetints: None of the network interfaces were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: The detector has not yet been created.; kEtcPalErrSys: An internal library or system call error occurred.

◆ ResetNetworking() [2/2]

etcpal::Error ResetNetworking ( std::vector< SacnMcastInterface > & sys_netints )

inlinestatic

Resets the underlying network sockets and packet receipt state for the sACN Source Detector.

This is typically used when the application detects that the list of networking interfaces has changed. This changes the list of system interfaces the source detector API will be limited to (the list passed into sacn::Init(), if any, is overridden for the source detector API, but not the other APIs). The source detector is then set to those interfaces.

After this call completes successfully, the detector will continue as if nothing had changed. New sources could be discovered, or old sources could expire. If this call fails, the caller must call Shutdown(), because the source detector 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 source detector API will be limited to, and the status codes are filled in. If empty, the source detector API is allowed to use all available system interfaces.

Returns: kEtcPalErrOk: Network changed successfully.; kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: The detector has not yet been created.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Shutdown()

void Shutdown ( )

inlinestatic

Destroy the sACN Source Detector.

Returns: kEtcPalErrOk: Detector destroyed successfully.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: The detector has not yet been created.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Startup() [1/4]

etcpal::Error Startup	(	const Settings &	settings,
		NotifyHandler &	notify_handler )

inlinestatic

Start the sACN Source Detector.

This is an override of Startup that uses all network interfaces.

Note that the detector 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 Source Detector to be created.
[in]	notify_handler	The callback handler for the sACN Source Detector to be created.

Returns: kEtcPalErrOk: Detector created successfully.; kEtcPalErrNoNetints: None of the network interfaces were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No room to allocate memory for the detector.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Startup() [2/4]

etcpal::Error Startup	(	const Settings &	settings,
		NotifyHandler &	notify_handler,
		std::vector< SacnMcastInterface > &	netints )

inlinestatic

Start the sACN Source Detector.

Note that the detector 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 Source Detector to be created.
[in]	notify_handler	The callback handler for the sACN Source Detector to be created.
[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: Detector created successfully.; kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No room to allocate memory for the detector.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Startup() [3/4]

etcpal::Error Startup ( NotifyHandler & notify_handler )

inlinestatic

Start the sACN Source Detector with default settings.

This is an override of Startup that has default settings for the configuration and will use all network interfaces.

Note that the detector 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] notify_handler The callback handler for the sACN Source Detector to be created.

Returns: kEtcPalErrOk: Detector created successfully.; kEtcPalErrNoNetints: None of the network interfaces were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No room to allocate memory for the detector.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Startup() [4/4]

etcpal::Error Startup	(	NotifyHandler &	notify_handler,
		std::vector< SacnMcastInterface > &	netints )

inlinestatic

Start the sACN Source Detector with default settings.

This is an override of Startup that doesn't require a Settings parameter, since the fields in that structure are completely optional.

Note that the detector 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]	notify_handler	The callback handler for the sACN Source Detector to be created.
[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: Detector created successfully.; kEtcPalErrNoNetints: None of the network interfaces provided were usable by the library.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No room to allocate memory for the detector.; kEtcPalErrSys: An internal library or system call error occurred.

The documentation for this class was generated from the following file:

include/sacn/cpp/source_detector.h

Data Structures

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ GetNetworkInterfaces()

◆ ResetNetworking() [1/2]

◆ ResetNetworking() [2/2]

◆ Shutdown()

◆ Startup() [1/4]

◆ Startup() [2/4]

◆ Startup() [3/4]

◆ Startup() [4/4]