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_RECEIVER_H_
#define SACN_RECEIVER_H_
 
#include <stdbool.h>
#include <stdint.h>
#include "etcpal/error.h"
#include "etcpal/inet.h"
#include "etcpal/log.h"
#include "etcpal/netint.h"
#include "etcpal/uuid.h"
#include "sacn/common.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef int sacn_receiver_t;
static const sacn_receiver_t kSacnReceiverInvalid = -1;
 
enum
{
  kSacnReceiverInfiniteSources = 0,
 
  kSacnDefaultExpiredWaitMs = 1000u
};
 
typedef struct SacnRecvUniverseSubrange
{
  int start_address; 
  int address_count; 
} SacnRecvUniverseSubrange;
 
typedef struct SacnRecvUniverseData
{
  uint16_t universe_id;
  uint8_t priority;
  bool preview;
  bool is_sampling;
  uint16_t sync_universe;
  uint8_t sequence;
  uint8_t options;
  uint8_t start_code;
  SacnRecvUniverseSubrange slot_range;
  const uint8_t* values;
} SacnRecvUniverseData;
 
typedef struct SacnRemoteSource
{
  sacn_remote_source_t handle;
  EtcPalUuid cid;
  char name[kSacnSourceNameMaxLen];
} SacnRemoteSource;
 
typedef struct SacnLostSource
{
  sacn_remote_source_t handle;
  EtcPalUuid cid;
  char name[kSacnSourceNameMaxLen];
  bool terminated;
} SacnLostSource;
 
enum
{
  kSacnReceiverOptsFilterPreviewData = 0x1
};
typedef void (*SacnUniverseDataCallback)(sacn_receiver_t             receiver_handle,
                                         const EtcPalSockAddr*       source_addr,
                                         const SacnRemoteSource*     source_info,
                                         const SacnRecvUniverseData* universe_data,
                                         void*                       context);
 
typedef void (*SacnSourcesLostCallback)(sacn_receiver_t       handle,
                                        uint16_t              universe,
                                        const SacnLostSource* lost_sources,
                                        size_t                num_lost_sources,
                                        void*                 context);
 
typedef void (*SacnSamplingPeriodStartedCallback)(sacn_receiver_t handle, uint16_t universe, void* context);
 
typedef void (*SacnSamplingPeriodEndedCallback)(sacn_receiver_t handle, uint16_t universe, void* context);
 
typedef void (*SacnSourcePapLostCallback)(sacn_receiver_t         handle,
                                          uint16_t                universe,
                                          const SacnRemoteSource* source,
                                          void*                   context);
 
typedef void (*SacnSourceLimitExceededCallback)(sacn_receiver_t handle, uint16_t universe, void* context);
 
typedef struct SacnReceiverCallbacks
{
  SacnUniverseDataCallback          universe_data;           
  SacnSourcesLostCallback           sources_lost;            
  SacnSamplingPeriodStartedCallback sampling_period_started; 
  SacnSamplingPeriodEndedCallback   sampling_period_ended;   
  SacnSourcePapLostCallback         source_pap_lost;         
  SacnSourceLimitExceededCallback   source_limit_exceeded;   
  void*                             context; 
} SacnReceiverCallbacks;
 
typedef struct SacnReceiverConfig
{
  /********* Required values **********/
 
  uint16_t universe_id;
  SacnReceiverCallbacks callbacks;
 
  /********* Optional values **********/
 
  SacnRecvUniverseSubrange footprint;
 
  int source_count_max;
  unsigned int flags;
 
  sacn_ip_support_t ip_supported;
} SacnReceiverConfig;
 
#define SACN_RECEIVER_CONFIG_DEFAULT_INIT \
  {0,                                     \
   {NULL, NULL, NULL, NULL, NULL, NULL},  \
   {1, kSacnDmxAddressCount},             \
   kSacnReceiverInfiniteSources,          \
   0,                                     \
   kSacnIpV4AndIpV6}
 
typedef struct SacnReceiverNetintList
{
  sacn_receiver_t handle;
 
  SacnMcastInterface* netints;
  size_t num_netints;
  bool no_netints;
} SacnReceiverNetintList;
 
void sacn_receiver_config_init(SacnReceiverConfig* config);
 
etcpal_error_t sacn_receiver_create(const SacnReceiverConfig* config,
                                    sacn_receiver_t*          handle,
                                    const SacnNetintConfig*   netint_config);
etcpal_error_t sacn_receiver_destroy(sacn_receiver_t handle);
etcpal_error_t sacn_receiver_get_universe(sacn_receiver_t handle, uint16_t* universe_id);
etcpal_error_t sacn_receiver_get_footprint(sacn_receiver_t handle, SacnRecvUniverseSubrange* footprint);
etcpal_error_t sacn_receiver_change_universe(sacn_receiver_t handle, uint16_t new_universe_id);
etcpal_error_t sacn_receiver_change_footprint(sacn_receiver_t handle, const SacnRecvUniverseSubrange* new_footprint);
etcpal_error_t sacn_receiver_change_universe_and_footprint(sacn_receiver_t                 handle,
                                                           uint16_t                        new_universe_id,
                                                           const SacnRecvUniverseSubrange* new_footprint);
etcpal_error_t sacn_receiver_reset_networking(const SacnNetintConfig* sys_netint_config);
etcpal_error_t sacn_receiver_reset_networking_per_receiver(const SacnNetintConfig*       sys_netint_config,
                                                           const SacnReceiverNetintList* per_receiver_netint_lists,
                                                           size_t                        num_per_receiver_netint_lists);
size_t sacn_receiver_get_network_interfaces(sacn_receiver_t handle, EtcPalMcastNetintId* netints, size_t netints_size);
 
void     sacn_receiver_set_expired_wait(uint32_t wait_ms);
uint32_t sacn_receiver_get_expired_wait();
 
#ifdef __cplusplus
}
#endif
 
#endif /* SACN_RECEIVER_H_ */