merge_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_MERGE_RECEIVER_H_
#define SACN_CPP_MERGE_RECEIVER_H_
 
#include "sacn/cpp/common.h"
 
#include "sacn/merge_receiver.h"
#include "etcpal/cpp/inet.h"
#include "etcpal/cpp/opaque_id.h"
#include "etcpal/cpp/uuid.h"
 
namespace sacn
{
 
namespace detail
{
class MergeReceiverHandleType
{
};
};  // namespace detail
 
class MergeReceiver
{
public:
  using Handle = etcpal::OpaqueId<detail::MergeReceiverHandleType, sacn_merge_receiver_t, kSacnMergeReceiverInvalid>;
 
  class NotifyHandler
  {
  public:
    NotifyHandler()          = default;
    virtual ~NotifyHandler() = default;
 
    NotifyHandler(const NotifyHandler& other) = default;
 
    NotifyHandler& operator=(const NotifyHandler& other) = default;
 
    NotifyHandler(NotifyHandler&& other) = default;
 
    NotifyHandler& operator=(NotifyHandler&& other) = default;
 
    virtual void HandleMergedData(Handle handle, const SacnRecvMergedData& merged_data) = 0;
 
    virtual void HandleNonDmxData(Handle                      receiver_handle,
                                  const etcpal::SockAddr&     source_addr,
                                  const SacnRemoteSource&     source_info,
                                  const SacnRecvUniverseData& universe_data)
    {
      ETCPAL_UNUSED_ARG(receiver_handle);
      ETCPAL_UNUSED_ARG(source_addr);
      ETCPAL_UNUSED_ARG(source_info);
      ETCPAL_UNUSED_ARG(universe_data);
    }
 
    virtual void HandleSourcesLost(Handle handle, uint16_t universe, const std::vector<SacnLostSource>& lost_sources)
    {
      ETCPAL_UNUSED_ARG(handle);
      ETCPAL_UNUSED_ARG(universe);
      ETCPAL_UNUSED_ARG(lost_sources);
    }
 
    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, SACN_MERGE_RECEIVER_MAX_SLOTS};
 
    int source_count_max{kSacnReceiverInfiniteSources};
 
    bool use_pap{true};
 
    sacn_ip_support_t ip_supported{kSacnIpV4AndIpV6};
 
    Settings() = default;
 
    Settings(uint16_t new_universe_id);
 
    bool IsValid() const;
  };
 
  struct NetintList
  {
    sacn_merge_receiver_t handle{kSacnMergeReceiverInvalid};
 
    std::vector<SacnMcastInterface> netints;
 
    bool no_netints{false};
 
    NetintList() = default;
    NetintList(sacn_merge_receiver_t merge_receiver_handle, McastMode mcast_mode);
    NetintList(sacn_merge_receiver_t merge_receiver_handle, const std::vector<SacnMcastInterface>& network_interfaces);
  };
 
  struct Source
  {
    sacn_remote_source_t handle{kSacnRemoteSourceInvalid};
    etcpal::Uuid cid;
    std::string name;
    etcpal::SockAddr addr;
    bool per_address_priorities_active{false};
    uint8_t universe_priority{0u};
  };
 
  MergeReceiver()          = default;
  virtual ~MergeReceiver() = default;
 
  MergeReceiver(const MergeReceiver& other)            = delete;
  MergeReceiver& operator=(const MergeReceiver& other) = delete;
  MergeReceiver(MergeReceiver&& other)                 = default; 
  MergeReceiver& operator=(MergeReceiver&& 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();
  etcpal::Expected<Source>         GetSource(sacn_remote_source_t source_handle);
 
  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:
  static SacnMergeReceiverConfig TranslateConfig(const Settings& settings, NotifyHandler& notify_handler);
 
  Handle handle_;
};
 
namespace internal
{
extern "C" inline void MergeReceiverCbMergedData(sacn_merge_receiver_t     handle,
                                                 const SacnRecvMergedData* merged_data,
                                                 void*                     context)
{
  if (context && merged_data)
  {
    static_cast<MergeReceiver::NotifyHandler*>(context)->HandleMergedData(MergeReceiver::Handle(handle), *merged_data);
  }
}
 
extern "C" inline void MergeReceiverCbNonDmx(sacn_merge_receiver_t       receiver_handle,
                                             const EtcPalSockAddr*       source_addr,
                                             const SacnRemoteSource*     source_info,
                                             const SacnRecvUniverseData* universe_data,
                                             void*                       context)
{
  if (context && source_addr && source_info && universe_data)
  {
    static_cast<MergeReceiver::NotifyHandler*>(context)->HandleNonDmxData(MergeReceiver::Handle(receiver_handle),
                                                                          *source_addr, *source_info, *universe_data);
  }
}
 
extern "C" inline void MergeReceiverCbSourcesLost(sacn_merge_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<MergeReceiver::NotifyHandler*>(context)->HandleSourcesLost(MergeReceiver::Handle(handle), universe,
                                                                           lost_vec);
  }
}
 
extern "C" inline void MergeReceiverCbSamplingPeriodStarted(sacn_merge_receiver_t handle,
                                                            uint16_t              universe,
                                                            void*                 context)
{
  if (context)
  {
    static_cast<MergeReceiver::NotifyHandler*>(context)->HandleSamplingPeriodStarted(MergeReceiver::Handle(handle),
                                                                                     universe);
  }
}
 
extern "C" inline void MergeReceiverCbSamplingPeriodEnded(sacn_merge_receiver_t handle,
                                                          uint16_t              universe,
                                                          void*                 context)
{
  if (context)
  {
    static_cast<MergeReceiver::NotifyHandler*>(context)->HandleSamplingPeriodEnded(MergeReceiver::Handle(handle),
                                                                                   universe);
  }
}
 
extern "C" inline void MergeReceiverCbSourcePapLost(sacn_merge_receiver_t   handle,
                                                    uint16_t                universe,
                                                    const SacnRemoteSource* source,
                                                    void*                   context)
{
  if (context && source)
  {
    static_cast<MergeReceiver::NotifyHandler*>(context)->HandleSourcePapLost(MergeReceiver::Handle(handle), universe,
                                                                             *source);
  }
}
 
extern "C" inline void MergeReceiverCbSourceLimitExceeded(sacn_merge_receiver_t handle,
                                                          uint16_t              universe,
                                                          void*                 context)
{
  if (context)
  {
    static_cast<MergeReceiver::NotifyHandler*>(context)->HandleSourceLimitExceeded(MergeReceiver::Handle(handle),
                                                                                   universe);
  }
}
 
};  // namespace internal
 
inline MergeReceiver::Settings::Settings(uint16_t new_universe_id) : universe_id(new_universe_id)
{
}
 
inline bool MergeReceiver::Settings::IsValid() const
{
  return (universe_id > 0) && (footprint.start_address >= 1) &&
         (footprint.start_address <= SACN_MERGE_RECEIVER_MAX_SLOTS) && (footprint.address_count >= 1) &&
         (footprint.address_count <= (SACN_MERGE_RECEIVER_MAX_SLOTS - footprint.start_address + 1));
}
 
inline MergeReceiver::NetintList::NetintList(sacn_merge_receiver_t merge_receiver_handle,
                                             McastMode             mcast_mode = McastMode::kEnabledOnAllInterfaces)
    : handle(merge_receiver_handle), no_netints(mcast_mode == McastMode::kDisabledOnAllInterfaces)
{
}
 
inline MergeReceiver::NetintList::NetintList(sacn_merge_receiver_t                  merge_receiver_handle,
                                             const std::vector<SacnMcastInterface>& network_interfaces)
    : handle(merge_receiver_handle), netints(network_interfaces)
{
}
 
inline etcpal::Error MergeReceiver::Startup(const Settings& settings,
                                            NotifyHandler&  notify_handler,
                                            McastMode       mcast_mode = McastMode::kEnabledOnAllInterfaces)
{
  SacnMergeReceiverConfig config = TranslateConfig(settings, notify_handler);
 
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  if (mcast_mode == McastMode::kDisabledOnAllInterfaces)
    netint_config.no_netints = true;
 
  sacn_merge_receiver_t c_handle = kSacnMergeReceiverInvalid;
  etcpal::Error         result   = sacn_merge_receiver_create(&config, &c_handle, &netint_config);
 
  handle_.SetValue(c_handle);
 
  return result;
}
 
inline etcpal::Error MergeReceiver::Startup(const Settings&                  settings,
                                            NotifyHandler&                   notify_handler,
                                            std::vector<SacnMcastInterface>& netints)
{
  SacnMergeReceiverConfig config = TranslateConfig(settings, notify_handler);
 
  sacn_merge_receiver_t c_handle = kSacnMergeReceiverInvalid;
  etcpal::Error         result   = kEtcPalErrOk;
 
  if (netints.empty())
  {
    result = sacn_merge_receiver_create(&config, &c_handle, nullptr);
  }
  else
  {
    SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
    netint_config.netints          = netints.data();
    netint_config.num_netints      = netints.size();
 
    result = sacn_merge_receiver_create(&config, &c_handle, &netint_config);
  }
 
  handle_.SetValue(c_handle);
 
  return result;
}
 
inline void MergeReceiver::Shutdown()
{
  sacn_merge_receiver_destroy(handle_.value());
  handle_.Clear();
}
 
inline etcpal::Expected<uint16_t> MergeReceiver::GetUniverse() const
{
  uint16_t       result = 0;
  etcpal_error_t err    = sacn_merge_receiver_get_universe(handle_.value(), &result);
  if (err == kEtcPalErrOk)
    return result;
 
  return err;
}
 
inline etcpal::Expected<SacnRecvUniverseSubrange> MergeReceiver::GetFootprint() const
{
  SacnRecvUniverseSubrange result;
  etcpal_error_t           err = sacn_merge_receiver_get_footprint(handle_.value(), &result);
  if (err == kEtcPalErrOk)
    return result;
 
  return err;
}
 
inline etcpal::Error MergeReceiver::ChangeUniverse(uint16_t new_universe_id)
{
  return sacn_merge_receiver_change_universe(handle_.value(), new_universe_id);
}
 
inline etcpal::Error MergeReceiver::ChangeFootprint(const SacnRecvUniverseSubrange& new_footprint)
{
  return sacn_merge_receiver_change_footprint(handle_.value(), &new_footprint);
}
 
inline etcpal::Error MergeReceiver::ChangeUniverseAndFootprint(uint16_t                        new_universe_id,
                                                               const SacnRecvUniverseSubrange& new_footprint)
{
  return sacn_merge_receiver_change_universe_and_footprint(handle_.value(), new_universe_id, &new_footprint);
}
 
inline std::vector<EtcPalMcastNetintId> MergeReceiver::GetNetworkInterfaces()
{
  // This uses a guessing algorithm with a while loop to avoid race conditions.
  size_t                           size_guess = 4u;
  std::vector<EtcPalMcastNetintId> netints(size_guess);
  size_t num_netints = sacn_merge_receiver_get_network_interfaces(handle_.value(), netints.data(), netints.size());
 
  while (num_netints > netints.size())
  {
    size_guess = num_netints + 4u;
    netints.resize(size_guess);
    num_netints = sacn_merge_receiver_get_network_interfaces(handle_.value(), netints.data(), netints.size());
  }
 
  netints.resize(num_netints);
  return netints;
}
 
inline etcpal::Expected<MergeReceiver::Source> MergeReceiver::GetSource(sacn_remote_source_t source_handle)
{
  SacnMergeReceiverSource c_info;
  etcpal_error_t          error = sacn_merge_receiver_get_source(handle_.value(), source_handle, &c_info);
  if (error == kEtcPalErrOk)
  {
    MergeReceiver::Source res;
    res.handle                        = c_info.handle;
    res.cid                           = c_info.cid;
    res.name                          = c_info.name;
    res.addr                          = c_info.addr;
    res.per_address_priorities_active = c_info.per_address_priorities_active;
    res.universe_priority             = c_info.universe_priority;
    return res;
  }
 
  return error;
}
 
inline etcpal::Error MergeReceiver::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_merge_receiver_reset_networking(&netint_config);
}
 
inline etcpal::Error MergeReceiver::ResetNetworking(std::vector<SacnMcastInterface>& sys_netints)
{
  if (sys_netints.empty())
    return sacn_merge_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_merge_receiver_reset_networking(&netint_config);
}
 
inline etcpal::Error MergeReceiver::ResetNetworking(std::vector<SacnMcastInterface>& sys_netints,
                                                    std::vector<NetintList>&         per_receiver_netint_lists)
{
  std::vector<SacnMergeReceiverNetintList> 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
                   SacnMergeReceiverNetintList c_list = {
                     list.handle,
                     list.netints.data(),
                     list.netints.size(),
                     list.no_netints
                   };
                   // clang-format on
 
                   return c_list;
                 });
 
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  netint_config.netints          = sys_netints.data();
  netint_config.num_netints      = sys_netints.size();
 
  return sacn_merge_receiver_reset_networking_per_receiver(&netint_config, netint_lists_c.data(),
                                                           netint_lists_c.size());
}
 
constexpr MergeReceiver::Handle MergeReceiver::handle() const
{
  return handle_;
}
 
inline SacnMergeReceiverConfig MergeReceiver::TranslateConfig(const Settings& settings, NotifyHandler& notify_handler)
{
  // clang-format off
  SacnMergeReceiverConfig config = {
    settings.universe_id,
    {
      internal::MergeReceiverCbMergedData,
      internal::MergeReceiverCbNonDmx,
      internal::MergeReceiverCbSourcesLost,
      internal::MergeReceiverCbSamplingPeriodStarted,
      internal::MergeReceiverCbSamplingPeriodEnded,
      internal::MergeReceiverCbSourcePapLost,
      internal::MergeReceiverCbSourceLimitExceeded,
      &notify_handler
    },
    settings.footprint,
    settings.source_count_max,
    settings.use_pap,
    settings.ip_supported
  };
  // clang-format on
 
  return config;
}
 
};  // namespace sacn
 
#endif  // SACN_CPP_MERGE_RECEIVER_H_