sACN Source Detector

The sACN Source Detector API. More...

Data Structures
struct	SacnSourceDetectorCallbacks
struct	SacnSourceDetectorConfig

Macros
#define	SACN_SOURCE_DETECTOR_INFINITE   0
	Constant for "infinite" when listening for sources or universes on a source.
#define	SACN_SOURCE_DETECTOR_CONFIG_DEFAULT_INIT

Typedefs
typedef void(*	SacnSourceDetectorSourceUpdatedCallback) (sacn_remote_source_t handle, const EtcPalUuid *cid, const char *name, const uint16_t *sourced_universes, size_t num_sourced_universes, void *context)
	Notify that a source is new or has changed.
typedef void(*	SacnSourceDetectorSourceExpiredCallback) (sacn_remote_source_t handle, const EtcPalUuid *cid, const char *name, void *context)
	Notify that a source is no longer transmitting Universe Discovery messages.
typedef void(*	SacnSourceDetectorLimitExceededCallback) (void *context)
	Notify that the module has run out of memory to track universes or sources.
typedef struct SacnSourceDetectorCallbacks	SacnSourceDetectorCallbacks
typedef struct SacnSourceDetectorConfig	SacnSourceDetectorConfig

Functions
void	sacn_source_detector_config_init (SacnSourceDetectorConfig *config)
	Initialize an sACN Source Detector Config struct to default values.
etcpal_error_t	sacn_source_detector_create (const SacnSourceDetectorConfig *config, const SacnNetintConfig *netint_config)
	Create the sACN Source Detector.
void	sacn_source_detector_destroy ()
	Destroy the sACN Source Detector.
etcpal_error_t	sacn_source_detector_reset_networking (const SacnNetintConfig *sys_netint_config)
	Updates the source detector system network interfaces. Also resets the underlying network sockets for the sACN Source Detector if it was created.
size_t	sacn_source_detector_get_network_interfaces (EtcPalMcastNetintId *netints, size_t netints_size)
	Obtain the source detector's network interfaces.

Detailed Description

The sACN Source Detector API.

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, but that instance still needs to be created and can be destroyed.

Usage:

#include "sacn/source_detector.h"
 
EtcPalLogParams log_params = ETCPAL_LOG_PARAMS_INIT;
// Initialize log_params...
 
etcpal_error_t init_result = sacn_init(&log_params, NULL);
// Or, to init without worrying about logs from the sACN library...
etcpal_error_t init_result = sacn_init(NULL, NULL);
 
SacnSourceDetectorConfig my_config = SACN_SOURCE_DETECTOR_CONFIG_DEFAULT_INIT;
my_config.callbacks.source_updated = my_source_updated;
my_config.callbacks.source_expired = my_source_expired;
my_config.callbacks.limit_exceeded = my_limit_exceeded;
 
SacnMcastInterface my_netints[NUM_MY_NETINTS];
// Assuming my_netints and NUM_MY_NETINTS are initialized by the application...
 
SacnNetintConfig netint_config;
netint_config.netints = my_netints;
netint_config.num_netints = NUM_MY_NETINTS;
 
// If you want to specify specific network interfaces to use:
etcpal_error_t create_result = sacn_source_detector_create(&my_config, &netint_config);
// Or, if you just want to use all network interfaces:
etcpal_error_t create_result = sacn_source_detector_create(&my_config, NULL);
// Check create_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_t reset_result = sacn_source_detector_reset_networking(my_netints, NUM_MY_NETINTS);
// Check reset_result here...
 
// To destroy the source detector, call this:
sacn_source_detector_destroy();
 
// During application shutdown, everything can be cleaned up by calling sacn_deinit.
sacn_deinit();

Callback demonstrations:

void my_source_updated(sacn_remote_source_t handle, const EtcPalUuid* cid, const char* name,
                       const uint16_t* sourced_universes, size_t num_sourced_universes, void* context)
{
  if (cid && name)
  {
    char cid_str[ETCPAL_UUID_STRING_BYTES];
    etcpal_uuid_to_string(cid, cid_str);
    printf("Source Detector: Source %s (name %s) ", cid_str, name);
    if(sourced_universes)
    {
      printf("is active on these universes: ");
      for(size_t i = 0; i < num_sourced_universes; ++i)
        printf("%d ", sourced_universes[i]);
      printf("\n");
    }
    else
    {
      printf("is not active on any universes.\n");
    }
  }
}
 
void my_source_expired(sacn_remote_source_t handle, const EtcPalUuid* cid, const char* name, void* context)
{
  if (cid && name)
  {
    char cid_str[ETCPAL_UUID_STRING_BYTES];
    etcpal_uuid_to_string(cid, cid_str);
    printf("Source Detector: Source %s (name %s) has expired.\n", cid_str, name);
  }
}
 
void my_limit_exceeded(void* context)
{
  printf("Source Detector: Source/universe limit exceeded!\n");
}

Macro Definition Documentation

SACN_SOURCE_DETECTOR_CONFIG_DEFAULT_INIT

#define SACN_SOURCE_DETECTOR_CONFIG_DEFAULT_INIT

Value:

  {                                                                                                          \
    {NULL, NULL, NULL, NULL}, SACN_SOURCE_DETECTOR_INFINITE, SACN_SOURCE_DETECTOR_INFINITE, kSacnIpV4AndIpV6 \
  }

A default-value initializer for an SacnSourceDetectorConfig struct.

SACN_SOURCE_DETECTOR_INFINITE

#define SACN_SOURCE_DETECTOR_INFINITE   0

Constant for "infinite" when listening for sources or universes on a source.

When using dynamic memory, this constant can be passed in when creating a source detector. It represents an infinite number of sources or universes on a source.

Typedef Documentation

SacnSourceDetectorCallbacks

typedef struct SacnSourceDetectorCallbacks SacnSourceDetectorCallbacks

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

SacnSourceDetectorConfig

typedef struct SacnSourceDetectorConfig SacnSourceDetectorConfig

A set of configuration information for the sACN Source Detector.

SacnSourceDetectorLimitExceededCallback

typedef void(* SacnSourceDetectorLimitExceededCallback) (void *context)

Notify that the module has run out of memory to track universes or sources.

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_source_detector_create() has source_count_max and universes_per_source_max set to SACN_SOURCE_DETECTOR_INFINITE, this callback will never be called (except for the rare case where a heap allocation function fails) and may be set to NULL.

If SACN_DYNAMIC_MEM was defined to 0 when sACN was compiled, source_count_max and universes_per_source_max are ignored and SACN_SOURCE_DETECTOR_MAX_SOURCES and SACN_SOURCE_DETECTOR_MAX_UNIVERSES_PER_SOURCE are used instead.

This callback is rate-limited: it will only be called the first time a source or universe limit is exceeded. After that, it will not be called until the number of sources or universes has dropped below their limit and hits it again.

Parameters

[in]

context

Context pointer that was given at the creation of the source detector instance.

SacnSourceDetectorSourceExpiredCallback

typedef void(* SacnSourceDetectorSourceExpiredCallback) (sacn_remote_source_t handle, const EtcPalUuid *cid, const char *name, void *context)

Notify that a source is no longer transmitting Universe Discovery messages.

Parameters

[in]	handle	The handle uniquely identifying the source.
[in]	cid	The CID of the source.
[in]	name	The null-terminated UTF-8 string.
[in]	context	Context pointer that was given at the creation of the source detector instance.

SacnSourceDetectorSourceUpdatedCallback

typedef void(* SacnSourceDetectorSourceUpdatedCallback) (sacn_remote_source_t handle, const EtcPalUuid *cid, const char *name, const uint16_t *sourced_universes, size_t num_sourced_universes, void *context)

Notify that a source is new or has changed.

This passes the source's current universe list, but you will only get this callback when the module detects that the source is new or the list has somehow changed.

The protocol requires the list of sourced universes to be numerically sorted. The library enforces this rule by checking that the universe list is in ascending order before notifying.

Parameters

[in]	handle	The handle uniquely identifying the source.
[in]	cid	The CID of the source.
[in]	name	The null-terminated UTF-8 string.
[in]	sourced_universes	Numerically sorted array of the currently sourced universes. Will be NULL if the source is not currently transmitting any universes.
[in]	num_sourced_universes	Size of the sourced_universes array. Will be 0 if the source is not currently transmitting any universes.
[in]	context	Context pointer that was given at the creation of the source detector instance.

Function Documentation

sacn_source_detector_config_init()

void sacn_source_detector_config_init

(

SacnSourceDetectorConfig *

config

)

Initialize an sACN Source Detector Config struct to default values.

Parameters

[out]

config

Config struct to initialize.

sacn_source_detector_create()

etcpal_error_t sacn_source_detector_create	(	const SacnSourceDetectorConfig *	config,
		const SacnNetintConfig *	netint_config )

Create 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]	config	Configuration parameters for the sACN source detector.
[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: 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.

sacn_source_detector_get_network_interfaces()

size_t sacn_source_detector_get_network_interfaces	(	EtcPalMcastNetintId *	netints,
		size_t	netints_size )

Obtain the source detector's network interfaces.

Parameters

[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 source detector. If this is greater than netints_size, then only netints_size addresses were written to the netints array. If the source detector has not been created yet, 0 is returned.

sacn_source_detector_reset_networking()

etcpal_error_t sacn_source_detector_reset_networking

(

const SacnNetintConfig *

sys_netint_config

)

Updates the source detector system network interfaces. Also resets the underlying network sockets for the sACN Source Detector if it was created.

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 sacn_source_detector_destroy, because the 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

[in,out]

sys_netint_config

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

kEtcPalErrSys: An internal library or system call error occurred.