RDMnet  0.3.0
Implementation of ANSI E1.33 (RDMnet)
View other versions:
rdmnet::Controller Class Reference

Overview

An instance of RDMnet controller functionality.

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

#include <rdmnet/cpp/controller.h>

Data Structures

class  NotifyHandler
 A base class for a class that receives notification callbacks from a controller. More...
 
class  RdmCommandHandler
 A base class for a class that receives RDM commands addressed to a controller. More...
 
struct  RdmData
 A set of initial identifying RDM data to use for a controller. More...
 
struct  Settings
 A set of configuration settings that a controller needs to initialize. More...
 

Public Types

using Handle = rdmnet_controller_t
 A handle type used by the RDMnet library to identify controller instances.
 

Public Member Functions

 Controller (const Controller &other)=delete
 
Controlleroperator= (const Controller &other)=delete
 
 Controller (Controller &&other)=default
 Move a controller instance.
 
Controlleroperator= (Controller &&other)=default
 Move a controller instance.
 
etcpal::Error Startup (NotifyHandler &notify_handler, const Settings &settings, const RdmData &rdm_data)
 Allocate resources and start up this controller with the given configuration. More...
 
etcpal::Error Startup (NotifyHandler &notify_handler, const Settings &settings, RdmCommandHandler &rdm_handler, uint8_t *rdm_response_buf=nullptr)
 Allocate resources and start up this controller with the given configuration. More...
 
void Shutdown (rdmnet_disconnect_reason_t disconnect_reason=kRdmnetDisconnectShutdown)
 Shut down this controller and deallocate resources. More...
 
etcpal::Expected< ScopeHandleAddScope (const char *id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
 Add a new scope to this controller instance. More...
 
etcpal::Expected< ScopeHandleAddScope (const std::string &id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
 Add a new scope to this controller instance. More...
 
etcpal::Expected< ScopeHandleAddScope (const Scope &scope_config)
 Add a new scope to this controller instance. More...
 
etcpal::Expected< ScopeHandleAddDefaultScope (const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{})
 Shortcut to add the default RDMnet scope to a controller instance. More...
 
etcpal::Error RemoveScope (ScopeHandle scope_handle, rdmnet_disconnect_reason_t disconnect_reason)
 Remove a previously-added scope from this controller instance. More...
 
etcpal::Error ChangeScope (ScopeHandle scope_handle, const char *new_scope_id_str, rdmnet_disconnect_reason_t disconnect_reason, const etcpal::SockAddr &new_static_broker_addr=etcpal::SockAddr{})
 Change the configuration of a scope on a controller. More...
 
etcpal::Error ChangeScope (ScopeHandle scope_handle, const Scope &new_scope_config, rdmnet_disconnect_reason_t disconnect_reason)
 Change the configuration of a scope on a controller. More...
 
etcpal::Error ChangeSearchDomain (const char *new_search_domain, rdmnet_disconnect_reason_t disconnect_reason)
 Change the controller's DNS search domain. More...
 
etcpal::Expected< uint32_t > SendRdmCommand (ScopeHandle scope_handle, const DestinationAddr &destination, rdmnet_command_class_t command_class, uint16_t param_id, const uint8_t *data=nullptr, uint8_t data_len=0)
 Send an RDM command from a controller on a scope. More...
 
etcpal::Expected< uint32_t > SendGetCommand (ScopeHandle scope_handle, const DestinationAddr &destination, uint16_t param_id, const uint8_t *data=nullptr, uint8_t data_len=0)
 Send an RDM GET command from a controller on a scope. More...
 
etcpal::Expected< uint32_t > SendSetCommand (ScopeHandle scope_handle, const DestinationAddr &destination, uint16_t param_id, const uint8_t *data=nullptr, uint8_t data_len=0)
 Send an RDM SET command from a controller on a scope. More...
 
etcpal::Error RequestClientList (ScopeHandle scope_handle)
 Request a client list from a broker. More...
 
etcpal::Error RequestResponderIds (ScopeHandle scope_handle, const rdm::Uid *uids, size_t num_uids)
 Request mappings from dynamic UIDs to Responder IDs (RIDs). More...
 
etcpal::Error RequestResponderIds (ScopeHandle scope_handle, const std::vector< rdm::Uid > &uids)
 Request mappings from dynamic UIDs to Responder IDs (RIDs). More...
 
etcpal::Error SendRdmAck (ScopeHandle scope_handle, const SavedRdmCommand &received_cmd, const uint8_t *response_data=nullptr, size_t response_data_len=0)
 Send an acknowledge (ACK) response to an RDM command received by a controller. More...
 
etcpal::Error SendRdmNack (ScopeHandle scope_handle, const SavedRdmCommand &received_cmd, rdm_nack_reason_t nack_reason)
 Send a negative acknowledge (NACK) response to an RDM command received by a controller. More...
 
etcpal::Error SendRdmNack (ScopeHandle scope_handle, const SavedRdmCommand &received_cmd, uint16_t raw_nack_reason)
 Send a negative acknowledge (NACK) response to an RDM command received by a controller. More...
 
etcpal::Error SendRdmUpdate (ScopeHandle scope_handle, uint16_t param_id, const uint8_t *data=nullptr, size_t data_len=0)
 Send an asynchronous RDM GET response to update the value of a local parameter. More...
 
etcpal::Error SendLlrpAck (const llrp::SavedRdmCommand &received_cmd, const uint8_t *response_data=nullptr, uint8_t response_data_len=0)
 Send an acknowledge (ACK) response to an LLRP RDM command received by a controller. More...
 
etcpal::Error SendLlrpNack (const llrp::SavedRdmCommand &received_cmd, rdm_nack_reason_t nack_reason)
 Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller. More...
 
etcpal::Error SendLlrpNack (const llrp::SavedRdmCommand &received_cmd, uint16_t raw_nack_reason)
 Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller. More...
 
Handle handle () const
 Retrieve the handle of a controller instance.
 
const RdmDatardm_data () const
 Retrieve the RDM data that this controller was configured with on startup. More...
 
Controller::NotifyHandlernotify_handler () const
 Retrieve the Controller::NotifyHandler reference that this controller was configured with.
 
Controller::RdmCommandHandlerrdm_command_handler () const
 Retrieve the Controller::RdmCommandHandler reference that this controller was configured with. More...
 
etcpal::Expected< Scopescope (ScopeHandle scope_handle) const
 Retrieve the scope configuration associated with a given scope handle. More...
 
void UpdateRdmData (const RdmData &new_data)
 Update the data used to identify this controller to other controllers.
 

Static Public Attributes

static constexpr Handle kInvalidHandle = RDMNET_CONTROLLER_INVALID
 An invalid Handle value.
 

Member Function Documentation

◆ AddDefaultScope()

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

Shortcut to add the default RDMnet scope to a controller 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 Controller::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_controller_add_scope().

◆ AddScope() [1/3]

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

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

Parameters
idThe 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_controller_add_scope().

◆ AddScope() [2/3]

etcpal::Expected< ScopeHandle > rdmnet::Controller::AddScope ( const Scope scope_config)
inline

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

Parameters
scope_configConfiguration 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_controller_add_scope().

◆ AddScope() [3/3]

etcpal::Expected< ScopeHandle > rdmnet::Controller::AddScope ( const std::string id,
const etcpal::SockAddr static_broker_addr = etcpal::SockAddr{} 
)
inline

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

Parameters
idThe 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_controller_add_scope().

◆ ChangeScope() [1/2]

etcpal::Error rdmnet::Controller::ChangeScope ( ScopeHandle  scope_handle,
const char *  new_scope_id_str,
rdmnet_disconnect_reason_t  disconnect_reason,
const etcpal::SockAddr new_static_broker_addr = etcpal::SockAddr{} 
)
inline

Change the configuration of a scope on a controller.

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

Parameters
scope_handleHandle to the scope for which to change the configuration.
new_scope_id_strID string to use for the new scope.
disconnect_reasonRDMnet protocol disconnect reason to send to the connected broker.
new_static_broker_addr[optional] New static IP address and port at which to connect to the broker for this scope.
Returns
etcpal::Error::Ok(): Scope changed successfully.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrNotInit: Module not initialized.
kEtcPalErrNotFound: scope_handle is not associated with a valid scope instance.
kEtcPalErrSys: An internal library or system call error occurred.

◆ ChangeScope() [2/2]

etcpal::Error rdmnet::Controller::ChangeScope ( ScopeHandle  scope_handle,
const Scope new_scope_config,
rdmnet_disconnect_reason_t  disconnect_reason 
)
inline

Change the configuration of a scope on a controller.

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

Parameters
scope_handleHandle to the scope for which to change the configuration.
new_scope_configNew configuration parameters for the scope.
disconnect_reasonRDMnet protocol disconnect reason to send to the connected broker.
Returns
etcpal::Error::Ok(): Scope changed successfully.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrNotInit: Module not initialized.
kEtcPalErrNotFound: scope_handle is not associated with a valid scope instance.
kEtcPalErrSys: An internal library or system call error occurred.

◆ ChangeSearchDomain()

etcpal::Error rdmnet::Controller::ChangeSearchDomain ( const char *  new_search_domain,
rdmnet_disconnect_reason_t  disconnect_reason 
)
inline

Change the controller's DNS search domain.

Non-default search domains are considered advanced usage. Any added scopes which do not have a static broker configuration will be disconnected, sending the disconnect reason provided in the disconnect_reason parameter. Then discovery will be re-attempted on the new search domain.

Parameters
new_search_domainNew search domain to use for discovery.
disconnect_reasonDisconnect reason to send to any connected brokers.
Returns
etcpal::Error::Ok(): Search domain changed successfully.
kEtcPalErrInvalid: Invalid argument.
kEtcPalErrNotInit: Module not initialized.
kEtcPalErrSys: An internal library or system call error occurred.

◆ rdm_command_handler()

Controller::RdmCommandHandler * rdmnet::Controller::rdm_command_handler ( ) const
inline

Retrieve the Controller::RdmCommandHandler reference that this controller was configured with.

Returns
A pointer to the handler, or nullptr if it was not provided.

◆ rdm_data()

const Controller::RdmData & rdmnet::Controller::rdm_data ( ) const
inline

Retrieve the RDM data that this controller was configured with on startup.

Returns
The data, or an invalid RdmData instance if it was not provided.

◆ RemoveScope()

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

Remove a previously-added scope from this controller instance.

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

Parameters
scope_handleHandle to scope to remove.
disconnect_reasonRDMnet protocol disconnect reason to send to the connected broker.
Returns
etcpal::Error::Ok(): Scope removed successfully.
Error codes from from rdmnet_controller_remove_scope().

◆ RequestClientList()

etcpal::Error rdmnet::Controller::RequestClientList ( ScopeHandle  scope_handle)
inline

Request a client list from a broker.

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

Parameters
scope_handleHandle to the scope on which to request the client list.
Returns
etcpal::Error::Ok(): Request sent successfully.
Error codes from rdmnet_controller_request_client_list().

◆ RequestResponderIds() [1/2]

etcpal::Error rdmnet::Controller::RequestResponderIds ( ScopeHandle  scope_handle,
const rdm::Uid *  uids,
size_t  num_uids 
)
inline

Request mappings from dynamic UIDs to Responder IDs (RIDs).

See Devices and Gateways for more information. A RID is a UUID that permanently identifies a virtual RDMnet responder.

Parameters
scope_handleHandle to the scope on which to request the responder IDs.
uidsList of dynamic UIDs for which to request the corresponding responder ID.
num_uidsSize of the uids array.
Returns
etcpal::Error::Ok(): Request sent successfully.
Error codes from rdmnet_controller_request_responder_ids().

◆ RequestResponderIds() [2/2]

etcpal::Error rdmnet::Controller::RequestResponderIds ( ScopeHandle  scope_handle,
const std::vector< rdm::Uid > &  uids 
)
inline

Request mappings from dynamic UIDs to Responder IDs (RIDs).

See Devices and Gateways for more information. A RID is a UUID that permanently identifies a virtual RDMnet responder.

Parameters
scope_handleHandle to the scope on which to request the responder IDs.
uidsList of dynamic UIDs for which to request the corresponding responder ID.
Returns
etcpal::Error::Ok(): Request sent successfully.
Error codes from rdmnet_controller_request_responder_ids().

◆ scope()

etcpal::Expected< Scope > rdmnet::Controller::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: Controller not started, or scope handle not found.

◆ SendGetCommand()

etcpal::Expected< uint32_t > rdmnet::Controller::SendGetCommand ( ScopeHandle  scope_handle,
const DestinationAddr destination,
uint16_t  param_id,
const uint8_t *  data = nullptr,
uint8_t  data_len = 0 
)
inline

Send an RDM GET command from a controller on a scope.

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

Parameters
scope_handleHandle to the scope on which to send the RDM command.
destinationThe destination addressing information for the RDM command.
param_idThe command's RDM parameter ID.
data[optional] The command's RDM parameter data, if it has any.
data_len[optional] The length of the RDM parameter data (or 0 if data is nullptr).
Returns
On success, a sequence number which can be used to match the command with a response.
On failure, error codes from rdmnet_controller_send_get_command().

◆ SendLlrpAck()

etcpal::Error rdmnet::Controller::SendLlrpAck ( const llrp::SavedRdmCommand received_cmd,
const uint8_t *  response_data = nullptr,
uint8_t  response_data_len = 0 
)
inline

Send an acknowledge (ACK) response to an LLRP RDM command received by a controller.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
received_cmdThe command to which this ACK is a response.
response_data[optional] The response's RDM parameter data, if it has any.
response_data_len[optional] The length of the RDM parameter data (or 0 if data is nullptr).
Returns
etcpal::Error::Ok(): LLRP ACK sent successfully.
Error codes from rdmnet_controller_send_llrp_ack().

◆ SendLlrpNack() [1/2]

etcpal::Error rdmnet::Controller::SendLlrpNack ( const llrp::SavedRdmCommand received_cmd,
rdm_nack_reason_t  nack_reason 
)
inline

Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
received_cmdThe command to which this NACK is a response.
nack_reasonThe RDM NACK reason to send with the NACK response.
Returns
etcpal::Error::Ok(): NACK sent successfully.
Error codes from rdmnet_controller_send_llrp_nack().

◆ SendLlrpNack() [2/2]

etcpal::Error rdmnet::Controller::SendLlrpNack ( const llrp::SavedRdmCommand received_cmd,
uint16_t  raw_nack_reason 
)
inline

Send a negative acknowledge (NACK) response to an LLRP RDM command received by a controller.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
received_cmdThe command to which this NACK is a response.
raw_nack_reasonThe NACK reason (either standard or manufacturer-specific) to send with the NACK response.
Returns
etcpal::Error::Ok(): NACK sent successfully.
Error codes from rdmnet_controller_send_llrp_nack().

◆ SendRdmAck()

etcpal::Error rdmnet::Controller::SendRdmAck ( ScopeHandle  scope_handle,
const SavedRdmCommand received_cmd,
const uint8_t *  response_data = nullptr,
size_t  response_data_len = 0 
)
inline

Send an acknowledge (ACK) response to an RDM command received by a controller.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
scope_handleHandle to the scope on which the corresponding command was received.
received_cmdThe command to which this ACK is a response.
response_data[optional] The response's RDM parameter data, if it has any.
response_data_len[optional] The length of the RDM parameter data (or 0 if data is nullptr).
Returns
etcpal::Error::Ok(): ACK sent successfully.
Error codes from rdmnet_controller_send_rdm_ack().

◆ SendRdmCommand()

etcpal::Expected< uint32_t > rdmnet::Controller::SendRdmCommand ( ScopeHandle  scope_handle,
const DestinationAddr destination,
rdmnet_command_class_t  command_class,
uint16_t  param_id,
const uint8_t *  data = nullptr,
uint8_t  data_len = 0 
)
inline

Send an RDM command from a controller on a scope.

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

Parameters
scope_handleHandle to the scope on which to send the RDM command.
destinationThe destination addressing information for the RDM command.
command_classThe command's RDM command class (GET or SET).
param_idThe command's RDM parameter ID.
data[optional] The command's RDM parameter data, if it has any.
data_len[optional] The length of the RDM parameter data (or 0 if data is nullptr).
Returns
On success, a sequence number which can be used to match the command with a response.
On failure, error codes from rdmnet_controller_send_rdm_command().

◆ SendRdmNack() [1/2]

etcpal::Error rdmnet::Controller::SendRdmNack ( ScopeHandle  scope_handle,
const SavedRdmCommand received_cmd,
rdm_nack_reason_t  nack_reason 
)
inline

Send a negative acknowledge (NACK) response to an RDM command received by a controller.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
scope_handleHandle to the scope on which the corresponding command was received.
received_cmdThe command to which this NACK is a response.
nack_reasonThe RDM NACK reason to send with the NACK response.
Returns
etcpal::Error::Ok(): NACK sent successfully.
Error codes from rdmnet_controller_send_rdm_nack().

◆ SendRdmNack() [2/2]

etcpal::Error rdmnet::Controller::SendRdmNack ( ScopeHandle  scope_handle,
const SavedRdmCommand received_cmd,
uint16_t  raw_nack_reason 
)
inline

Send a negative acknowledge (NACK) response to an RDM command received by a controller.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
scope_handleHandle to the scope on which the corresponding command was received.
received_cmdThe command to which this NACK is a response.
raw_nack_reasonThe NACK reason (either standard or manufacturer-specific) to send with the NACK response.
Returns
etcpal::Error::Ok(): NACK sent successfully.
Error codes from rdmnet_controller_send_rdm_nack().

◆ SendRdmUpdate()

etcpal::Error rdmnet::Controller::SendRdmUpdate ( ScopeHandle  scope_handle,
uint16_t  param_id,
const uint8_t *  data = nullptr,
size_t  data_len = 0 
)
inline

Send an asynchronous RDM GET response to update the value of a local parameter.

This function should only be used if a Controller::RdmCommandHandler was supplied when starting this controller.

Parameters
scope_handleHandle to the scope on which to send the RDM update.
param_idThe RDM parameter ID that has been updated.
dataThe updated parameter data, if any.
data_lenThe length of the parameter data, if any.
Returns
etcpal::Error::Ok(): RDM update sent successfully.
Error codes from rdmnet_controller_send_rdm_update().

◆ SendSetCommand()

etcpal::Expected< uint32_t > rdmnet::Controller::SendSetCommand ( ScopeHandle  scope_handle,
const DestinationAddr destination,
uint16_t  param_id,
const uint8_t *  data = nullptr,
uint8_t  data_len = 0 
)
inline

Send an RDM SET command from a controller on a scope.

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

Parameters
scope_handleHandle to the scope on which to send the RDM command.
destinationThe destination addressing information for the RDM command.
param_idThe command's RDM parameter ID.
data[optional] The command's RDM parameter data, if it has any.
data_len[optional] The length of the RDM parameter data (or 0 if data is nullptr).
Returns
On success, a sequence number which can be used to match the command with a response.
On failure, error codes from rdmnet_controller_send_set_command().

◆ Shutdown()

void rdmnet::Controller::Shutdown ( rdmnet_disconnect_reason_t  disconnect_reason = kRdmnetDisconnectShutdown)
inline

Shut down this controller and deallocate resources.

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

Parameters
disconnect_reasonReason code for disconnecting from each scope.

◆ Startup() [1/2]

etcpal::Error rdmnet::Controller::Startup ( NotifyHandler notify_handler,
const Settings settings,
const RdmData rdm_data 
)
inline

Allocate resources and start up this controller with the given configuration.

This overload provides a set of RDM data to the library to use for the controller's RDM responder. RDM commands addressed to the controller will be handled internally by the library.

Parameters
notify_handlerA class instance to handle callback notifications from this controller.
settingsConfiguration settings used by this controller.
rdm_dataData to identify this controller to other controllers on the network.
Returns
etcpal::Error::Ok(): Controller started successfully.
kEtcPalErrInvalid: Invalid argument.
Errors forwarded from rdmnet_controller_create().

◆ Startup() [2/2]

etcpal::Error rdmnet::Controller::Startup ( NotifyHandler notify_handler,
const Settings settings,
RdmCommandHandler rdm_handler,
uint8_t *  rdm_response_buf = nullptr 
)
inline

Allocate resources and start up this controller with the given configuration.

This overload provides a notification handler to respond to RDM commands addressed to the controller. You must implement a core set of RDM commands - see Using the Controller API for more information.

Parameters
notify_handlerA class instance to handle callback notifications from this controller.
settingsConfiguration settings used by this controller.
rdm_handlerA class instance to handle RDM commands addressed to this controller.
rdm_response_buf(optional) A data buffer used to respond synchronously to RDM commands. See Handling RDM Commands for more information.
Returns
etcpal::Error::Ok(): Controller started successfully.
kEtcPalErrInvalid: Invalid argument.
Errors forwarded from rdmnet_controller_create().

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