Asterisk - The Open Source Telephony Project  21.4.1
Data Structures | Macros | Enumerations | Functions | Variables
res_hep.c File Reference

Routines for integration with Homer using HEPv3. More...

#include "asterisk.h"
#include "asterisk/module.h"
#include "asterisk/astobj2.h"
#include "asterisk/config_options.h"
#include "asterisk/taskprocessor.h"
#include "asterisk/res_hep.h"
#include <netinet/ip.h>
#include <netinet/tcp.h>
#include <netinet/udp.h>
#include <netinet/ip6.h>

Go to the source code of this file.

Data Structures

struct  hep_chunk
 
struct  hep_chunk_ip4
 
struct  hep_chunk_ip6
 
struct  hep_chunk_uint16
 
struct  hep_chunk_uint32
 
struct  hep_chunk_uint8
 
struct  hep_ctrl
 
struct  hep_generic
 
struct  hepv3_global_config
 Global configuration for the module. More...
 
struct  hepv3_runtime_data
 Run-time data derived from hepv3_global_config. More...
 
struct  module_config
 The configuration settings for this module. More...
 

Macros

#define ASTERISK_VENDOR_ID   0x0004
 
#define GENERIC_VENDOR_ID   0x0000
 
#define INITIALIZE_GENERIC_HEP_CHUNK(hep_item, type)
 
#define INITIALIZE_GENERIC_HEP_CHUNK_DATA(hep_item, type, value)
 
#define INITIALIZE_GENERIC_HEP_IDS(hep_chunk, type)
 
#define INITIALIZE_GENERIC_HEP_IDS_VAR(hep_chunk, type, len)
 

Enumerations

enum  hepv3_chunk_types {
  CHUNK_TYPE_IP_PROTOCOL_FAMILY = 0X0001, CHUNK_TYPE_IP_PROTOCOL_ID = 0X0002, CHUNK_TYPE_IPV4_SRC_ADDR = 0X0003, CHUNK_TYPE_IPV4_DST_ADDR = 0X0004,
  CHUNK_TYPE_IPV6_SRC_ADDR = 0X0005, CHUNK_TYPE_IPV6_DST_ADDR = 0X0006, CHUNK_TYPE_SRC_PORT = 0X0007, CHUNK_TYPE_DST_PORT = 0X0008,
  CHUNK_TYPE_TIMESTAMP_SEC = 0X0009, CHUNK_TYPE_TIMESTAMP_USEC = 0X000A, CHUNK_TYPE_PROTOCOL_TYPE = 0X000B, CHUNK_TYPE_CAPTURE_AGENT_ID = 0X000C,
  CHUNK_TYPE_KEEP_ALIVE_TIMER = 0X000D, CHUNK_TYPE_AUTH_KEY = 0X000E, CHUNK_TYPE_PAYLOAD = 0X000F, CHUNK_TYPE_PAYLOAD_ZIP = 0X0010,
  CHUNK_TYPE_UUID = 0X0011, CHUNK_TYPE_CAPTURE_AGENT_NAME = 0X0013
}
 

Functions

static void __reg_module (void)
 
static void __unreg_module (void)
 
static AO2_GLOBAL_OBJ_STATIC (global_config)
 The module configuration container.
 
static AO2_GLOBAL_OBJ_STATIC (global_data)
 Current module data.
 
struct ast_moduleAST_MODULE_SELF_SYM (void)
 
static void capture_info_dtor (void *obj)
 Destructor for a hepv3_capture_info object.
 
 CONFIG_INFO_STANDARD (cfg_info, global_config, module_config_alloc,.files=ACO_FILES(&hepv3_conf),.pre_apply_config=hepv3_config_pre_apply,.post_apply_config=hepv3_config_post_apply,)
 Register information about the configs being processed by this module.
 
static int hep_queue_cb (void *data)
 Callback function for the hep_queue_tp taskprocessor.
 
static void * hepv3_config_alloc (void)
 HEPv3 configuration object allocation.
 
static void hepv3_config_dtor (void *obj)
 
static void hepv3_config_post_apply (void)
 Post-apply callback for the config framework. More...
 
static int hepv3_config_pre_apply (void)
 Pre-apply callback for the config framework. More...
 
struct hepv3_capture_infohepv3_create_capture_info (const void *payload, size_t len)
 Create a hepv3_capture_info object. More...
 
static struct hepv3_runtime_datahepv3_data_alloc (struct hepv3_global_config *config)
 Allocate the HEPv3 run-time data.
 
static void hepv3_data_dtor (void *obj)
 HEPv3 run-time data destructor.
 
enum hep_uuid_type hepv3_get_uuid_type (void)
 Get the preferred UUID type. More...
 
int hepv3_is_loaded (void)
 Return whether or not we're currently loaded and active. More...
 
int hepv3_send_packet (struct hepv3_capture_info *capture_info)
 Send a generic packet capture to HEPv3. More...
 
static int load_module (void)
 Load the module.
 
static void * module_config_alloc (void)
 Module config constructor.
 
static void module_config_dtor (void *obj)
 Configuration object destructor.
 
static int reload_module (void)
 Reload the module.
 
static int unload_module (void)
 Unload the module.
 
static int uuid_type_handler (const struct aco_option *opt, struct ast_variable *var, void *obj)
 Handler for the uuid_type attribute.
 

Variables

static struct ast_module_info __mod_info = { .name = AST_MODULE, .flags = AST_MODFLAG_GLOBAL_SYMBOLS | AST_MODFLAG_LOAD_ORDER , .description = "HEPv3 API" , .key = "This paragraph is copyright (c) 2006 by Digium, Inc. \In order for your module to load, it must return this \key via a function called \"key\". Any code which \includes this paragraph must be licensed under the GNU \General Public License version 2 or later (at your \option). In addition to Digium's general reservations \of rights, Digium expressly reserves the right to \allow other parties to license this paragraph under \different terms. Any use of Digium, Inc. trademarks or \logos (including \"Asterisk\" or \"Digium\") without \express written permission of Digium, Inc. is prohibited.\n" , .buildopt_sum = "da6642af068ee5e6490c5b1d2cc1d238" , .support_level = AST_MODULE_SUPPORT_EXTENDED, .load = load_module, .unload = unload_module, .reload = reload_module, .load_pri = AST_MODPRI_APP_DEPEND, }
 
static const struct ast_module_infoast_module_info = &__mod_info
 
static struct aco_type global_option
 
struct aco_typeglobal_options [] = ACO_TYPES(&global_option)
 
static struct ast_taskprocessorhep_queue_tp
 
struct aco_file hepv3_conf
 

Detailed Description

Routines for integration with Homer using HEPv3.

Author
Alexandr Dubovikov alexa.nosp@m.ndr..nosp@m.dubov.nosp@m.ikov.nosp@m.@sipc.nosp@m.aptu.nosp@m.re.or.nosp@m.g
Matt Jordan mjord.nosp@m.an@d.nosp@m.igium.nosp@m..com

Definition in file res_hep.c.

Macro Definition Documentation

#define ASTERISK_VENDOR_ID   0x0004

Asterisk vendor ID. Used for custom data to send to a capture node

Definition at line 106 of file res_hep.c.

#define GENERIC_VENDOR_ID   0x0000

Generic vendor ID. Used for HEPv3 standard packets

Definition at line 103 of file res_hep.c.

#define INITIALIZE_GENERIC_HEP_CHUNK (   hep_item,
  type 
)
Value:
do { \
INITIALIZE_GENERIC_HEP_IDS(&(hep_item)->chunk, (type)); \
(hep_item)->chunk.length = htons(sizeof(*(hep_item))); \
} while (0)

Definition at line 176 of file res_hep.c.

#define INITIALIZE_GENERIC_HEP_CHUNK_DATA (   hep_item,
  type,
  value 
)
Value:
do { \
INITIALIZE_GENERIC_HEP_CHUNK((hep_item), (type)); \
(hep_item)->data = (value); \
} while (0)

Definition at line 181 of file res_hep.c.

#define INITIALIZE_GENERIC_HEP_IDS (   hep_chunk,
  type 
)
Value:
do { \
(hep_chunk)->vendor_id = htons(GENERIC_VENDOR_ID); \
(hep_chunk)->type_id = htons((type)); \
} while (0)
#define GENERIC_VENDOR_ID
Definition: res_hep.c:103

Definition at line 166 of file res_hep.c.

#define INITIALIZE_GENERIC_HEP_IDS_VAR (   hep_chunk,
  type,
  len 
)
Value:
do { \
INITIALIZE_GENERIC_HEP_IDS((hep_chunk), (type)); \
(hep_chunk)->length = htons(sizeof(*(hep_chunk)) + len); \
} while (0)

Definition at line 171 of file res_hep.c.

Enumeration Type Documentation

Chunk types from the HEPv3 Spec

Enumerator
CHUNK_TYPE_IP_PROTOCOL_FAMILY 

THE IP PROTOCOL FAMILY

CHUNK_TYPE_IP_PROTOCOL_ID 

THE IP PROTOCOL ID (UDP, TCP, ETC.)

CHUNK_TYPE_IPV4_SRC_ADDR 

IF IPV4, THE SOURCE ADDRESS

CHUNK_TYPE_IPV4_DST_ADDR 

IF IPV4, THE DESTINATION ADDRESS

CHUNK_TYPE_IPV6_SRC_ADDR 

IF IPV6, THE SOURCE ADDRESS

CHUNK_TYPE_IPV6_DST_ADDR 

IF IPV6, THE DESTINATION ADDRESS

CHUNK_TYPE_SRC_PORT 

THE SOURCE PORT

CHUNK_TYPE_DST_PORT 

THE DESTINATION PORT

CHUNK_TYPE_TIMESTAMP_SEC 

THE CAPTURE TIME (SECONDS)

CHUNK_TYPE_TIMESTAMP_USEC 

THE CAPTURE TIME (MICROSECONDS)

CHUNK_TYPE_PROTOCOL_TYPE 

THE PROTOCOL PACKET TYPE. SEE /REF HEPV3_CAPTURE_TYPE

CHUNK_TYPE_CAPTURE_AGENT_ID 

OUR CAPTURE AGENT ID

CHUNK_TYPE_KEEP_ALIVE_TIMER 

A KEEP ALIVE TIMER

CHUNK_TYPE_AUTH_KEY 

THE CAPTURE_PASSWORD IF DEFINED

CHUNK_TYPE_PAYLOAD 

THE ONE AND ONLY PAYLOAD

CHUNK_TYPE_PAYLOAD_ZIP 

THE ONE AND ONLY (ZIPPED) PAYLOAD

CHUNK_TYPE_UUID 

THE UUID FOR THIS PACKET

CHUNK_TYPE_CAPTURE_AGENT_NAME 

THE CAPTURE AGENT NAME

Definition at line 109 of file res_hep.c.

109  {
110 
111  /*! THE IP PROTOCOL FAMILY */
113 
114  /*! THE IP PROTOCOL ID (UDP, TCP, ETC.) */
115  CHUNK_TYPE_IP_PROTOCOL_ID = 0X0002,
116 
117  /*! IF IPV4, THE SOURCE ADDRESS */
118  CHUNK_TYPE_IPV4_SRC_ADDR = 0X0003,
119 
120  /*! IF IPV4, THE DESTINATION ADDRESS */
121  CHUNK_TYPE_IPV4_DST_ADDR = 0X0004,
122 
123  /*! IF IPV6, THE SOURCE ADDRESS */
124  CHUNK_TYPE_IPV6_SRC_ADDR = 0X0005,
125 
126  /*! IF IPV6, THE DESTINATION ADDRESS */
127  CHUNK_TYPE_IPV6_DST_ADDR = 0X0006,
128 
129  /*! THE SOURCE PORT */
130  CHUNK_TYPE_SRC_PORT = 0X0007,
131 
132  /*! THE DESTINATION PORT */
133  CHUNK_TYPE_DST_PORT = 0X0008,
134 
135  /*! THE CAPTURE TIME (SECONDS) */
136  CHUNK_TYPE_TIMESTAMP_SEC = 0X0009,
137 
138  /*! THE CAPTURE TIME (MICROSECONDS) */
139  CHUNK_TYPE_TIMESTAMP_USEC = 0X000A,
140 
141  /*! THE PROTOCOL PACKET TYPE. SEE /REF HEPV3_CAPTURE_TYPE */
142  CHUNK_TYPE_PROTOCOL_TYPE = 0X000B,
143 
144  /*! OUR CAPTURE AGENT ID */
146 
147  /*! A KEEP ALIVE TIMER */
149 
150  /*! THE CAPTURE_PASSWORD IF DEFINED */
151  CHUNK_TYPE_AUTH_KEY = 0X000E,
152 
153  /*! THE ONE AND ONLY PAYLOAD */
154  CHUNK_TYPE_PAYLOAD = 0X000F,
155 
156  /*! THE ONE AND ONLY (ZIPPED) PAYLOAD */
157  CHUNK_TYPE_PAYLOAD_ZIP = 0X0010,
158 
159  /*! THE UUID FOR THIS PACKET */
160  CHUNK_TYPE_UUID = 0X0011,
161 
162  /*! THE CAPTURE AGENT NAME */
164 };

Function Documentation

static void hepv3_config_post_apply ( void  )
static

Post-apply callback for the config framework.

This will create the run-time information from the supplied configuration.

Definition at line 646 of file res_hep.c.

References ao2_global_obj_ref, ao2_global_obj_replace_unref, ao2_ref, hepv3_data_alloc(), and RAII_VAR.

647 {
648  RAII_VAR(struct module_config *, mod_cfg, ao2_global_obj_ref(global_config), ao2_cleanup);
649  struct hepv3_runtime_data *data;
650 
651  data = hepv3_data_alloc(mod_cfg->general);
652  if (!data) {
653  return;
654  }
655 
656  ao2_global_obj_replace_unref(global_data, data);
657  ao2_ref(data, -1);
658 }
Run-time data derived from hepv3_global_config.
Definition: res_hep.c:259
#define ao2_global_obj_ref(holder)
Get a reference to the object stored in the global holder.
Definition: astobj2.h:918
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
The configuration settings for this module.
Definition: cdr.c:264
static struct hepv3_runtime_data * hepv3_data_alloc(struct hepv3_global_config *config)
Allocate the HEPv3 run-time data.
Definition: res_hep.c:378
#define ao2_global_obj_replace_unref(holder, obj)
Replace an ao2 object in the global holder, throwing away any old object.
Definition: astobj2.h:901
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
static int hepv3_config_pre_apply ( void  )
static

Pre-apply callback for the config framework.

This validates that required fields exist and are populated.

Definition at line 623 of file res_hep.c.

References aco_pending_config(), and module_config::general.

624 {
625  struct module_config *config = aco_pending_config(&cfg_info);
626 
627  if (!config->general->enabled) {
628  /* If we're not enabled, we don't care about anything else */
629  return 0;
630  }
631 
632  if (ast_strlen_zero(config->general->capture_address)) {
633  ast_log(AST_LOG_ERROR, "Missing required configuration option 'capture_address'\n");
634  return -1;
635  }
636 
637  return 0;
638 }
void * aco_pending_config(struct aco_info *info)
Get pending config changes.
The configuration settings for this module.
Definition: cdr.c:264
struct ast_cdr_config * general
Definition: cdr.c:265
struct hepv3_capture_info* hepv3_create_capture_info ( const void *  payload,
size_t  len 
)

Create a hepv3_capture_info object.

This returned object is an ao2 reference counted object.

Any attribute in the returned hepv3_capture_info that is a pointer should point to something that is allocated on the heap, as it will be free'd when the hepv3_capture_info object is reclaimed.

Parameters
payloadThe payload to send to the HEP capture node
lenLength of payload
Returns
A hepv3_capture_info ref counted object on success
Return values
NULLon error

Definition at line 435 of file res_hep.c.

References ao2_ref, ast_malloc, capture_info_dtor(), hepv3_capture_info::len, hepv3_capture_info::payload, and hepv3_capture_info::protocol_id.

436 {
437  struct hepv3_capture_info *info;
438 
439  info = ao2_alloc(sizeof(*info), capture_info_dtor);
440  if (!info) {
441  return NULL;
442  }
443 
444  info->payload = ast_malloc(len);
445  if (!info->payload) {
446  ao2_ref(info, -1);
447  return NULL;
448  }
449  memcpy(info->payload, payload, len);
450  info->len = len;
451 
452  /* Set a reasonable default */
453  info->protocol_id = IPPROTO_UDP;
454 
455  return info;
456 }
HEPv3 Capture Info.
Definition: res_hep.h:57
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ast_malloc(len)
A wrapper for malloc()
Definition: astmm.h:191
static void capture_info_dtor(void *obj)
Destructor for a hepv3_capture_info object.
Definition: res_hep.c:408
void * payload
Definition: res_hep.h:65
enum hep_uuid_type hepv3_get_uuid_type ( void  )

Get the preferred UUID type.

Since
13.10.0
Returns
The type of UUID the packet should use

Definition at line 416 of file res_hep.c.

References ao2_global_obj_ref, and RAII_VAR.

417 {
418  RAII_VAR(struct module_config *, config, ao2_global_obj_ref(global_config), ao2_cleanup);
419 
420  if (!config) {
421  /* Well, that's unfortunate. Return something. */
422  return HEP_UUID_TYPE_CALL_ID;
423  }
424 
425  return config->general->uuid_type;
426 }
#define ao2_global_obj_ref(holder)
Get a reference to the object stored in the global holder.
Definition: astobj2.h:918
The configuration settings for this module.
Definition: cdr.c:264
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
int hepv3_is_loaded ( void  )

Return whether or not we're currently loaded and active.

Return values
0The module is not loaded
1The module is loaded

Definition at line 428 of file res_hep.c.

References ao2_global_obj_ref, and RAII_VAR.

429 {
430  RAII_VAR(struct module_config *, config, ao2_global_obj_ref(global_config), ao2_cleanup);
431 
432  return config && config->general->enabled;
433 }
#define ao2_global_obj_ref(holder)
Get a reference to the object stored in the global holder.
Definition: astobj2.h:918
The configuration settings for this module.
Definition: cdr.c:264
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941
int hepv3_send_packet ( struct hepv3_capture_info capture_info)

Send a generic packet capture to HEPv3.

Parameters
capture_infoInformation describing the packet. This should be a reference counted object, created via hepv3_create_capture_info.

Once this function is called, it assumes ownership of the capture_info object and steals the reference of the object. Regardless of success or failure, the calling function should assumed that this function will own the object.

Return values
0on success
-1on error

Definition at line 600 of file res_hep.c.

References ao2_global_obj_ref, ao2_ref, ast_taskprocessor_push(), hep_queue_cb(), and RAII_VAR.

601 {
602  RAII_VAR(struct module_config *, config, ao2_global_obj_ref(global_config), ao2_cleanup);
603  int res;
604 
605  if (!config || !config->general->enabled) {
606  ao2_ref(capture_info, -1);
607  return 0;
608  }
609 
610  res = ast_taskprocessor_push(hep_queue_tp, hep_queue_cb, capture_info);
611  if (res == -1) {
612  ao2_ref(capture_info, -1);
613  }
614 
615  return res;
616 }
#define ao2_global_obj_ref(holder)
Get a reference to the object stored in the global holder.
Definition: astobj2.h:918
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
The configuration settings for this module.
Definition: cdr.c:264
int ast_taskprocessor_push(struct ast_taskprocessor *tps, int(*task_exe)(void *datap), void *datap) attribute_warn_unused_result
Push a task into the specified taskprocessor queue and signal the taskprocessor thread.
static int hep_queue_cb(void *data)
Callback function for the hep_queue_tp taskprocessor.
Definition: res_hep.c:459
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941

Variable Documentation

struct aco_file hepv3_conf
Initial value:
= {
.filename = "hep.conf",
}
#define ACO_TYPES(...)
A helper macro to ensure that aco_info types always have a sentinel.
static struct aco_type global_option
An aco_type structure to link the "general" category to the skel_global_config type.
Definition: app_skel.c:241

Definition at line 274 of file res_hep.c.