| 
    RDMnet
    0.3.0
    
   Implementation of ANSI E1.33 (RDMnet) 
   | 
  
  
     
      View other versions:
      
     
   | 
  
 
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 | |
| Controller & | operator= (const Controller &other)=delete | 
| Controller (Controller &&other)=default | |
| Move a controller instance.  | |
| Controller & | operator= (Controller &&other)=default | 
| Move a controller instance.  | |
| etcpal::Error | Startup (NotifyHandler ¬ify_handler, const Settings &settings, const RdmData &rdm_data) | 
| Allocate resources and start up this controller with the given configuration.  More... | |
| etcpal::Error | Startup (NotifyHandler ¬ify_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< ScopeHandle > | AddScope (const char *id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{}) | 
| Add a new scope to this controller instance.  More... | |
| etcpal::Expected< ScopeHandle > | AddScope (const std::string &id, const etcpal::SockAddr &static_broker_addr=etcpal::SockAddr{}) | 
| Add a new scope to this controller instance.  More... | |
| etcpal::Expected< ScopeHandle > | AddScope (const Scope &scope_config) | 
| Add a new scope to this controller instance.  More... | |
| etcpal::Expected< ScopeHandle > | AddDefaultScope (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 RdmData & | rdm_data () const | 
| Retrieve the RDM data that this controller was configured with on startup.  More... | |
| Controller::NotifyHandler * | notify_handler () const | 
| Retrieve the Controller::NotifyHandler reference that this controller was configured with.  | |
| Controller::RdmCommandHandler * | rdm_command_handler () const | 
| Retrieve the Controller::RdmCommandHandler reference that this controller was configured with.  More... | |
| etcpal::Expected< Scope > | scope (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.  | |
      
  | 
  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.
| static_broker_addr | [optional] A static broker address to configure for the default scope. | 
      
  | 
  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.
| 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. | 
      
  | 
  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.
| scope_config | Configuration information for the new scope. | 
      
  | 
  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.
| 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. | 
      
  | 
  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.
| scope_handle | Handle to the scope for which to change the configuration. | 
| new_scope_id_str | ID string to use for the new scope. | 
| disconnect_reason | RDMnet 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. | 
      
  | 
  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.
| scope_handle | Handle to the scope for which to change the configuration. | 
| new_scope_config | New configuration parameters for the scope. | 
| disconnect_reason | RDMnet protocol disconnect reason to send to the connected broker. | 
      
  | 
  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.
| new_search_domain | New search domain to use for discovery. | 
| disconnect_reason | Disconnect reason to send to any connected brokers. | 
      
  | 
  inline | 
Retrieve the Controller::RdmCommandHandler reference that this controller was configured with.
      
  | 
  inline | 
Retrieve the RDM data that this controller was configured with on startup.
      
  | 
  inline | 
Remove a previously-added scope from this controller instance.
After this call completes, scope_handle will no longer be valid.
| scope_handle | Handle to scope to remove. | 
| disconnect_reason | RDMnet protocol disconnect reason to send to the connected broker. | 
      
  | 
  inline | 
Request a client list from a broker.
The response will be delivered via the Controller::NotifyHandler::HandleClientListUpdate() callback.
| scope_handle | Handle to the scope on which to request the client list. | 
      
  | 
  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.
| scope_handle | Handle to the scope on which to request the responder IDs. | 
| uids | List of dynamic UIDs for which to request the corresponding responder ID. | 
| num_uids | Size of the uids array. | 
      
  | 
  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.
| scope_handle | Handle to the scope on which to request the responder IDs. | 
| uids | List of dynamic UIDs for which to request the corresponding responder ID. | 
      
  | 
  inline | 
Retrieve the scope configuration associated with a given scope handle.
      
  | 
  inline | 
Send an RDM GET command from a controller on a scope.
The response will be delivered via the Controller::NotifyHandler::HandleRdmResponse() callback.
| scope_handle | Handle to the scope on which to send the RDM command. | 
| destination | The destination addressing information for the RDM command. | 
| param_id | The 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). | 
      
  | 
  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.
| received_cmd | The 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). | 
      
  | 
  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.
| received_cmd | The command to which this NACK is a response. | 
| nack_reason | The RDM NACK reason to send with the NACK response. | 
      
  | 
  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.
| received_cmd | The command to which this NACK is a response. | 
| raw_nack_reason | The NACK reason (either standard or manufacturer-specific) to send with the NACK response. | 
      
  | 
  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.
| scope_handle | Handle to the scope on which the corresponding command was received. | 
| received_cmd | The 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). | 
      
  | 
  inline | 
Send an RDM command from a controller on a scope.
The response will be delivered via the Controller::NotifyHandler::HandleRdmResponse() callback.
| scope_handle | Handle to the scope on which to send the RDM command. | 
| destination | The destination addressing information for the RDM command. | 
| command_class | The command's RDM command class (GET or SET). | 
| param_id | The 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). | 
      
  | 
  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.
| scope_handle | Handle to the scope on which the corresponding command was received. | 
| received_cmd | The command to which this NACK is a response. | 
| nack_reason | The RDM NACK reason to send with the NACK response. | 
      
  | 
  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.
| scope_handle | Handle to the scope on which the corresponding command was received. | 
| received_cmd | The command to which this NACK is a response. | 
| raw_nack_reason | The NACK reason (either standard or manufacturer-specific) to send with the NACK response. | 
      
  | 
  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.
| scope_handle | Handle to the scope on which to send the RDM update. | 
| param_id | The RDM parameter ID that has been updated. | 
| data | The updated parameter data, if any. | 
| data_len | The length of the parameter data, if any. | 
      
  | 
  inline | 
Send an RDM SET command from a controller on a scope.
The response will be delivered via the Controller::NotifyHandler::HandleRdmResponse() callback.
| scope_handle | Handle to the scope on which to send the RDM command. | 
| destination | The destination addressing information for the RDM command. | 
| param_id | The 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). | 
      
  | 
  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.
| disconnect_reason | Reason code for disconnecting from each scope. | 
      
  | 
  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.
| notify_handler | A class instance to handle callback notifications from this controller. | 
| settings | Configuration settings used by this controller. | 
| rdm_data | Data to identify this controller to other controllers on the network. | 
      
  | 
  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.
| notify_handler | A class instance to handle callback notifications from this controller. | 
| settings | Configuration settings used by this controller. | 
| rdm_handler | A 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. |