Overview

Implementation of EPT client functionality; see Using the EPT Client API.

EPT clients use the Extensible Packet Transport protocol to exchange opaque, manufacturer-specific non-RDM data across the network topology defined by RDMnet. EPT clients participate in RDMnet scopes and exchange messages through an RDMnet broker, similarly to RDMnet controllers and devices.

See Using the EPT Client API for a detailed description of how to use this API.

Data Structures
struct	RdmnetEptClientCallbacks
	A set of notification callbacks received about an EPT client. More...

struct	RdmnetEptClientConfig
	A set of information that defines the startup parameters of an EPT client. More...

Macros
#define	RDMNET_EPT_CLIENT_INVALID -1
	An invalid RDMnet EPT Client handle value.

#define	RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT
	A default-value initializer for an RdmnetEptClientConfig struct. More...

Typedefs
typedef int	rdmnet_ept_client_t
	A handle to an RDMnet EPT Client.

typedef void(*	RdmnetEptClientConnectedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectedInfo info, void context)
	An EPT client has successfully connected to a broker. More...

typedef void(*	RdmnetEptClientConnectFailedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectFailedInfo info, void context)
	A connection attempt failed between an EPT client and a broker. More...

typedef void(*	RdmnetEptClientDisconnectedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientDisconnectedInfo info, void context)
	An EPT client which was previously connected to a broker has disconnected. More...

typedef void(*	RdmnetEptClientClientListUpdateReceivedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, client_list_action_t list_action, const RdmnetEptClientList client_list, void context)
	A client list update has been received from a broker. More...

typedef void(*	RdmnetEptClientDataReceivedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetEptData data, RdmnetSyncEptResponse response, void *context)
	EPT data has been received addressed to an EPT client. More...

typedef void(*	RdmnetEptClientStatusReceivedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetEptStatus status, void context)
	An EPT status message has been received in response to a previously-sent EPT data message. More...

typedef struct RdmnetEptClientCallbacks	RdmnetEptClientCallbacks
	A set of notification callbacks received about an EPT client.

typedef struct RdmnetEptClientConfig	RdmnetEptClientConfig
	A set of information that defines the startup parameters of an EPT client.

Functions
void	rdmnet_ept_client_config_init (RdmnetEptClientConfig *config)
	Initialize an RdmnetEptClientConfig with default values for the optional config options. More...

void	rdmnet_ept_client_set_callbacks (RdmnetEptClientConfig config, RdmnetEptClientConnectedCallback connected, RdmnetEptClientConnectFailedCallback connect_failed, RdmnetEptClientDisconnectedCallback disconnected, RdmnetEptClientClientListUpdateReceivedCallback client_list_update_received, RdmnetEptClientDataReceivedCallback data_received, RdmnetEptClientStatusReceivedCallback status_received, void context)
	Set the callbacks in an RDMnet EPT client configuration structure. More...

etcpal_error_t	rdmnet_ept_client_create (const RdmnetEptClientConfig config, rdmnet_ept_client_t handle)
	Create a new instance of RDMnet EPT client functionality. More...

etcpal_error_t	rdmnet_ept_client_destroy (rdmnet_ept_client_t client_handle, rdmnet_disconnect_reason_t disconnect_reason)
	Destroy an EPT client instance. More...

etcpal_error_t	rdmnet_ept_client_add_scope (rdmnet_ept_client_t client_handle, const RdmnetScopeConfig scope_config, rdmnet_client_scope_t scope_handle)
	Add a new scope to an EPT client instance. More...

etcpal_error_t	rdmnet_ept_client_add_default_scope (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t *scope_handle)
	Add a new scope representing the default RDMnet scope to an EPT client instance. More...

etcpal_error_t	rdmnet_ept_client_remove_scope (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, rdmnet_disconnect_reason_t disconnect_reason)
	Remove a previously-added scope from an EPT client instance. More...

etcpal_error_t	rdmnet_ept_client_change_scope (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetScopeConfig *new_scope_config, rdmnet_disconnect_reason_t disconnect_reason)
	Change the configuration of a scope on an EPT client. More...

etcpal_error_t	rdmnet_ept_client_get_scope (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, char scope_str_buf, EtcPalSockAddr static_broker_addr)
	Retrieve the scope string of a previously-added scope. More...

etcpal_error_t	rdmnet_ept_client_request_client_list (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle)
	Request a client list from a broker. More...

etcpal_error_t	rdmnet_ept_client_send_data (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const EtcPalUuid dest_cid, uint16_t manufacturer_id, uint16_t protocol_id, const uint8_t data, size_t data_len)
	Send data from an EPT client on a scope. More...

etcpal_error_t	rdmnet_ept_client_send_status (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const EtcPalUuid dest_cid, ept_status_code_t status_code, const char status_string)
	Send a status message from an EPT client on a scope. More...

Macro Definition Documentation

◆ RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT

#define RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT

Value:

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

A default-value initializer for an RdmnetEptClientConfig struct.

Usage:

RdmnetEptClientConfig config = RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT;

// Now fill in the required portions as necessary with your data...

RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT

#define RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT

A default-value initializer for an RdmnetEptClientConfig struct.

Definition: ept_client.h:188

RdmnetEptClientConfig

A set of information that defines the startup parameters of an EPT client.

Definition: ept_client.h:148

Typedef Documentation

◆ RdmnetEptClientClientListUpdateReceivedCallback

typedef void(* RdmnetEptClientClientListUpdateReceivedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, client_list_action_t list_action, const RdmnetEptClientList *client_list, void *context)

A client list update has been received from a broker.

Parameters

[in]	client_handle	Handle to the EPT client which has received the client list update.
[in]	scope_handle	Handle to the scope on which the client list update was received.
[in]	list_action	The way the updates in client_list should be applied to the EPT client's cached list.
[in]	client_list	The list of updates.
[in]	context	Context pointer that was given at the creation of the client instance.

◆ RdmnetEptClientConnectedCallback

typedef void(* RdmnetEptClientConnectedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectedInfo *info, void *context)

An EPT client has successfully connected to a broker.

Parameters

[in]	client_handle	Handle to the EPT client which has connected.
[in]	scope_handle	Handle to the scope on which the EPT client has connected.
[in]	info	More information about the successful connection.
[in]	context	Context pointer that was given at the creation of the client instance.

◆ RdmnetEptClientConnectFailedCallback

typedef void(* RdmnetEptClientConnectFailedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientConnectFailedInfo *info, void *context)

A connection attempt failed between an EPT client and a broker.

Parameters

[in]	client_handle	Handle to the EPT client which has failed to connect.
[in]	scope_handle	Handle to the scope on which the connection failed.
[in]	info	More information about the failed connection.
[in]	context	Context pointer that was given at the creation of the client instance.

◆ RdmnetEptClientDataReceivedCallback

typedef void(* RdmnetEptClientDataReceivedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetEptData *data, RdmnetSyncEptResponse *response, void *context)

EPT data has been received addressed to an EPT client.

Parameters

[in]	client_handle	Handle to the EPT client which has received the data.
[in]	scope_handle	Handle to the scope on which the EPT data was received.
[in]	data	The EPT data.
[out]	response	Fill in with response data if responding synchronously.
[in]	context	Context pointer that was given at the creation of the client instance.

◆ RdmnetEptClientDisconnectedCallback

typedef void(* RdmnetEptClientDisconnectedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetClientDisconnectedInfo *info, void *context)

An EPT client which was previously connected to a broker has disconnected.

Parameters

[in]	client_handle	Handle to the EPT client which has disconnected.
[in]	scope_handle	Handle to the scope on which the disconnect occurred.
[in]	info	More information about the disconnect event.
[in]	context	Context pointer that was given at the creation of the client instance.

◆ RdmnetEptClientStatusReceivedCallback

typedef void(* RdmnetEptClientStatusReceivedCallback) (rdmnet_ept_client_t client_handle, rdmnet_client_scope_t scope_handle, const RdmnetEptStatus *status, void *context)

An EPT status message has been received in response to a previously-sent EPT data message.

Parameters

[in]	client_handle	Handle to the EPT client which has received the EPT status message.
[in]	scope_handle	Handle to the scope on which the EPT status message was received.
[in]	status	The EPT status data.
[in]	context	Context pointer that was given at the creation of the client instance.

Function Documentation

◆ rdmnet_ept_client_add_default_scope()

etcpal_error_t rdmnet_ept_client_add_default_scope	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t *	scope_handle
	)

Add a new scope representing the default RDMnet scope to an EPT client instance.

This is a shortcut to easily add the default RDMnet scope to an EPT client. The default behavior is to not use a statically-configured broker. If a static broker is needed on the default scope, rdmnet_ept_client_add_scope() must be used.

Parameters

[in]	client_handle	Handle to EPT client to which to add the default scope.
[out]	scope_handle	Filled in on success with a handle to the new scope.

Returns: kEtcPalErrOk: Default scope added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance.; kEtcPalErrNoMem: No memory to allocate new scope.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_add_scope()

etcpal_error_t rdmnet_ept_client_add_scope	(	rdmnet_ept_client_t	client_handle,
		const RdmnetScopeConfig *	scope_config,
		rdmnet_client_scope_t *	scope_handle
	)

Add a new scope to an EPT client instance.

The library will attempt to discover and connect to a broker for the scope (or just connect if a static broker address is given); the status of these attempts will be communicated via the callbacks associated with the EPT client instance.

Parameters

[in]	client_handle	Handle to EPT client to which to add a new scope.
[in]	scope_config	Configuration parameters for the new scope.
[out]	scope_handle	Filled in on success with a handle to the new scope.

Returns: kEtcPalErrOk: New scope added successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance.; kEtcPalErrNoMem: No memory to allocate new scope.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_change_scope()

etcpal_error_t rdmnet_ept_client_change_scope	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t	scope_handle,
		const RdmnetScopeConfig *	new_scope_config,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Change the configuration of a scope on an EPT client.

Will disconnect from any connected brokers and attempt connection again using the new configuration given.

Parameters

[in]	client_handle	Handle to the EPT client on which to change a scope.
[in]	scope_handle	Handle to the scope for which to change the configuration.
[in]	new_scope_config	New configuration parameters for the scope.
[in]	disconnect_reason	RDMnet protocol disconnect reason to send to the connected broker.

Returns: kEtcPalErrOk: Scope changed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_config_init()

void rdmnet_ept_client_config_init ( RdmnetEptClientConfig * config )

Initialize an RdmnetEptClientConfig 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:

RdmnetEptClientConfig config;

rdmnet_ept_client_config_init(&config);

rdmnet_ept_client_config_init

void rdmnet_ept_client_config_init(RdmnetEptClientConfig *config)

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

Definition: ept_client.c:39

Parameters

[out] config Pointer to RdmnetEptClientConfig to init.

◆ rdmnet_ept_client_create()

etcpal_error_t rdmnet_ept_client_create	(	const RdmnetEptClientConfig *	config,
		rdmnet_ept_client_t *	handle
	)

Create a new instance of RDMnet EPT client functionality.

Each EPT client is identified by a single component ID (CID). RDMnet connection will not be attempted until at least one scope is added using rdmnet_ept_client_add_scope().

Parameters

[in]	config	Configuration parameters to use for this EPT client instance.
[out]	handle	Filled in on success with a handle to the new EPT client instance.

Returns: kEtcPalErrOk: EPT client created successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNoMem: No memory to allocate new EPT client instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_destroy()

etcpal_error_t rdmnet_ept_client_destroy	(	rdmnet_ept_client_t	client_handle,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Destroy an EPT client instance.

Will disconnect from all brokers to which this EPT client is currently connected, sending the disconnect reason provided in the disconnect_reason parameter.

Parameters

[in]	client_handle	Handle to EPT client to destroy, no longer valid after this function returns.
[in]	disconnect_reason	Disconnect reason code to send on all connected scopes.

Returns: kEtcPalErrOk: EPT client destroyed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_get_scope()

etcpal_error_t rdmnet_ept_client_get_scope	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t	scope_handle,
		char *	scope_str_buf,
		EtcPalSockAddr *	static_broker_addr
	)

Retrieve the scope string of a previously-added scope.

Parameters

[in]	client_handle	Handle to the EPT client from which to retrieve the scope string.
[in]	scope_handle	Handle to the scope for which to retrieve the scope string.
[out]	scope_str_buf	Filled in on success with the scope string. Must be at least of length E133_SCOPE_STRING_PADDED_LENGTH.
[out]	static_broker_addr	(optional) Filled in on success with the static broker address, if present. Leave NULL if you don't care about the static broker address.

Returns: kEtcPalErrOk: Scope information retrieved successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_remove_scope()

etcpal_error_t rdmnet_ept_client_remove_scope	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t	scope_handle,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

Remove a previously-added scope from an EPT client instance.

After this call completes, scope_handle will no longer be valid.

Parameters

[in]	client_handle	Handle to the EPT client from which to remove a scope.
[in]	scope_handle	Handle to scope to remove.
[in]	disconnect_reason	RDMnet protocol disconnect reason to send to the connected broker.

Returns: kEtcPalErrOk: Scope removed successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_request_client_list()

etcpal_error_t rdmnet_ept_client_request_client_list	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t	scope_handle
	)

Request a client list from a broker.

The response will be delivered via the RdmnetEptClientClientListUpdateReceivedCallback.

Parameters

[in]	client_handle	Handle to the EPT client from which to request the client list.
[in]	scope_handle	Handle to the scope on which to request the client list.

Returns: kEtcPalErrOk: Request sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_send_data()

etcpal_error_t rdmnet_ept_client_send_data	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t	scope_handle,
		const EtcPalUuid *	dest_cid,
		uint16_t	manufacturer_id,
		uint16_t	protocol_id,
		const uint8_t *	data,
		size_t	data_len
	)

Send data from an EPT client on a scope.

Parameters

[in]	client_handle	Handle to the EPT client from which to send data.
[in]	scope_handle	Handle to the scope on which to send data.
[in]	dest_cid	CID of the EPT client to which to send the data.
[in]	manufacturer_id	Manufacturer ID portion of the EPT sub-protocol identifier.
[in]	protocol_id	Manufacturer ID portion of the EPT sub-protocol identifier.
[in]	data	The data to send.
[in]	data_len	Size in bytes of data.

Returns: kEtcPalErrOk: Data sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_send_status()

etcpal_error_t rdmnet_ept_client_send_status	(	rdmnet_ept_client_t	client_handle,
		rdmnet_client_scope_t	scope_handle,
		const EtcPalUuid *	dest_cid,
		ept_status_code_t	status_code,
		const char *	status_string
	)

Send a status message from an EPT client on a scope.

Parameters

[in]	client_handle	Handle to the EPT client from which to send the status message.
[in]	scope_handle	Handle to the scope on which to send the status message.
[in]	dest_cid	CID of the EPT client to which to send the status message.
[in]	status_code	EPT status code to send.
[in]	status_string	Optional status string accompanying the code.

Returns: kEtcPalErrOk: Status sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: client_handle is not associated with a valid EPT client instance, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ rdmnet_ept_client_set_callbacks()

void rdmnet_ept_client_set_callbacks	(	RdmnetEptClientConfig *	config,
		RdmnetEptClientConnectedCallback	connected,
		RdmnetEptClientConnectFailedCallback	connect_failed,
		RdmnetEptClientDisconnectedCallback	disconnected,
		RdmnetEptClientClientListUpdateReceivedCallback	client_list_update_received,
		RdmnetEptClientDataReceivedCallback	data_received,
		RdmnetEptClientStatusReceivedCallback	status_received,
		void *	context
	)

Set the callbacks in an RDMnet EPT client configuration structure.

Parameters

[out]	config	Config struct in which to set the callbacks.
[in]	connected	Callback called when the EPT client has connected to a broker.
[in]	connect_failed	Callback called when a connection to a broker has failed.
[in]	disconnected	Callback called when a connection to a broker has disconnected.
[in]	client_list_update_received	Callback called when an EPT client receives an updated RDMnet client list.
[in]	data_received	Callback called when an EPT client receives an EPT data message.
[in]	status_received	Callback called when an EPT client receives an EPT status message in response to an EPT data message.
[in]	context	(optional) Pointer to opaque data passed back with each callback.

Overview

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RDMNET_EPT_CLIENT_CONFIG_DEFAULT_INIT

Typedef Documentation

◆ RdmnetEptClientClientListUpdateReceivedCallback

◆ RdmnetEptClientConnectedCallback

◆ RdmnetEptClientConnectFailedCallback

◆ RdmnetEptClientDataReceivedCallback

◆ RdmnetEptClientDisconnectedCallback

◆ RdmnetEptClientStatusReceivedCallback

Function Documentation

◆ rdmnet_ept_client_add_default_scope()

◆ rdmnet_ept_client_add_scope()

◆ rdmnet_ept_client_change_scope()

◆ rdmnet_ept_client_config_init()

◆ rdmnet_ept_client_create()

◆ rdmnet_ept_client_destroy()

◆ rdmnet_ept_client_get_scope()

◆ rdmnet_ept_client_remove_scope()

◆ rdmnet_ept_client_request_client_list()

◆ rdmnet_ept_client_send_data()

◆ rdmnet_ept_client_send_status()

◆ rdmnet_ept_client_set_callbacks()