receiver.h

Go to the documentation of this file.

/******************************************************************************
 * Copyright 2024 ETC Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ******************************************************************************
 * This file is a part of sACN. For more information, go to:
 * https://github.com/ETCLabs/sACN
 *****************************************************************************/
 
#ifndef SACN_CPP_RECEIVER_H_
#define SACN_CPP_RECEIVER_H_
 
#include <vector>
 
#include "sacn/cpp/common.h"
 
#include "sacn/receiver.h"
#include "etcpal/cpp/inet.h"
#include "etcpal/cpp/opaque_id.h"
 
namespace sacn
{
 
namespace detail
{
class ReceiverHandleType
{
};
};  // namespace detail
 
class Receiver
{
public:
  using Handle = etcpal::OpaqueId<detail::ReceiverHandleType, sacn_receiver_t, SACN_RECEIVER_INVALID>;
 
  class NotifyHandler
  {
  public:
    virtual ~NotifyHandler() = default;
 
    virtual void HandleUniverseData(Handle receiver_handle, const etcpal::SockAddr& source_addr,
                                    const SacnRemoteSource& source_info, const SacnRecvUniverseData& universe_data) = 0;
 
    virtual void HandleSourcesLost(Handle handle, uint16_t universe,
                                   const std::vector<SacnLostSource>& lost_sources) = 0;
 
    virtual void HandleSamplingPeriodStarted(Handle handle, uint16_t universe)
    {
      ETCPAL_UNUSED_ARG(handle);
      ETCPAL_UNUSED_ARG(universe);
    }
 
    virtual void HandleSamplingPeriodEnded(Handle handle, uint16_t universe)
    {
      ETCPAL_UNUSED_ARG(handle);
      ETCPAL_UNUSED_ARG(universe);
    }
 
    virtual void HandleSourcePapLost(Handle handle, uint16_t universe, const SacnRemoteSource& source)
    {
      ETCPAL_UNUSED_ARG(handle);
      ETCPAL_UNUSED_ARG(universe);
      ETCPAL_UNUSED_ARG(source);
    }
 
    virtual void HandleSourceLimitExceeded(Handle handle, uint16_t universe)
    {
      ETCPAL_UNUSED_ARG(handle);
      ETCPAL_UNUSED_ARG(universe);
    }
  };
 
  struct Settings
  {
    /********* Required values **********/
 
    uint16_t universe_id{0}; 
    /********* Optional values **********/
 
    SacnRecvUniverseSubrange footprint{1, DMX_ADDRESS_COUNT};
 
    int source_count_max{SACN_RECEIVER_INFINITE_SOURCES};
    unsigned int flags{0}; 
    sacn_ip_support_t ip_supported{kSacnIpV4AndIpV6}; 
    Settings() = default;
 
    Settings(uint16_t new_universe_id);
 
    bool IsValid() const;
  };
 
  struct NetintList
  {
    sacn_receiver_t handle{SACN_RECEIVER_INVALID};
 
    std::vector<SacnMcastInterface> netints;
 
    bool no_netints{false};
 
    NetintList() = default;
    NetintList(sacn_receiver_t receiver_handle, McastMode mcast_mode);
    NetintList(sacn_receiver_t receiver_handle, const std::vector<SacnMcastInterface>& network_interfaces);
  };
 
  Receiver() = default;
  Receiver(const Receiver& other) = delete;
  Receiver& operator=(const Receiver& other) = delete;
  Receiver(Receiver&& other) = default;            
  Receiver& operator=(Receiver&& other) = default; 
  etcpal::Error Startup(const Settings& settings, NotifyHandler& notify_handler, McastMode mcast_mode);
  etcpal::Error Startup(const Settings& settings, NotifyHandler& notify_handler,
                        std::vector<SacnMcastInterface>& netints);
  void Shutdown();
  etcpal::Expected<uint16_t> GetUniverse() const;
  etcpal::Expected<SacnRecvUniverseSubrange> GetFootprint() const;
  etcpal::Error ChangeUniverse(uint16_t new_universe_id);
  etcpal::Error ChangeFootprint(const SacnRecvUniverseSubrange& new_footprint);
  etcpal::Error ChangeUniverseAndFootprint(uint16_t new_universe_id, const SacnRecvUniverseSubrange& new_footprint);
  std::vector<EtcPalMcastNetintId> GetNetworkInterfaces();
 
  // Lesser used functions.  These apply to all instances of this class.
  static void SetExpiredWait(uint32_t wait_ms);
  static uint32_t GetExpiredWait();
 
  static etcpal::Error ResetNetworking(McastMode mcast_mode);
  static etcpal::Error ResetNetworking(std::vector<SacnMcastInterface>& netints);
  static etcpal::Error ResetNetworking(std::vector<SacnMcastInterface>& sys_netints,
                                       std::vector<NetintList>& netint_lists);
 
  constexpr Handle handle() const;
 
private:
  SacnReceiverConfig TranslateConfig(const Settings& settings, NotifyHandler& notify_handler);
 
  Handle handle_;
};
 
namespace internal
{
extern "C" inline void ReceiverCbUniverseData(sacn_receiver_t receiver_handle, const EtcPalSockAddr* source_addr,
                                              const SacnRemoteSource* source_info,
                                              const SacnRecvUniverseData* universe_data, void* context)
{
  if (source_addr && source_info && universe_data && context)
  {
    static_cast<Receiver::NotifyHandler*>(context)->HandleUniverseData(Receiver::Handle(receiver_handle), *source_addr,
                                                                       *source_info, *universe_data);
  }
}
 
extern "C" inline void ReceiverCbSourcesLost(sacn_receiver_t handle, uint16_t universe,
                                             const SacnLostSource* lost_sources, size_t num_lost_sources, void* context)
{
  if (context && lost_sources && (num_lost_sources > 0))
  {
    std::vector<SacnLostSource> lost_vec(lost_sources, lost_sources + num_lost_sources);
    static_cast<Receiver::NotifyHandler*>(context)->HandleSourcesLost(Receiver::Handle(handle), universe, lost_vec);
  }
}
 
extern "C" inline void ReceiverCbSamplingPeriodStarted(sacn_receiver_t handle, uint16_t universe, void* context)
{
  if (context)
  {
    static_cast<Receiver::NotifyHandler*>(context)->HandleSamplingPeriodStarted(Receiver::Handle(handle), universe);
  }
}
 
extern "C" inline void ReceiverCbSamplingPeriodEnded(sacn_receiver_t handle, uint16_t universe, void* context)
{
  if (context)
  {
    static_cast<Receiver::NotifyHandler*>(context)->HandleSamplingPeriodEnded(Receiver::Handle(handle), universe);
  }
}
 
extern "C" inline void ReceiverCbPapLost(sacn_receiver_t handle, uint16_t universe, const SacnRemoteSource* source,
                                         void* context)
{
  if (context && source)
  {
    static_cast<Receiver::NotifyHandler*>(context)->HandleSourcePapLost(Receiver::Handle(handle), universe, *source);
  }
}
 
extern "C" inline void ReceiverCbSourceLimitExceeded(sacn_receiver_t handle, uint16_t universe, void* context)
{
  if (context)
  {
    static_cast<Receiver::NotifyHandler*>(context)->HandleSourceLimitExceeded(Receiver::Handle(handle), universe);
  }
}
 
};  // namespace internal
 
inline Receiver::Settings::Settings(uint16_t new_universe_id) : universe_id(new_universe_id)
{
}
 
inline bool Receiver::Settings::IsValid() const
{
  return (universe_id > 0) && (footprint.start_address >= 1) && (footprint.start_address <= DMX_ADDRESS_COUNT) &&
         (footprint.address_count >= 1) &&
         (footprint.address_count <= (DMX_ADDRESS_COUNT - footprint.start_address + 1));
}
 
inline Receiver::NetintList::NetintList(sacn_receiver_t receiver_handle,
                                        McastMode mcast_mode = McastMode::kEnabledOnAllInterfaces)
    : handle(receiver_handle), no_netints(mcast_mode == McastMode::kDisabledOnAllInterfaces)
{
}
 
inline Receiver::NetintList::NetintList(sacn_receiver_t receiver_handle,
                                        const std::vector<SacnMcastInterface>& network_interfaces)
    : handle(receiver_handle), netints(network_interfaces)
{
}
 
inline etcpal::Error Receiver::Startup(const Settings& settings, NotifyHandler& notify_handler,
                                       McastMode mcast_mode = McastMode::kEnabledOnAllInterfaces)
{
  SacnReceiverConfig config = TranslateConfig(settings, notify_handler);
 
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  if (mcast_mode == McastMode::kDisabledOnAllInterfaces)
    netint_config.no_netints = true;
 
  sacn_receiver_t c_handle = SACN_RECEIVER_INVALID;
  etcpal::Error result = sacn_receiver_create(&config, &c_handle, &netint_config);
 
  handle_.SetValue(c_handle);
 
  return result;
}
 
inline etcpal::Error Receiver::Startup(const Settings& settings, NotifyHandler& notify_handler,
                                       std::vector<SacnMcastInterface>& netints)
{
  SacnReceiverConfig config = TranslateConfig(settings, notify_handler);
 
  sacn_receiver_t c_handle = SACN_RECEIVER_INVALID;
  etcpal::Error result = kEtcPalErrOk;
 
  if (netints.empty())
  {
    result = sacn_receiver_create(&config, &c_handle, NULL);
  }
  else
  {
    SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
    netint_config.netints = netints.data();
    netint_config.num_netints = netints.size();
 
    result = sacn_receiver_create(&config, &c_handle, &netint_config);
  }
 
  handle_.SetValue(c_handle);
 
  return result;
}
 
inline void Receiver::Shutdown()
{
  sacn_receiver_destroy(handle_.value());
  handle_.Clear();
}
 
inline etcpal::Expected<uint16_t> Receiver::GetUniverse() const
{
  uint16_t result = 0;
  etcpal_error_t err = sacn_receiver_get_universe(handle_.value(), &result);
  if (err == kEtcPalErrOk)
    return result;
  else
    return err;
}
 
inline etcpal::Expected<SacnRecvUniverseSubrange> Receiver::GetFootprint() const
{
  SacnRecvUniverseSubrange result;
  etcpal_error_t err = sacn_receiver_get_footprint(handle_.value(), &result);
  if (err == kEtcPalErrOk)
    return result;
  else
    return err;
}
 
inline etcpal::Error Receiver::ChangeUniverse(uint16_t new_universe_id)
{
  return sacn_receiver_change_universe(handle_.value(), new_universe_id);
}
 
inline etcpal::Error Receiver::ChangeFootprint(const SacnRecvUniverseSubrange& new_footprint)
{
  return sacn_receiver_change_footprint(handle_.value(), &new_footprint);
}
 
inline etcpal::Error Receiver::ChangeUniverseAndFootprint(uint16_t new_universe_id,
                                                          const SacnRecvUniverseSubrange& new_footprint)
{
  return sacn_receiver_change_universe_and_footprint(handle_.value(), new_universe_id, &new_footprint);
}
 
inline std::vector<EtcPalMcastNetintId> Receiver::GetNetworkInterfaces()
{
  // This uses a guessing algorithm with a while loop to avoid race conditions.
  std::vector<EtcPalMcastNetintId> netints;
  size_t size_guess = 4u;
  size_t num_netints = 0u;
 
  do
  {
    netints.resize(size_guess);
    num_netints = sacn_receiver_get_network_interfaces(handle_.value(), netints.data(), netints.size());
    size_guess = num_netints + 4u;
  } while (num_netints > netints.size());
 
  netints.resize(num_netints);
  return netints;
}
 
inline void Receiver::SetExpiredWait(uint32_t wait_ms)
{
  sacn_receiver_set_expired_wait(wait_ms);
}
 
inline uint32_t Receiver::GetExpiredWait()
{
  return sacn_receiver_get_expired_wait();
}
 
inline etcpal::Error Receiver::ResetNetworking(McastMode mcast_mode = McastMode::kEnabledOnAllInterfaces)
{
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  if (mcast_mode == McastMode::kDisabledOnAllInterfaces)
    netint_config.no_netints = true;
 
  return sacn_receiver_reset_networking(&netint_config);
}
 
inline etcpal::Error Receiver::ResetNetworking(std::vector<SacnMcastInterface>& sys_netints)
{
  if (sys_netints.empty())
    return sacn_receiver_reset_networking(nullptr);
 
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  netint_config.netints = sys_netints.data();
  netint_config.num_netints = sys_netints.size();
 
  return sacn_receiver_reset_networking(&netint_config);
}
 
inline etcpal::Error Receiver::ResetNetworking(std::vector<SacnMcastInterface>& sys_netints,
                                               std::vector<NetintList>& per_receiver_netint_lists)
{
  std::vector<SacnReceiverNetintList> netint_lists_c;
  netint_lists_c.reserve(per_receiver_netint_lists.size());
  std::transform(
      per_receiver_netint_lists.begin(), per_receiver_netint_lists.end(), std::back_inserter(netint_lists_c),
      [](NetintList& list) {
        // clang-format off
                   SacnReceiverNetintList c_list = {
                     list.handle,
                     list.netints.data(),
                     list.netints.size(),
                     list.no_netints
                   };
        // clang-format on
 
        return c_list;
      });
 
  SacnNetintConfig sys_netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  sys_netint_config.netints = sys_netints.data();
  sys_netint_config.num_netints = sys_netints.size();
 
  return sacn_receiver_reset_networking_per_receiver(&sys_netint_config, netint_lists_c.data(), netint_lists_c.size());
}
 
inline constexpr Receiver::Handle Receiver::handle() const
{
  return handle_;
}
 
inline SacnReceiverConfig Receiver::TranslateConfig(const Settings& settings, NotifyHandler& notify_handler)
{
  // clang-format off
  SacnReceiverConfig config = {
    settings.universe_id,
    {
      internal::ReceiverCbUniverseData,
      internal::ReceiverCbSourcesLost,
      internal::ReceiverCbSamplingPeriodStarted,
      internal::ReceiverCbSamplingPeriodEnded,
      internal::ReceiverCbPapLost,
      internal::ReceiverCbSourceLimitExceeded,
      &notify_handler
    },
    settings.footprint,
    settings.source_count_max,
    settings.flags,
    settings.ip_supported
  };
  // clang-format on
 
  return config;
}
 
};  // namespace sacn
 
#endif  // SACN_CPP_RECEIVER_H_