source.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_SOURCE_H_
#define SACN_CPP_SOURCE_H_
 
#include "sacn/cpp/common.h"
 
#include <cstring>
#include "sacn/source.h"
#include "etcpal/cpp/uuid.h"
#include "etcpal/cpp/inet.h"
#include "etcpal/cpp/opaque_id.h"
 
namespace sacn
{
 
namespace detail
{
class SourceHandleType
{
};
};  // namespace detail
 
class Source
{
public:
  using Handle = etcpal::OpaqueId<detail::SourceHandleType, sacn_source_t, kSacnSourceInvalid>;
 
  enum class TickMode
  {
    kProcessLevelsOnly = kSacnSourceTickModeProcessLevelsOnly,
    kProcessPapOnly = kSacnSourceTickModeProcessPapOnly,
    kProcessLevelsAndPap = kSacnSourceTickModeProcessLevelsAndPap
  };
 
  struct Settings
  {
    /********* Required values **********/
 
    etcpal::Uuid cid;
    std::string name;
 
    /********* Optional values **********/
 
    size_t universe_count_max{kSacnSourceInfiniteUniverses};
 
    bool manually_process_source{false};
 
    sacn_ip_support_t ip_supported{kSacnIpV4AndIpV6};
 
    int keep_alive_interval{kSacnSourceKeepAliveIntervalDefault};
 
    int pap_keep_alive_interval{kSacnSourcePapKeepAliveIntervalDefault};
 
    Settings() = default;
    Settings(etcpal::Uuid new_cid, std::string new_name);
 
    bool IsValid() const;
  };
 
  struct UniverseSettings
  {
    /********* Required values **********/
 
    uint16_t universe{0};
 
    /********* Optional values **********/
 
    uint8_t priority{100};
 
    bool send_preview{false};
 
    bool send_unicast_only{false};
 
    std::vector<etcpal::IpAddr> unicast_destinations;
 
    uint16_t sync_universe{0};
 
    UniverseSettings() = default;
    UniverseSettings(uint16_t universe_id);
 
    bool IsValid() const;
  };
 
  struct UniverseNetintList
  {
    sacn_source_t handle{kSacnSourceInvalid};
    uint16_t universe{0};
 
    std::vector<SacnMcastInterface> netints;
 
    bool no_netints{false};
 
    UniverseNetintList() = default;
    UniverseNetintList(sacn_source_t source_handle, uint16_t universe_id, McastMode mcast_mode);
    UniverseNetintList(sacn_source_t                          source_handle,
                       uint16_t                               universe_id,
                       const std::vector<SacnMcastInterface>& network_interfaces);
  };
 
  Source()          = default;
  virtual ~Source() = default;
 
  Source(const Source& other)            = delete;
  Source& operator=(const Source& other) = delete;
  Source(Source&& other)                 = default; 
  Source& operator=(Source&& other)      = default; 
  etcpal::Error Startup(const Settings& settings);
  void          Shutdown();
 
  etcpal::Error ChangeName(const std::string& new_name);
 
  etcpal::Error         AddUniverse(const UniverseSettings& settings, McastMode mcast_mode);
  etcpal::Error         AddUniverse(const UniverseSettings& settings, std::vector<SacnMcastInterface>& netints);
  void                  RemoveUniverse(uint16_t universe);
  std::vector<uint16_t> GetUniverses();
 
  etcpal::Error               AddUnicastDestination(uint16_t universe, const etcpal::IpAddr& dest);
  void                        RemoveUnicastDestination(uint16_t universe, const etcpal::IpAddr& dest);
  std::vector<etcpal::IpAddr> GetUnicastDestinations(uint16_t universe);
 
  etcpal::Error ChangePriority(uint16_t universe, uint8_t new_priority);
  etcpal::Error ChangePreviewFlag(uint16_t universe, bool new_preview_flag);
  etcpal::Error ChangeSynchronizationUniverse(uint16_t universe, uint16_t new_sync_universe);
 
  etcpal::Error SendNow(uint16_t universe, uint8_t start_code, const uint8_t* buffer, size_t buflen);
  etcpal::Error SendSynchronization(uint16_t universe);
 
  void UpdateLevels(uint16_t universe, const uint8_t* new_levels, size_t new_levels_size);
  void UpdateLevelsAndPap(uint16_t       universe,
                          const uint8_t* new_levels,
                          size_t         new_levels_size,
                          const uint8_t* new_priorities,
                          size_t         new_priorities_size);
  void UpdateLevelsAndForceSync(uint16_t universe, const uint8_t* new_levels, size_t new_levels_size);
  void UpdateLevelsAndPapAndForceSync(uint16_t       universe,
                                      const uint8_t* new_levels,
                                      size_t         new_levels_size,
                                      const uint8_t* new_priorities,
                                      size_t         new_priorities_size);
 
  std::vector<EtcPalMcastNetintId> GetNetworkInterfaces(uint16_t universe);
 
  constexpr Handle handle() const;
 
  static int ProcessManual(TickMode tick_mode);
 
  static etcpal::Error ResetNetworking(McastMode mcast_mode, const SacnSendSocketConfig& send_socket_config);
  static etcpal::Error ResetNetworking(std::vector<SacnMcastInterface>& netints,
                                       const SacnSendSocketConfig&      send_socket_config);
  static etcpal::Error ResetNetworking(std::vector<SacnMcastInterface>& sys_netints,
                                       std::vector<UniverseNetintList>& netint_lists,
                                       const SacnSendSocketConfig&      send_socket_config);
 
private:
  class TranslatedUniverseConfig
  {
  public:
    explicit TranslatedUniverseConfig(const UniverseSettings& settings);
    const SacnSourceUniverseConfig& get() noexcept;
 
  private:
    std::vector<EtcPalIpAddr> unicast_destinations_;
    SacnSourceUniverseConfig  config_;
  };
 
  static SacnSourceConfig TranslateConfig(const Settings& settings);
 
  Handle handle_;
};
 
inline Source::Settings::Settings(etcpal::Uuid new_cid, std::string new_name)
    : cid(std::move(new_cid)), name(std::move(new_name))
{
}
 
inline bool Source::Settings::IsValid() const
{
  return !cid.IsNull();
}
 
inline Source::UniverseSettings::UniverseSettings(uint16_t universe_id) : universe(universe_id)
{
}
 
inline bool Source::UniverseSettings::IsValid() const
{
  return ((universe >= sacn::kMinimumUniverse) && (universe <= sacn::kMaximumUniverse));
}
 
inline Source::UniverseNetintList::UniverseNetintList(sacn_source_t source_handle,
                                                      uint16_t      universe_id,
                                                      McastMode     mcast_mode = McastMode::kEnabledOnAllInterfaces)
    : handle(source_handle), universe(universe_id), no_netints(mcast_mode == McastMode::kDisabledOnAllInterfaces)
{
}
 
inline Source::UniverseNetintList::UniverseNetintList(sacn_source_t                          source_handle,
                                                      uint16_t                               universe_id,
                                                      const std::vector<SacnMcastInterface>& network_interfaces)
    : handle(source_handle), universe(universe_id), netints(network_interfaces)
{
}
 
inline etcpal::Error Source::Startup(const Settings& settings)
{
  SacnSourceConfig config   = TranslateConfig(settings);
  sacn_source_t    c_handle = kSacnSourceInvalid;
  etcpal::Error    result   = sacn_source_create(&config, &c_handle);
  handle_.SetValue(c_handle);
  return result;
}
 
inline void Source::Shutdown()
{
  sacn_source_destroy(handle_.value());
  handle_.Clear();
}
 
inline etcpal::Error Source::ChangeName(const std::string& new_name)
{
  return sacn_source_change_name(handle_.value(), new_name.c_str());
}
 
inline etcpal::Error Source::AddUniverse(const UniverseSettings& settings,
                                         McastMode               mcast_mode = McastMode::kEnabledOnAllInterfaces)
{
  TranslatedUniverseConfig config(settings);
 
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  if (mcast_mode == McastMode::kDisabledOnAllInterfaces)
    netint_config.no_netints = true;
 
  return sacn_source_add_universe(handle_.value(), &config.get(), &netint_config);
}
 
inline etcpal::Error Source::AddUniverse(const UniverseSettings& settings, std::vector<SacnMcastInterface>& netints)
{
  TranslatedUniverseConfig config(settings);
 
  if (netints.empty())
    return sacn_source_add_universe(handle_.value(), &config.get(), nullptr);
 
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  netint_config.netints          = netints.data();
  netint_config.num_netints      = netints.size();
 
  return sacn_source_add_universe(handle_.value(), &config.get(), &netint_config);
}
 
inline void Source::RemoveUniverse(uint16_t universe)
{
  sacn_source_remove_universe(handle_.value(), universe);
}
 
inline std::vector<uint16_t> Source::GetUniverses()
{
  // This uses a guessing algorithm with a while loop to avoid race conditions.
  size_t                size_guess = 4u;
  std::vector<uint16_t> universes(size_guess);
  size_t                num_universes = sacn_source_get_universes(handle_.value(), universes.data(), universes.size());
 
  while (num_universes > universes.size())
  {
    size_guess = num_universes + 4u;
    universes.resize(size_guess);
    num_universes = sacn_source_get_universes(handle_.value(), universes.data(), universes.size());
  }
 
  universes.resize(num_universes);
  return universes;
}
 
inline etcpal::Error Source::AddUnicastDestination(uint16_t universe, const etcpal::IpAddr& dest)
{
  return sacn_source_add_unicast_destination(handle_.value(), universe, &dest.get());
}
 
inline void Source::RemoveUnicastDestination(uint16_t universe, const etcpal::IpAddr& dest)
{
  sacn_source_remove_unicast_destination(handle_.value(), universe, &dest.get());
}
 
inline std::vector<etcpal::IpAddr> Source::GetUnicastDestinations(uint16_t universe)
{
  // This uses a guessing algorithm with a while loop to avoid race conditions.
  size_t                    size_guess = 4u;
  std::vector<EtcPalIpAddr> destinations(size_guess);
  size_t                    num_destinations =
      sacn_source_get_unicast_destinations(handle_.value(), universe, destinations.data(), destinations.size());
 
  while (num_destinations > destinations.size())
  {
    size_guess = num_destinations + 4u;
    destinations.resize(size_guess);
    num_destinations =
        sacn_source_get_unicast_destinations(handle_.value(), universe, destinations.data(), destinations.size());
  }
 
  destinations.resize(num_destinations);
 
  // Convert vector<EtcPalIpAddr> to vector<etcpal::IpAddr>.
  std::vector<etcpal::IpAddr> result;
  if (!destinations.empty())
  {
    result.reserve(destinations.size());
    std::transform(destinations.begin(), destinations.end(), std::back_inserter(result),
                   [](const EtcPalIpAddr& dest) { return etcpal::IpAddr(dest); });
  }
 
  return result;
}
 
inline etcpal::Error Source::ChangePriority(uint16_t universe, uint8_t new_priority)
{
  return sacn_source_change_priority(handle_.value(), universe, new_priority);
}
 
inline etcpal::Error Source::ChangePreviewFlag(uint16_t universe, bool new_preview_flag)
{
  return sacn_source_change_preview_flag(handle_.value(), universe, new_preview_flag);
}
 
inline etcpal::Error Source::ChangeSynchronizationUniverse(uint16_t universe, uint16_t new_sync_universe)
{
  return sacn_source_change_synchronization_universe(handle_.value(), universe, new_sync_universe);
}
 
inline etcpal::Error Source::SendNow(uint16_t universe, uint8_t start_code, const uint8_t* buffer, size_t buflen)
{
  return sacn_source_send_now(handle_.value(), universe, start_code, buffer, buflen);
}
 
inline etcpal::Error Source::SendSynchronization(uint16_t sync_universe)
{
  return sacn_source_send_synchronization(handle_.value(), sync_universe);
}
 
inline void Source::UpdateLevels(uint16_t universe, const uint8_t* new_levels, size_t new_levels_size)
{
  sacn_source_update_levels(handle_.value(), universe, new_levels, new_levels_size);
}
 
inline void Source::UpdateLevelsAndPap(uint16_t       universe,
                                       const uint8_t* new_levels,
                                       size_t         new_levels_size,
                                       const uint8_t* new_priorities,
                                       size_t         new_priorities_size)
{
  sacn_source_update_levels_and_pap(handle_.value(), universe, new_levels, new_levels_size, new_priorities,
                                    new_priorities_size);
}
 
inline void Source::UpdateLevelsAndForceSync(uint16_t universe, const uint8_t* new_levels, size_t new_levels_size)
{
  sacn_source_update_levels_and_force_sync(handle_.value(), universe, new_levels, new_levels_size);
}
 
inline void Source::UpdateLevelsAndPapAndForceSync(uint16_t       universe,
                                                   const uint8_t* new_levels,
                                                   size_t         new_levels_size,
                                                   const uint8_t* new_priorities,
                                                   size_t         new_priorities_size)
{
  sacn_source_update_levels_and_pap_and_force_sync(handle_.value(), universe, new_levels, new_levels_size,
                                                   new_priorities, new_priorities_size);
}
 
inline int Source::ProcessManual(TickMode tick_mode = TickMode::kProcessLevelsAndPap)
{
  return sacn_source_process_manual(static_cast<sacn_source_tick_mode_t>(tick_mode));
}
 
inline etcpal::Error Source::ResetNetworking(
    McastMode                   mcast_mode         = McastMode::kEnabledOnAllInterfaces,
    const SacnSendSocketConfig& send_socket_config = SACN_SEND_SOCKET_CONFIG_DEFAULT_INIT)
{
  SacnNetintConfig netint_config = SACN_NETINT_CONFIG_DEFAULT_INIT;
  if (mcast_mode == McastMode::kDisabledOnAllInterfaces)
    netint_config.no_netints = true;
 
  netint_config.send_socket_config = send_socket_config;
 
  return sacn_source_reset_networking(&netint_config);
}
 
inline etcpal::Error Source::ResetNetworking(
    std::vector<SacnMcastInterface>& sys_netints,
    const SacnSendSocketConfig&      send_socket_config = SACN_SEND_SOCKET_CONFIG_DEFAULT_INIT)
{
  SacnNetintConfig netint_config   = SACN_NETINT_CONFIG_DEFAULT_INIT;
  netint_config.send_socket_config = send_socket_config;
 
  if (!sys_netints.empty())
  {
    netint_config.netints     = sys_netints.data();
    netint_config.num_netints = sys_netints.size();
  }
 
  return sacn_source_reset_networking(&netint_config);
}
 
inline etcpal::Error Source::ResetNetworking(
    std::vector<SacnMcastInterface>& sys_netints,
    std::vector<UniverseNetintList>& per_universe_netint_lists,
    const SacnSendSocketConfig&      send_socket_config = SACN_SEND_SOCKET_CONFIG_DEFAULT_INIT)
{
  std::vector<SacnSourceUniverseNetintList> netint_lists_c;
  netint_lists_c.reserve(per_universe_netint_lists.size());
  std::transform(per_universe_netint_lists.begin(), per_universe_netint_lists.end(), std::back_inserter(netint_lists_c),
                 [](UniverseNetintList& list) {
                   // clang-format off
        SacnSourceUniverseNetintList c_list = {
          list.handle,
          list.universe,
          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();
  sys_netint_config.send_socket_config = send_socket_config;
  return sacn_source_reset_networking_per_universe(&sys_netint_config, netint_lists_c.data(), netint_lists_c.size());
}
 
inline std::vector<EtcPalMcastNetintId> Source::GetNetworkInterfaces(uint16_t universe)
{
  // 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_source_get_network_interfaces(handle_.value(), universe, netints.data(), netints.size());
 
  while (num_netints > netints.size())
  {
    size_guess = num_netints + 4u;
    netints.resize(size_guess);
    num_netints = sacn_source_get_network_interfaces(handle_.value(), universe, netints.data(), netints.size());
  }
 
  netints.resize(num_netints);
  return netints;
}
 
constexpr Source::Handle Source::handle() const
{
  return handle_;
}
 
inline SacnSourceConfig Source::TranslateConfig(const Settings& settings)
{
  // clang-format off
  SacnSourceConfig config = {
    settings.cid.get(),
    settings.name.c_str(),
    settings.universe_count_max,
    settings.manually_process_source,
    settings.ip_supported,
    settings.keep_alive_interval,
    settings.pap_keep_alive_interval
  };
  // clang-format on
 
  return config;
}
 
inline const SacnSourceUniverseConfig& Source::TranslatedUniverseConfig::get() noexcept
{
  if (!unicast_destinations_.empty())
  {
    config_.unicast_destinations     = unicast_destinations_.data();
    config_.num_unicast_destinations = unicast_destinations_.size();
  }
 
  return config_;
}
 
// clang-format off
inline Source::TranslatedUniverseConfig::TranslatedUniverseConfig(const UniverseSettings& settings)
    : config_{
        settings.universe,
        settings.priority,
        settings.send_preview,
        settings.send_unicast_only,
        nullptr,
        0,
        settings.sync_universe
      }
{
  // clang-format on
 
  if (!settings.unicast_destinations.empty())
  {
    unicast_destinations_.reserve(settings.unicast_destinations.size());
    std::transform(settings.unicast_destinations.begin(), settings.unicast_destinations.end(),
                   std::back_inserter(unicast_destinations_), [](const etcpal::IpAddr& dest) { return dest.get(); });
  }
}
 
};  // namespace sacn
 
#endif  // SACN_CPP_SOURCE_H_