Overview

An instance of RDMnet EPT client functionality.

See Using the EPT Client API for details of how to use this API.

#include <rdmnet/cpp/ept_client.h>

Data Structures
class	NotifyHandler
	A base class for a class that receives notification callbacks from an EPT client. More...

struct	Settings
	A set of configuration settings that an EPT client needs to initialize. More...

Public Types
using	Handle = rdmnet_ept_client_t
	A handle type used by the RDMnet library to identify EPT client instances.

Public Member Functions
	EptClient (const EptClient &other)=delete

EptClient &	operator= (const EptClient &other)=delete

	EptClient (EptClient &&other)=default
	Move an EPT client instance.

EptClient &	operator= (EptClient &&other)=default
	Move an EPT client instance.

etcpal::Error	Startup (NotifyHandler &notify_handler, const Settings &settings)
	Allocate resources and start up this EPT client with the given configuration. More...

void	Shutdown (rdmnet_disconnect_reason_t disconnect_reason=kRdmnetDisconnectShutdown)
	Shut down this EPT client and deallocate resources. More...

etcpal::Expected< ScopeHandle >	AddScope (const char *id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
	Add a new scope to this EPT client instance. More...

etcpal::Expected< ScopeHandle >	AddScope (const Scope &scope_config)
	Add a new scope to this EPT client instance. More...

etcpal::Expected< ScopeHandle >	AddDefaultScope (const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
	Shortcut to add the default RDMnet scope to an EPT client instance. More...

etcpal::Error	RemoveScope (ScopeHandle scope_handle, rdmnet_disconnect_reason_t disconnect_reason)
	Remove a previously-added scope from this EPT client instance. More...

etcpal::Error	RequestClientList (ScopeHandle scope_handle)
	Request a client list from a broker. More...

etcpal::Error	SendData (ScopeHandle scope_handle, const etcpal::Uuid &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	SendStatus (ScopeHandle scope_handle, const etcpal::Uuid &dest_cid, ept_status_code_t status_code, const char *status_string=nullptr)
	Send a status message from an EPT client on a scope. More...

Handle	handle () const
	Retrieve the handle of an EPT client instance.

NotifyHandler *	notify_handler () const
	Retrieve the NotifyHandler reference that this EPT client was configured with.

etcpal::Expected< Scope >	scope (ScopeHandle scope_handle) const
	Retrieve the scope configuration associated with a given scope handle. More...

Static Public Attributes
static constexpr Handle	kInvalidHandle = RDMNET_EPT_CLIENT_INVALID
	An invalid Handle value.

Member Function Documentation

◆ AddDefaultScope()

etcpal::Expected< ScopeHandle > rdmnet::EptClient::AddDefaultScope ( const etcpal::SockAddr & static_broker_addr = etcpal::SockAddr{} )

inline

Shortcut to add the default RDMnet scope to an EPT client instance.

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

Parameters

static_broker_addr [optional] A static broker address to configure for the default scope.

Returns: On success, a handle to the new scope, to be used with subsequent API calls.; On failure, error codes from rdmnet_ept_client_add_scope().

◆ AddScope() [1/2]

etcpal::Expected< ScopeHandle > rdmnet::EptClient::AddScope	(	const char *	id,
		const etcpal::SockAddr &	static_broker_addr = `etcpal::SockAddr{}`
	)

inline

Add a new scope to this 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 associated NotifyHandler.

Parameters

id	The scope ID string.
static_broker_addr	[optional] A static IP address and port at which to connect to the broker for this scope.

Returns: On success, a handle to the new scope, to be used with subsequent API calls.; On failure, error codes from rdmnet_ept_client_add_scope().

◆ AddScope() [2/2]

etcpal::Expected< ScopeHandle > rdmnet::EptClient::AddScope ( const Scope & scope_config )

inline

Add a new scope to this 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 associated NotifyHandler.

Parameters

scope_config Configuration information for the new scope.

Returns: On success, a handle to the new scope, to be used with subsequent API calls.; On failure, error codes from rdmnet_ept_client_add_scope().

◆ RemoveScope()

etcpal::Error rdmnet::EptClient::RemoveScope	(	ScopeHandle	scope_handle,
		rdmnet_disconnect_reason_t	disconnect_reason
	)

inline

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

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

Parameters

scope_handle	Handle to the scope to remove.
disconnect_reason	RDMnet protocol disconnect reason to send to the connected broker.

Returns: etcpal::Error::Ok(): Scope removed successfully.; Error codes from from rdmnet_ept_client_remove_scope().

◆ RequestClientList()

etcpal::Error rdmnet::EptClient::RequestClientList ( ScopeHandle scope_handle )

inline

Request a client list from a broker.

The response will be delivered via the NotifyHandler::HandleClientListUpdate() callback.

Parameters

scope_handle Handle to the scope on which to request the client list.

Returns: etcpal::Error::Ok(): Request sent successfully.; Error codes from rdmnet_ept_client_request_client_list().

◆ scope()

etcpal::Expected< Scope > rdmnet::EptClient::scope ( ScopeHandle scope_handle ) const

inline

Retrieve the scope configuration associated with a given scope handle.

Returns: The scope configuration on success.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: EPT client not started, or scope handle not found.

◆ SendData()

etcpal::Error rdmnet::EptClient::SendData	(	ScopeHandle	scope_handle,
		const etcpal::Uuid &	dest_cid,
		uint16_t	manufacturer_id,
		uint16_t	protocol_id,
		const uint8_t *	data,
		size_t	data_len
	)

inline

Send data from an EPT client on a scope.

Parameters

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

Returns: etcpal::Error::Ok(): Data sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Client not started, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ SendStatus()

etcpal::Error rdmnet::EptClient::SendStatus	(	ScopeHandle	scope_handle,
		const etcpal::Uuid &	dest_cid,
		ept_status_code_t	status_code,
		const char *	status_string = `nullptr`
	)

inline

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

Parameters

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

Returns: etcpal::Error::Ok(): Status sent successfully.; kEtcPalErrInvalid: Invalid argument.; kEtcPalErrNotInit: Module not initialized.; kEtcPalErrNotFound: Client not started, or scope_handle is not associated with a valid scope instance.; kEtcPalErrSys: An internal library or system call error occurred.

◆ Shutdown()

void rdmnet::EptClient::Shutdown ( rdmnet_disconnect_reason_t disconnect_reason = kRdmnetDisconnectShutdown )

inline

Shut down this EPT client and deallocate resources.

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

Parameters

disconnect_reason Reason code for disconnecting from each scope.

◆ Startup()

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

inline

Allocate resources and start up this EPT client with the given configuration.

Parameters

notify_handler	A class instance to handle callback notifications from this EPT client.
settings	Configuration settings used by this EPT client.

Returns: etcpal::Error::Ok(): EPT client started successfully.; kEtcPalErrInvalid: Invalid argument.; Errors forwarded from rdmnet_ept_client_create().

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

include/rdmnet/cpp/ept_client.h

Overview

Data Structures

Public Types

Public Member Functions

Static Public Attributes

Member Function Documentation

◆ AddDefaultScope()

◆ AddScope() [1/2]

◆ AddScope() [2/2]

◆ RemoveScope()

◆ RequestClientList()

◆ scope()

◆ SendData()

◆ SendStatus()

◆ Shutdown()

◆ Startup()