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, SACN_MERGE_RECEIVER_INVALID>;
 
  class NotifyHandler
  {
  public:
    virtual ~NotifyHandler() = 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, DMX_ADDRESS_COUNT};
 
    int source_count_max{SACN_RECEIVER_INFINITE_SOURCES};
 
    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{SACN_MERGE_RECEIVER_INVALID};
 
    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;
    etcpal::Uuid cid;
    std::string name;
    etcpal::SockAddr addr;
    bool per_address_priorities_active;
    uint8_t universe_priority;
  };
 
  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:
  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 <= DMX_ADDRESS_COUNT) &&
         (footprint.address_count >= 1) &&
         (footprint.address_count <= (DMX_ADDRESS_COUNT - 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 = SACN_MERGE_RECEIVER_INVALID;
  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 = SACN_MERGE_RECEIVER_INVALID;
  etcpal::Error result = kEtcPalErrOk;
 
  if (netints.empty())
  {
    result = sacn_merge_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_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;
  else
    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;
  else
    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.
  std::vector<EtcPalMcastNetintId> netints;
  size_t size_guess = 4u;
  size_t num_netints = 0u;
 
  do
  {
    netints.resize(size_guess);
    num_netints = sacn_merge_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 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());
}
 
inline 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_