Discovery

Overview

Handle RDMnet discovery using mDNS and DNS-SD.

RDMnet uses DNS-SD (aka Bonjour) as its network discovery method. These functions encapsulate system DNS-SD and mDNS functionality (Bonjour, Avahi, etc.) and provide functions for doing broker discovery and service registration.

Typically, this API is called automatically when using the role APIs:

• Controller API
• Device API
• Broker API
• EPT Client API

And thus these functions should not typically need to be used directly.

Data Structures
struct	RdmnetDnsTxtRecordItem
	An extra key/value pair in a broker's DNS TXT record that does not have a standard RDMnet use. More...
struct	RdmnetBrokerDiscInfo
	Information about a broker discovered or registered using DNS-SD. More...
struct	RdmnetDiscBrokerCallbacks
	A set of notification callbacks received by a registered broker instance. More...
struct	RdmnetBrokerRegisterConfig
	A set of information that defines the parameters of an RDMnet broker registered with DNS-SD. More...
struct	RdmnetScopeMonitorCallbacks
	A set of notification callbacks received by a scope monitor instance. More...
struct	RdmnetScopeMonitorConfig
	A set of information that defines the parameters of an RDMnet scope to be monitored using DNS-SD. More...

Macros
#define	RDMNET_REGISTERED_BROKER_INVALID   NULL
	An invalid registered broker value.
#define	RDMNET_BROKER_REGISTER_CONFIG_DEFAULT_INIT
	A default-value initializer for an RdmnetBrokerRegisterConfig struct. More...
#define	RDMNET_SCOPE_MONITOR_INVALID   NULL
	An invalid monitored scope handle value.
#define	RDMNET_SCOPE_MONITOR_CONFIG_DEFAULT_INIT
	A default-value initializer for an RdmnetScopeMonitorConfig struct. More...

Typedefs
typedef struct RdmnetDnsTxtRecordItem	RdmnetDnsTxtRecordItem
	An extra key/value pair in a broker's DNS TXT record that does not have a standard RDMnet use. More...
typedef struct RdmnetBrokerRegisterRef *	rdmnet_registered_broker_t
	A handle to an RDMnet broker's DNS-SD registration.
typedef struct RdmnetBrokerDiscInfo	RdmnetBrokerDiscInfo
	Information about a broker discovered or registered using DNS-SD.
typedef struct RdmnetDiscBrokerCallbacks	RdmnetDiscBrokerCallbacks
	A set of notification callbacks received by a registered broker instance.
typedef struct RdmnetBrokerRegisterConfig	RdmnetBrokerRegisterConfig
	A set of information that defines the parameters of an RDMnet broker registered with DNS-SD.
typedef struct RdmnetScopeMonitorRef *	rdmnet_scope_monitor_t
	A handle to a monitored RDMnet scope.
typedef struct RdmnetScopeMonitorCallbacks	RdmnetScopeMonitorCallbacks
	A set of notification callbacks received by a scope monitor instance.
typedef struct RdmnetScopeMonitorConfig	RdmnetScopeMonitorConfig
	A set of information that defines the parameters of an RDMnet scope to be monitored using DNS-SD.

Functions
void	rdmnet_broker_register_config_init (RdmnetBrokerRegisterConfig *config)
	Initialize an RdmnetBrokerRegisterConfig with default values for the optional config options. More...
void	rdmnet_broker_register_config_set_callbacks (RdmnetBrokerRegisterConfig *config, RdmnetDiscBrokerRegisteredCallback broker_registered, RdmnetDiscBrokerRegisterFailedCallback broker_register_failed, RdmnetDiscOtherBrokerFoundCallback other_broker_found, RdmnetDiscOtherBrokerLostCallback other_broker_lost, void *context)
	Set the callbacks in an RDMnet broker register configuration structure. More...
void	rdmnet_scope_monitor_config_init (RdmnetScopeMonitorConfig *config)
	Initialize an RdmnetScopeMonitorConfig with default values for the optional config options. More...
void	rdmnet_scope_monitor_config_set_callbacks (RdmnetScopeMonitorConfig *config, RdmnetDiscBrokerFoundCallback broker_found, RdmnetDiscBrokerUpdatedCallback broker_udpated, RdmnetDiscBrokerLostCallback broker_lost, void *context)
	Set the callbacks in an RDMnet scope monitor configuration structure. More...
etcpal_error_t	rdmnet_disc_start_monitoring (const RdmnetScopeMonitorConfig *config, rdmnet_scope_monitor_t *handle, int *platform_specific_error)
	Begin monitoring an RDMnet scope for brokers. More...
void	rdmnet_disc_stop_monitoring (rdmnet_scope_monitor_t handle)
	Stop monitoring an RDMnet scope for brokers. More...
void	rdmnet_disc_stop_monitoring_all (void)
	Stop monitoring all RDMnet scopes for brokers. More...
etcpal_error_t	rdmnet_disc_register_broker (const RdmnetBrokerRegisterConfig *config, rdmnet_registered_broker_t *handle)
	Register an RDMnet broker on a scope. More...
void	rdmnet_disc_unregister_broker (rdmnet_registered_broker_t handle)
	Unegister an RDMnet broker on a scope. More...

Registered Broker Callbacks
typedef void(*	RdmnetDiscBrokerRegisteredCallback) (rdmnet_registered_broker_t handle, const char *assigned_service_instance_name, void *context)
	A broker has been registered successfully with the DNS-SD service. More...
typedef void(*	RdmnetDiscBrokerRegisterFailedCallback) (rdmnet_registered_broker_t handle, int platform_error, void *context)
	Broker registration has failed. More...
typedef void(*	RdmnetDiscOtherBrokerFoundCallback) (rdmnet_registered_broker_t handle, const RdmnetBrokerDiscInfo *broker_info, void *context)
	Another broker has been found on the scope on which this broker is registered. More...
typedef void(*	RdmnetDiscOtherBrokerLostCallback) (rdmnet_registered_broker_t handle, const char *scope, const char *service_instance_name, void *context)
	A broker which was previously detected on the same scope as a registered broker has been lost. More...

Scope Monitor Callbacks
typedef void(*	RdmnetDiscBrokerFoundCallback) (rdmnet_scope_monitor_t handle, const RdmnetBrokerDiscInfo *broker_info, void *context)
	An RDMnet broker has been found on a monitored scope. More...
typedef void(*	RdmnetDiscBrokerUpdatedCallback) (rdmnet_scope_monitor_t handle, const RdmnetBrokerDiscInfo *updated_broker_info, void *context)
	Updated information has been received for a previously-discovered RDMnet broker. More...
typedef void(*	RdmnetDiscBrokerLostCallback) (rdmnet_scope_monitor_t handle, const char *scope, const char *service_instance_name, void *context)
	A previously-discovered RDMnet broker has been lost on a monitored scope. More...

Macro Definition Documentation

RDMNET_BROKER_REGISTER_CONFIG_DEFAULT_INIT

#define RDMNET_BROKER_REGISTER_CONFIG_DEFAULT_INIT

Value:

  {                                                                                           \
    {{0}}, {0}, NULL, 0, NULL, 0, NULL, NULL, NULL, NULL, 0, { NULL, NULL, NULL, NULL, NULL } \
  }

A default-value initializer for an RdmnetBrokerRegisterConfig struct.

Usage:

RdmnetBrokerRegisterConfig config = RDMNET_BROKER_REGISTER_CONFIG_DEFAULT_INIT;
// Now fill in the required portions as necessary with your data...

RDMNET_SCOPE_MONITOR_CONFIG_DEFAULT_INIT

#define RDMNET_SCOPE_MONITOR_CONFIG_DEFAULT_INIT

Value:

  {                                              \
    E133_DEFAULT_SCOPE, {NULL, NULL, NULL}, NULL \
  }

A default-value initializer for an RdmnetScopeMonitorConfig struct.

Usage:

RdmnetScopeMonitorConfig config = RDMNET_SCOPE_MONITOR_CONFIG_DEFAULT_INIT;
// Now fill in the required portions as necessary with your data...

Typedef Documentation

RdmnetDiscBrokerFoundCallback

typedef void(* RdmnetDiscBrokerFoundCallback) (rdmnet_scope_monitor_t handle, const RdmnetBrokerDiscInfo *broker_info, void *context)

An RDMnet broker has been found on a monitored scope.

Parameters

handle	Handle to the monitored scope on which the broker was found.
broker_info	Information about the broker that was found.
context	Context pointer that was given at the creation of the scope monitor instance.

RdmnetDiscBrokerLostCallback

typedef void(* RdmnetDiscBrokerLostCallback) (rdmnet_scope_monitor_t handle, const char *scope, const char *service_instance_name, void *context)

A previously-discovered RDMnet broker has been lost on a monitored scope.

Parameters

handle	Handle to the monitored scope on which the broker was lost.
scope	Scope string of the monitored scope.
service_instance_name	Service instance name of the broker that has been lost.
context	Context pointer that was given at the creation of the scope monitor instance.

RdmnetDiscBrokerRegisteredCallback

typedef void(* RdmnetDiscBrokerRegisteredCallback) (rdmnet_registered_broker_t handle, const char *assigned_service_instance_name, void *context)

A broker has been registered successfully with the DNS-SD service.

Parameters

[in]	handle	Handle to the registered broker instance.
[in]	assigned_service_instance_name	The broker's service instance name. Note that this might be different from the one given at config time because of DNS-SD's uniqueness negotiation.
[in]	context	Context pointer that was given at the creation of the registered broker instance.

RdmnetDiscBrokerRegisterFailedCallback

typedef void(* RdmnetDiscBrokerRegisterFailedCallback) (rdmnet_registered_broker_t handle, int platform_error, void *context)

Broker registration has failed.

Parameters

[in]	handle	Handle to the registered broker instance which has failed to register.
[in]	platform_error	Platform-specific error code from the underlying DNS-SD service (e.g. Bonjour or Avahi).
[in]	context	Context pointer that was given at the creation of the registered broker instance.

RdmnetDiscBrokerUpdatedCallback

typedef void(* RdmnetDiscBrokerUpdatedCallback) (rdmnet_scope_monitor_t handle, const RdmnetBrokerDiscInfo *updated_broker_info, void *context)

Updated information has been received for a previously-discovered RDMnet broker.

Parameters

handle	Handle to the monitored scope on which the broker was updated.
updated_broker_info	Updated broker information.
context	Context pointer that was given at the creation of the scope monitor instance.

RdmnetDiscOtherBrokerFoundCallback

typedef void(* RdmnetDiscOtherBrokerFoundCallback) (rdmnet_registered_broker_t handle, const RdmnetBrokerDiscInfo *broker_info, void *context)

Another broker has been found on the scope on which this broker is registered.

Parameters

[in]	handle	Handle to the registered broker instance.
[in]	broker_info	Information about the other broker that has been found on the same scope.
[in]	context	Context pointer that was given at the creation of the registered broker instance.

RdmnetDiscOtherBrokerLostCallback

typedef void(* RdmnetDiscOtherBrokerLostCallback) (rdmnet_registered_broker_t handle, const char *scope, const char *service_instance_name, void *context)

A broker which was previously detected on the same scope as a registered broker has been lost.

Parameters

[in]	handle	Handle to the registered broker instance.
[in]	scope	Scope string of the scope on which the broker is registered.
[in]	service_instance_name	Service instance name of the other broker that has been lost.
[in]	context	Context pointer that was given at the creation of the registered broker instance.

RdmnetDnsTxtRecordItem

typedef struct RdmnetDnsTxtRecordItem RdmnetDnsTxtRecordItem

An extra key/value pair in a broker's DNS TXT record that does not have a standard RDMnet use.

DNS-SD TXT records are key/value pairs where the key is printable ASCII and the value is opaque binary data. The total length of the key plus the value cannot exceed 255 bytes.

Function Documentation

rdmnet_broker_register_config_init()

void rdmnet_broker_register_config_init

(

RdmnetBrokerRegisterConfig *

config

)

Initialize an RdmnetBrokerRegisterConfig with default values for the optional config options.

The config struct members not marked 'optional' are not meaningfully initialized by this function. Those members do not have default values and must be initialized manually before passing the config struct to an API function.

Usage example:

RdmnetBrokerRegisterConfig config;
rdmnet_broker_register_config_init(&config);

Parameters

[out]

config

Pointer to RdmnetBrokerRegisterConfig to init.

rdmnet_broker_register_config_set_callbacks()

void rdmnet_broker_register_config_set_callbacks	(	RdmnetBrokerRegisterConfig *	config,
		RdmnetDiscBrokerRegisteredCallback	broker_registered,
		RdmnetDiscBrokerRegisterFailedCallback	broker_register_failed,
		RdmnetDiscOtherBrokerFoundCallback	other_broker_found,
		RdmnetDiscOtherBrokerLostCallback	other_broker_lost,
		void *	context
	)

Set the callbacks in an RDMnet broker register configuration structure.

Items marked "optional" can be NULL.

Parameters

[out]	config	Config struct in which to set the callbacks.
[in]	broker_registered	Callback called when a broker is successfully registered.
[in]	broker_register_failed	Callback called when a broker registration has failed.
[in]	other_broker_found	Callback called when another broker is found on the same scope as a registered broker.
[in]	other_broker_lost	Callback called when a broker previously found on the same scope as a registered broker has gone away.
[in]	context	(optional) Pointer to opaque data passed back with each callback.

rdmnet_disc_register_broker()

etcpal_error_t rdmnet_disc_register_broker	(	const RdmnetBrokerRegisterConfig *	config,
		rdmnet_registered_broker_t *	handle
	)

Register an RDMnet broker on a scope.

The library will also monitor the given scope for conflicting brokers. There will be a holdoff period initially where the scope will be queried for conflicting brokers before registering. If a conflicting broker is found during this time, you will get a broker_found() callback and no broker_registered() callback - this indicates that the local broker should shutdown until receiving a corresponding broker_lost() callback.

The broker_registered() callback will be called when the broker is successfully registered.

Asynchronous register and monitoring errors can also be delivered via the broker_register_error() and scope_monitor_error() callbacks.

This function will deadlock if called directly from an RDMnet discovery callback.

Parameters

[in]	config	Configuration struct with details about the broker to register.
[out]	handle	Filled in on success with a handle that can be used to access the registered broker later.

Returns

kEtcPalErrOk: Monitoring started successfully.

kEtcPalErrInvalid: Invalid argument.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNoMem: Couldn't allocate resources to register this broker.

kEtcPalErrSys: An internal library or system call error occurred.

rdmnet_disc_start_monitoring()

etcpal_error_t rdmnet_disc_start_monitoring	(	const RdmnetScopeMonitorConfig *	config,
		rdmnet_scope_monitor_t *	handle,
		int *	platform_specific_error
	)

Begin monitoring an RDMnet scope for brokers.

Expect to receive callbacks from the RDMnet tick thread when brokers are found and lost. Asynchronous monitoring errors can also be delivered via the scope_monitor_error callback.

This function will deadlock if called directly from an RDMnet discovery callback.

Parameters

[in]	config	Configuration struct with details about the scope to monitor.
[out]	handle	Filled in on success with a handle that can be used to access the monitored scope later.
[out]	platform_specific_error	Filled in on failure with a platform-specific error code.

Returns

kEtcPalErrOk: Monitoring started successfully.

kEtcPalErrInvalid: Invalid argument.

kEtcPalErrNotInit: Module not initialized.

kEtcPalErrNoMem: Couldn't allocate resources to monitor this scope.

kEtcPalErrSys: An internal library or system call error occurred.

rdmnet_disc_stop_monitoring()

void rdmnet_disc_stop_monitoring

(

rdmnet_scope_monitor_t

handle

)

Stop monitoring an RDMnet scope for brokers.

This function will deadlock if called directly from an RDMnet discovery callback.

Parameters

[in]

handle

Scope handle to stop monitoring.

rdmnet_disc_stop_monitoring_all()

void rdmnet_disc_stop_monitoring_all

(

void

)

Stop monitoring all RDMnet scopes for brokers.

This function will deadlock if called directly from an RDMnet discovery callback.

rdmnet_disc_unregister_broker()

void rdmnet_disc_unregister_broker

(

rdmnet_registered_broker_t

handle

)

Unegister an RDMnet broker on a scope.

This function will deadlock if called directly from an RDMnet discovery callback.

Parameters

[in]

handle

Broker handle to unregister.

rdmnet_scope_monitor_config_init()

void rdmnet_scope_monitor_config_init

(

RdmnetScopeMonitorConfig *

config

)

Initialize an RdmnetScopeMonitorConfig with default values for the optional config options.

The config struct members not marked 'optional' are not meaningfully initialized by this function. Those members do not have default values and must be initialized manually before passing the config struct to an API function.

Usage example:

RdmnetScopeMonitorConfig config;
rdmnet_scope_monitor_config_init(&config);

Parameters

[out]

config

Pointer to RdmnetScopeMonitorConfig to init.

rdmnet_scope_monitor_config_set_callbacks()

void rdmnet_scope_monitor_config_set_callbacks	(	RdmnetScopeMonitorConfig *	config,
		RdmnetDiscBrokerFoundCallback	broker_found,
		RdmnetDiscBrokerUpdatedCallback	broker_updated,
		RdmnetDiscBrokerLostCallback	broker_lost,
		void *	context
	)

Set the callbacks in an RDMnet scope monitor configuration structure.

Items marked "optional" can be NULL.

Parameters

[out]	config	Config struct in which to set the callbacks.
[in]	broker_found	Callback called when a broker is discovered on the scope.
[in]	broker_updated	Callback called when a previously-discovered broker's information is updated.
[in]	broker_lost	Callback called when a previously-discovered broker is lost.
[in]	context	(optional) Pointer to opaque data passed back with each callback.