vnfs/VES/code/evel_library/evel.h

   1 #ifndef EVEL_INCLUDED
   2 #define EVEL_INCLUDED
   3 /**************************************************************************//**
   4  * @file
   5  * Header for EVEL library
   6  *
   7  * This file implements the EVEL library which is intended to provide a
   8  * simple wrapper around the complexity of AT&T's Vendor Event Listener API so
   9  * that VNFs can use it without worrying about details of the API transport.
  10  *
  11  * Zero return value is success (::EVEL_SUCCESS), non-zero is failure and will
  12  * be one of ::EVEL_ERR_CODES.
  13  *
  14  * License
  15  * -------
  16  *
  17  * Copyright © 2017 AT&T Intellectual Property. All rights reserved.
  18  *
  19  * Licensed under the Apache License, Version 2.0 (the "License");
  20  * you may not use this file except in compliance with the License.
  21  * You may obtain a copy of the License at
  22  *        http://www.apache.org/licenses/LICENSE-2.0
  23  *
  24  * Unless required by applicable law or agreed to in writing, software
  25  * distributed under the License is distributed on an "AS IS" BASIS,
  26  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  27  * See the License for the specific language governing permissions and
  28  * limitations under the License.
  29  *****************************************************************************/
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #include <stdbool.h>
  36 #include <stdio.h>
  37 #include <stdarg.h>
  38 #include <time.h>
  39
  40 #include "double_list.h"
  41
  42 /*****************************************************************************/
  43 /* Supported API version.                                                    */
  44 /*****************************************************************************/
  45 #define EVEL_API_MAJOR_VERSION 3
  46 #define EVEL_API_MINOR_VERSION 0
  47
  48 /**************************************************************************//**
  49  * Error codes
  50  *
  51  * Error codes for EVEL low level interface
  52  *****************************************************************************/
  53 typedef enum {
  54   EVEL_SUCCESS,                   /** The operation was successful.          */
  55   EVEL_ERR_GEN_FAIL,              /** Non-specific failure.                  */
  56   EVEL_CURL_LIBRARY_FAIL,         /** A cURL library operation failed.       */
  57   EVEL_PTHREAD_LIBRARY_FAIL,      /** A Posix threads operation failed.      */
  58   EVEL_OUT_OF_MEMORY,             /** A memory allocation failure occurred.  */
  59   EVEL_EVENT_BUFFER_FULL,         /** Too many events in the ring-buffer.    */
  60   EVEL_EVENT_HANDLER_INACTIVE,    /** Attempt to raise event when inactive.  */
  61   EVEL_NO_METADATA,               /** Failed to retrieve OpenStack metadata. */
  62   EVEL_BAD_METADATA,              /** OpenStack metadata invalid format.     */
  63   EVEL_BAD_JSON_FORMAT,           /** JSON failed to parse correctly.        */
  64   EVEL_JSON_KEY_NOT_FOUND,        /** Failed to find the specified JSON key. */
  65   EVEL_MAX_ERROR_CODES            /** Maximum number of valid error codes.   */
  66 } EVEL_ERR_CODES;
  67
  68 /**************************************************************************//**
  69  * Logging levels
  70  *
  71  * Variable levels of verbosity in the logging functions.
  72  *****************************************************************************/
  73 typedef enum {
  74   EVEL_LOG_MIN               = 0,
  75   EVEL_LOG_SPAMMY            = 30,
  76   EVEL_LOG_DEBUG             = 40,
  77   EVEL_LOG_INFO              = 50,
  78   EVEL_LOG_ERROR             = 60,
  79   EVEL_LOG_MAX               = 101
  80 } EVEL_LOG_LEVELS;
  81
  82 /*****************************************************************************/
  83 /* Maximum string lengths.                                                   */
  84 /*****************************************************************************/
  85 #define EVEL_MAX_STRING_LEN          4096
  86 #define EVEL_MAX_JSON_BODY           16000
  87 #define EVEL_MAX_ERROR_STRING_LEN    255
  88 #define EVEL_MAX_URL_LEN             511
  89
  90 /**************************************************************************//**
  91  * This value represents there being no restriction on the reporting interval.
  92  *****************************************************************************/
  93 static const int EVEL_MEASUREMENT_INTERVAL_UKNOWN = 0;
  94
  95 /**************************************************************************//**
  96  * How many events can be backed-up before we start dropping events on the
  97  * floor.
  98  *
  99  * @note  This value should be tuned in accordance with expected burstiness of
 100  *        the event load and the expected response time of the ECOMP event
 101  *        listener so that the probability of the buffer filling is suitably
 102  *        low.
 103  *****************************************************************************/
 104 static const int EVEL_EVENT_BUFFER_DEPTH = 100;
 105
 106 /*****************************************************************************/
 107 /* How many different IP Types-of-Service are supported.                     */
 108 /*****************************************************************************/
 109 #define EVEL_TOS_SUPPORTED      256
 110
 111 /**************************************************************************//**
 112  * Event domains for the various events we support.
 113  * JSON equivalent field: domain
 114  *****************************************************************************/
 115 typedef enum {
 116   EVEL_DOMAIN_INTERNAL,       /** Internal event, not for external routing.  */
 117   EVEL_DOMAIN_HEARTBEAT,      /** A Heartbeat event (event header only).     */
 118   EVEL_DOMAIN_FAULT,          /** A Fault event.                             */
 119   EVEL_DOMAIN_MEASUREMENT,    /** A Measurement for VF Scaling event.        */
 120   EVEL_DOMAIN_MOBILE_FLOW,    /** A Mobile Flow event.                       */
 121   EVEL_DOMAIN_REPORT,         /** A Measurement for VF Reporting event.      */
 122   EVEL_DOMAIN_SERVICE,        /** A Service event.                           */
 123   EVEL_DOMAIN_SIGNALING,      /** A Signaling event.                         */
 124   EVEL_DOMAIN_STATE_CHANGE,   /** A State Change event.                      */
 125   EVEL_DOMAIN_SYSLOG,         /** A Syslog event.                            */
 126   EVEL_DOMAIN_OTHER,          /** Another event.                             */
 127   EVEL_MAX_DOMAINS            /** Maximum number of recognized Event types.  */
 128 } EVEL_EVENT_DOMAINS;
 129
 130 /**************************************************************************//**
 131  * Event priorities.
 132  * JSON equivalent field: priority
 133  *****************************************************************************/
 134 typedef enum {
 135   EVEL_PRIORITY_HIGH,
 136   EVEL_PRIORITY_MEDIUM,
 137   EVEL_PRIORITY_NORMAL,
 138   EVEL_PRIORITY_LOW,
 139   EVEL_MAX_PRIORITIES
 140 } EVEL_EVENT_PRIORITIES;
 141
 142 /**************************************************************************//**
 143  * Fault / Threshold severities.
 144  * JSON equivalent field: eventSeverity
 145  *****************************************************************************/
 146 typedef enum {
 147   EVEL_SEVERITY_CRITICAL,
 148   EVEL_SEVERITY_MAJOR,
 149   EVEL_SEVERITY_MINOR,
 150   EVEL_SEVERITY_WARNING,
 151   EVEL_SEVERITY_NORMAL,
 152   EVEL_MAX_SEVERITIES
 153 } EVEL_SEVERITIES;
 154
 155 /**************************************************************************//**
 156  * Fault source types.
 157  * JSON equivalent field: eventSourceType
 158  *****************************************************************************/
 159 typedef enum {
 160   EVEL_SOURCE_OTHER,
 161   EVEL_SOURCE_ROUTER,
 162   EVEL_SOURCE_SWITCH,
 163   EVEL_SOURCE_HOST,
 164   EVEL_SOURCE_CARD,
 165   EVEL_SOURCE_PORT,
 166   EVEL_SOURCE_SLOT_THRESHOLD,
 167   EVEL_SOURCE_PORT_THRESHOLD,
 168   EVEL_SOURCE_VIRTUAL_MACHINE,
 169   EVEL_SOURCE_VIRTUAL_NETWORK_FUNCTION,
 170   /***************************************************************************/
 171   /* START OF VENDOR-SPECIFIC VALUES                                         */
 172   /*                                                                         */
 173   /* Vendor-specific values should be added here, and handled appropriately  */
 174   /* in evel_event.c.                                                        */
 175   /***************************************************************************/
 176
 177   /***************************************************************************/
 178   /* END OF VENDOR-SPECIFIC VALUES                                           */
 179   /***************************************************************************/
 180   EVEL_MAX_SOURCE_TYPES
 181 } EVEL_SOURCE_TYPES;
 182
 183 /**************************************************************************//**
 184  * Fault VNF Status.
 185  * JSON equivalent field: vfStatus
 186  *****************************************************************************/
 187 typedef enum {
 188   EVEL_VF_STATUS_ACTIVE,
 189   EVEL_VF_STATUS_IDLE,
 190   EVEL_VF_STATUS_PREP_TERMINATE,
 191   EVEL_VF_STATUS_READY_TERMINATE,
 192   EVEL_VF_STATUS_REQ_TERMINATE,
 193   EVEL_MAX_VF_STATUSES
 194 } EVEL_VF_STATUSES;
 195
 196 /**************************************************************************//**
 197  * Counter criticalities.
 198  * JSON equivalent field: criticality
 199  *****************************************************************************/
 200 typedef enum {
 201   EVEL_COUNTER_CRITICALITY_CRIT,
 202   EVEL_COUNTER_CRITICALITY_MAJ,
 203   EVEL_MAX_COUNTER_CRITICALITIES
 204 } EVEL_COUNTER_CRITICALITIES;
 205
 206 /**************************************************************************//**
 207  * Alert actions.
 208  * JSON equivalent field: alertAction
 209  *****************************************************************************/
 210 typedef enum {
 211   EVEL_ALERT_ACTION_CLEAR,
 212   EVEL_ALERT_ACTION_CONT,
 213   EVEL_ALERT_ACTION_SET,
 214   EVEL_MAX_ALERT_ACTIONS
 215 } EVEL_ALERT_ACTIONS;
 216
 217 /**************************************************************************//**
 218  * Alert types.
 219  * JSON equivalent field: alertType
 220  *****************************************************************************/
 221 typedef enum {
 222   EVEL_ALERT_TYPE_CARD,
 223   EVEL_ALERT_TYPE_ELEMENT,
 224   EVEL_ALERT_TYPE_INTERFACE,
 225   EVEL_ALERT_TYPE_SERVICE,
 226   EVEL_MAX_ALERT_TYPES
 227 } EVEL_ALERT_TYPES;
 228
 229 /**************************************************************************//**
 230  * Alert types.
 231  * JSON equivalent fields: newState, oldState
 232  *****************************************************************************/
 233 typedef enum {
 234   EVEL_ENTITY_STATE_IN_SERVICE,
 235   EVEL_ENTITY_STATE_MAINTENANCE,
 236   EVEL_ENTITY_STATE_OUT_OF_SERVICE,
 237   EVEL_MAX_ENTITY_STATES
 238 } EVEL_ENTITY_STATE;
 239
 240 /**************************************************************************//**
 241  * Syslog facilities.
 242  * JSON equivalent field: syslogFacility
 243  *****************************************************************************/
 244 typedef enum {
 245   EVEL_SYSLOG_FACILITY_KERNEL,
 246   EVEL_SYSLOG_FACILITY_USER,
 247   EVEL_SYSLOG_FACILITY_MAIL,
 248   EVEL_SYSLOG_FACILITY_SYSTEM_DAEMON,
 249   EVEL_SYSLOG_FACILITY_SECURITY_AUTH,
 250   EVEL_SYSLOG_FACILITY_INTERNAL,
 251   EVEL_SYSLOG_FACILITY_LINE_PRINTER,
 252   EVEL_SYSLOG_FACILITY_NETWORK_NEWS,
 253   EVEL_SYSLOG_FACILITY_UUCP,
 254   EVEL_SYSLOG_FACILITY_CLOCK_DAEMON,
 255   EVEL_SYSLOG_FACILITY_SECURITY_AUTH2,
 256   EVEL_SYSLOG_FACILITY_FTP_DAEMON,
 257   EVEL_SYSLOG_FACILITY_NTP,
 258   EVEL_SYSLOG_FACILITY_LOG_AUDIT,
 259   EVEL_SYSLOG_FACILITY_LOG_ALERT,
 260   EVEL_SYSLOG_FACILITY_CLOCK_DAEMON2,
 261   EVEL_SYSLOG_FACILITY_LOCAL0,
 262   EVEL_SYSLOG_FACILITY_LOCAL1,
 263   EVEL_SYSLOG_FACILITY_LOCAL2,
 264   EVEL_SYSLOG_FACILITY_LOCAL3,
 265   EVEL_SYSLOG_FACILITY_LOCAL4,
 266   EVEL_SYSLOG_FACILITY_LOCAL5,
 267   EVEL_SYSLOG_FACILITY_LOCAL6,
 268   EVEL_SYSLOG_FACILITY_LOCAL7,
 269   EVEL_MAX_SYSLOG_FACILITIES
 270 } EVEL_SYSLOG_FACILITIES;
 271
 272 /**************************************************************************//**
 273  * TCP flags.
 274  * JSON equivalent fields: tcpFlagCountList, tcpFlagList
 275  *****************************************************************************/
 276 typedef enum {
 277   EVEL_TCP_NS,
 278   EVEL_TCP_CWR,
 279   EVEL_TCP_ECE,
 280   EVEL_TCP_URG,
 281   EVEL_TCP_ACK,
 282   EVEL_TCP_PSH,
 283   EVEL_TCP_RST,
 284   EVEL_TCP_SYN,
 285   EVEL_TCP_FIN,
 286   EVEL_MAX_TCP_FLAGS
 287 } EVEL_TCP_FLAGS;
 288
 289 /**************************************************************************//**
 290  * Mobile QCI Classes of Service.
 291  * JSON equivalent fields: mobileQciCosCountList, mobileQciCosList
 292  *****************************************************************************/
 293 typedef enum {
 294
 295   /***************************************************************************/
 296   /* UMTS Classes of Service.                                                */
 297   /***************************************************************************/
 298   EVEL_QCI_COS_UMTS_CONVERSATIONAL,
 299   EVEL_QCI_COS_UMTS_STREAMING,
 300   EVEL_QCI_COS_UMTS_INTERACTIVE,
 301   EVEL_QCI_COS_UMTS_BACKGROUND,
 302
 303   /***************************************************************************/
 304   /* LTE Classes of Service.                                                 */
 305   /***************************************************************************/
 306   EVEL_QCI_COS_LTE_1,
 307   EVEL_QCI_COS_LTE_2,
 308   EVEL_QCI_COS_LTE_3,
 309   EVEL_QCI_COS_LTE_4,
 310   EVEL_QCI_COS_LTE_65,
 311   EVEL_QCI_COS_LTE_66,
 312   EVEL_QCI_COS_LTE_5,
 313   EVEL_QCI_COS_LTE_6,
 314   EVEL_QCI_COS_LTE_7,
 315   EVEL_QCI_COS_LTE_8,
 316   EVEL_QCI_COS_LTE_9,
 317   EVEL_QCI_COS_LTE_69,
 318   EVEL_QCI_COS_LTE_70,
 319   EVEL_MAX_QCI_COS_TYPES
 320 } EVEL_QCI_COS_TYPES;
 321
 322 /**************************************************************************//**
 323  * Service Event endpoint description
 324  * JSON equivalent field: endpointDesc
 325  *****************************************************************************/
 326 typedef enum {
 327   EVEL_SERVICE_ENDPOINT_CALLEE,
 328   EVEL_SERVICE_ENDPOINT_CALLER,
 329   EVEL_MAX_SERVICE_ENDPOINT_DESC
 330 } EVEL_SERVICE_ENDPOINT_DESC;
 331
 332 /**************************************************************************//**
 333  * Boolean type for EVEL library.
 334  *****************************************************************************/
 335 typedef enum {
 336   EVEL_FALSE,
 337   EVEL_TRUE
 338 } EVEL_BOOLEAN;
 339
 340 /**************************************************************************//**
 341  * Optional parameter holder for double.
 342  *****************************************************************************/
 343 typedef struct evel_option_double
 344 {
 345   double value;
 346   EVEL_BOOLEAN is_set;
 347 } EVEL_OPTION_DOUBLE;
 348
 349 /**************************************************************************//**
 350  * Optional parameter holder for string.
 351  *****************************************************************************/
 352 typedef struct evel_option_string
 353 {
 354   char * value;
 355   EVEL_BOOLEAN is_set;
 356 } EVEL_OPTION_STRING;
 357
 358 /**************************************************************************//**
 359  * Optional parameter holder for int.
 360  *****************************************************************************/
 361 typedef struct evel_option_int
 362 {
 363   int value;
 364   EVEL_BOOLEAN is_set;
 365 } EVEL_OPTION_INT;
 366
 367 /**************************************************************************//**
 368  * Optional parameter holder for unsigned long long.
 369  *****************************************************************************/
 370 typedef struct evel_option_ull
 371 {
 372   unsigned long long value;
 373   EVEL_BOOLEAN is_set;
 374 } EVEL_OPTION_ULL;
 375
 376 /**************************************************************************//**
 377  * Optional parameter holder for time_t.
 378  *****************************************************************************/
 379 typedef struct evel_option_time
 380 {
 381   time_t value;
 382   EVEL_BOOLEAN is_set;
 383 } EVEL_OPTION_TIME;
 384
 385 /*****************************************************************************/
 386 /* Supported Common Event Header version.                                    */
 387 /*****************************************************************************/
 388 #define EVEL_HEADER_MAJOR_VERSION 1
 389 #define EVEL_HEADER_MINOR_VERSION 2
 390
 391 /**************************************************************************//**
 392  * Event header.
 393  * JSON equivalent field: commonEventHeader
 394  *****************************************************************************/
 395 typedef struct event_header {
 396   /***************************************************************************/
 397   /* Version                                                                 */
 398   /***************************************************************************/
 399   int major_version;
 400   int minor_version;
 401
 402   /***************************************************************************/
 403   /* Mandatory fields                                                        */
 404   /***************************************************************************/
 405   EVEL_EVENT_DOMAINS event_domain;
 406   char * event_id;
 407   char * source_name;
 408   char * functional_role;
 409   char * reporting_entity_name;
 410   EVEL_EVENT_PRIORITIES priority;
 411   unsigned long long start_epoch_microsec;
 412   unsigned long long last_epoch_microsec;
 413   int sequence;
 414
 415   /***************************************************************************/
 416   /* Optional fields                                                         */
 417   /***************************************************************************/
 418   EVEL_OPTION_STRING event_type;
 419   EVEL_OPTION_STRING source_id;
 420   EVEL_OPTION_STRING reporting_entity_id;
 421
 422 } EVENT_HEADER;
 423
 424 /*****************************************************************************/
 425 /* Supported Fault version.                                                  */
 426 /*****************************************************************************/
 427 #define EVEL_FAULT_MAJOR_VERSION 1
 428 #define EVEL_FAULT_MINOR_VERSION 1
 429
 430 /**************************************************************************//**
 431  * Fault.
 432  * JSON equivalent field: faultFields
 433  *****************************************************************************/
 434 typedef struct event_fault {
 435   /***************************************************************************/
 436   /* Header and version                                                      */
 437   /***************************************************************************/
 438   EVENT_HEADER header;
 439   int major_version;
 440   int minor_version;
 441
 442   /***************************************************************************/
 443   /* Mandatory fields                                                        */
 444   /***************************************************************************/
 445   EVEL_SEVERITIES event_severity;
 446   EVEL_SOURCE_TYPES event_source_type;
 447   char * alarm_condition;
 448   char * specific_problem;
 449   EVEL_VF_STATUSES vf_status;
 450
 451   /***************************************************************************/
 452   /* Optional fields                                                         */
 453   /***************************************************************************/
 454   EVEL_OPTION_STRING alarm_interface_a;
 455   DLIST additional_info;
 456
 457 } EVENT_FAULT;
 458
 459 /**************************************************************************//**
 460  * Fault Additional Info.
 461  * JSON equivalent field: alarmAdditionalInformation
 462  *****************************************************************************/
 463 typedef struct fault_additional_info {
 464   char * name;
 465   char * value;
 466 } FAULT_ADDL_INFO;
 467
 468 /*****************************************************************************/
 469 /* Supported Measurement version.                                            */
 470 /*****************************************************************************/
 471 #define EVEL_MEASUREMENT_MAJOR_VERSION 1
 472 #define EVEL_MEASUREMENT_MINOR_VERSION 1
 473
 474 /**************************************************************************//**
 475  * Errors.
 476  * JSON equivalent field: errors
 477  *****************************************************************************/
 478 typedef struct measurement_errors {
 479   int receive_discards;
 480   int receive_errors;
 481   int transmit_discards;
 482   int transmit_errors;
 483 } MEASUREMENT_ERRORS;
 484
 485 /**************************************************************************//**
 486  * Measurement.
 487  * JSON equivalent field: measurementsForVfScalingFields
 488  *****************************************************************************/
 489 typedef struct event_measurement {
 490   /***************************************************************************/
 491   /* Header and version                                                      */
 492   /***************************************************************************/
 493   EVENT_HEADER header;
 494   int major_version;
 495   int minor_version;
 496
 497   /***************************************************************************/
 498   /* Mandatory fields                                                        */
 499   /***************************************************************************/
 500   double measurement_interval;
 501
 502   /***************************************************************************/
 503   /* Optional fields                                                         */
 504   /***************************************************************************/
 505   DLIST additional_measurements;
 506   EVEL_OPTION_DOUBLE aggregate_cpu_usage;
 507   DLIST codec_usage;
 508   EVEL_OPTION_INT concurrent_sessions;
 509   EVEL_OPTION_INT configured_entities;
 510   DLIST cpu_usage;
 511   MEASUREMENT_ERRORS * errors;
 512   DLIST feature_usage;
 513   DLIST filesystem_usage;
 514   DLIST latency_distribution;
 515   EVEL_OPTION_DOUBLE mean_request_latency;
 516   EVEL_OPTION_DOUBLE memory_configured;
 517   EVEL_OPTION_DOUBLE memory_used;
 518   EVEL_OPTION_INT media_ports_in_use;
 519   EVEL_OPTION_INT request_rate;
 520   EVEL_OPTION_DOUBLE vnfc_scaling_metric;
 521   DLIST vnic_usage;
 522
 523 } EVENT_MEASUREMENT;
 524
 525 /**************************************************************************//**
 526  * CPU Usage.
 527  * JSON equivalent field: cpuUsage
 528  *****************************************************************************/
 529 typedef struct measurement_cpu_use {
 530   char * id;
 531   double usage;
 532 } MEASUREMENT_CPU_USE;
 533
 534 /**************************************************************************//**
 535  * Filesystem Usage.
 536  * JSON equivalent field: filesystemUsage
 537  *****************************************************************************/
 538 typedef struct measurement_fsys_use {
 539   char * filesystem_name;
 540   double block_configured;
 541   int block_iops;
 542   double block_used;
 543   double ephemeral_configured;
 544   int ephemeral_iops;
 545   double ephemeral_used;
 546 } MEASUREMENT_FSYS_USE;
 547
 548 /**************************************************************************//**
 549  * Latency Bucket.
 550  * JSON equivalent field: latencyBucketMeasure
 551  *****************************************************************************/
 552 typedef struct measurement_latency_bucket {
 553   int count;
 554
 555   /***************************************************************************/
 556   /* Optional fields                                                         */
 557   /***************************************************************************/
 558   EVEL_OPTION_DOUBLE high_end;
 559   EVEL_OPTION_DOUBLE low_end;
 560
 561 } MEASUREMENT_LATENCY_BUCKET;
 562
 563 /**************************************************************************//**
 564  * Virtual NIC usage.
 565  * JSON equivalent field: vNicUsage
 566  *****************************************************************************/
 567 typedef struct measurement_vnic_use {
 568   int bytes_in;
 569   int bytes_out;
 570   int packets_in;
 571   int packets_out;
 572   char * vnic_id;
 573
 574   /***************************************************************************/
 575   /* Optional fields                                                         */
 576   /***************************************************************************/
 577   EVEL_OPTION_INT broadcast_packets_in;
 578   EVEL_OPTION_INT broadcast_packets_out;
 579   EVEL_OPTION_INT multicast_packets_in;
 580   EVEL_OPTION_INT multicast_packets_out;
 581   EVEL_OPTION_INT unicast_packets_in;
 582   EVEL_OPTION_INT unicast_packets_out;
 583
 584 } MEASUREMENT_VNIC_USE;
 585
 586 /**************************************************************************//**
 587  * Codec Usage.
 588  * JSON equivalent field: codecsInUse
 589  *****************************************************************************/
 590 typedef struct measurement_codec_use {
 591   char * codec_id;
 592   int number_in_use;
 593 } MEASUREMENT_CODEC_USE;
 594
 595 /**************************************************************************//**
 596  * Feature Usage.
 597  * JSON equivalent field: featuresInUse
 598  *****************************************************************************/
 599 typedef struct measurement_feature_use {
 600   char * feature_id;
 601   int feature_utilization;
 602 } MEASUREMENT_FEATURE_USE;
 603
 604 /**************************************************************************//**
 605  * Measurement Group.
 606  * JSON equivalent field: additionalMeasurements
 607  *****************************************************************************/
 608 typedef struct measurement_group {
 609   char * name;
 610   DLIST measurements;
 611 } MEASUREMENT_GROUP;
 612
 613 /**************************************************************************//**
 614  * Custom Defined Measurement.
 615  * JSON equivalent field: measurements
 616  *****************************************************************************/
 617 typedef struct custom_measurement {
 618   char * name;
 619   char * value;
 620 } CUSTOM_MEASUREMENT;
 621
 622 /*****************************************************************************/
 623 /* Supported Report version.                                                 */
 624 /*****************************************************************************/
 625 #define EVEL_REPORT_MAJOR_VERSION 1
 626 #define EVEL_REPORT_MINOR_VERSION 1
 627
 628 /**************************************************************************//**
 629  * Report.
 630  * JSON equivalent field: measurementsForVfReportingFields
 631  *
 632  * @note  This is an experimental event type and is not currently a formal part
 633  *        of AT&T's specification.
 634  *****************************************************************************/
 635 typedef struct event_report {
 636   /***************************************************************************/
 637   /* Header and version                                                      */
 638   /***************************************************************************/
 639   EVENT_HEADER header;
 640   int major_version;
 641   int minor_version;
 642
 643   /***************************************************************************/
 644   /* Mandatory fields                                                        */
 645   /***************************************************************************/
 646   double measurement_interval;
 647
 648   /***************************************************************************/
 649   /* Optional fields                                                         */
 650   /***************************************************************************/
 651   DLIST feature_usage;
 652   DLIST measurement_groups;
 653
 654 } EVENT_REPORT;
 655
 656 /**************************************************************************//**
 657  * Mobile GTP Per Flow Metrics.
 658  * JSON equivalent field: gtpPerFlowMetrics
 659  *****************************************************************************/
 660 typedef struct mobile_gtp_per_flow_metrics {
 661   double avg_bit_error_rate;
 662   double avg_packet_delay_variation;
 663   int avg_packet_latency;
 664   int avg_receive_throughput;
 665   int avg_transmit_throughput;
 666   int flow_activation_epoch;
 667   int flow_activation_microsec;
 668   int flow_deactivation_epoch;
 669   int flow_deactivation_microsec;
 670   time_t flow_deactivation_time;
 671   char * flow_status;
 672   int max_packet_delay_variation;
 673   int num_activation_failures;
 674   int num_bit_errors;
 675   int num_bytes_received;
 676   int num_bytes_transmitted;
 677   int num_dropped_packets;
 678   int num_l7_bytes_received;
 679   int num_l7_bytes_transmitted;
 680   int num_lost_packets;
 681   int num_out_of_order_packets;
 682   int num_packet_errors;
 683   int num_packets_received_excl_retrans;
 684   int num_packets_received_incl_retrans;
 685   int num_packets_transmitted_incl_retrans;
 686   int num_retries;
 687   int num_timeouts;
 688   int num_tunneled_l7_bytes_received;
 689   int round_trip_time;
 690   int time_to_first_byte;
 691
 692   /***************************************************************************/
 693   /* Optional fields                                                         */
 694   /***************************************************************************/
 695   EVEL_OPTION_INT ip_tos_counts[EVEL_TOS_SUPPORTED];
 696   EVEL_OPTION_INT tcp_flag_counts[EVEL_MAX_TCP_FLAGS];
 697   EVEL_OPTION_INT qci_cos_counts[EVEL_MAX_QCI_COS_TYPES];
 698   EVEL_OPTION_INT dur_connection_failed_status;
 699   EVEL_OPTION_INT dur_tunnel_failed_status;
 700   EVEL_OPTION_STRING flow_activated_by;
 701   EVEL_OPTION_TIME flow_activation_time;
 702   EVEL_OPTION_STRING flow_deactivated_by;
 703   EVEL_OPTION_STRING gtp_connection_status;
 704   EVEL_OPTION_STRING gtp_tunnel_status;
 705   EVEL_OPTION_INT large_packet_rtt;
 706   EVEL_OPTION_DOUBLE large_packet_threshold;
 707   EVEL_OPTION_INT max_receive_bit_rate;
 708   EVEL_OPTION_INT max_transmit_bit_rate;
 709   EVEL_OPTION_INT num_gtp_echo_failures;
 710   EVEL_OPTION_INT num_gtp_tunnel_errors;
 711   EVEL_OPTION_INT num_http_errors;
 712
 713 } MOBILE_GTP_PER_FLOW_METRICS;
 714
 715 /*****************************************************************************/
 716 /* Supported Mobile Flow version.                                            */
 717 /*****************************************************************************/
 718 #define EVEL_MOBILE_FLOW_MAJOR_VERSION 1
 719 #define EVEL_MOBILE_FLOW_MINOR_VERSION 1
 720
 721 /**************************************************************************//**
 722  * Mobile Flow.
 723  * JSON equivalent field: mobileFlow
 724  *****************************************************************************/
 725 typedef struct event_mobile_flow {
 726   /***************************************************************************/
 727   /* Header and version                                                      */
 728   /***************************************************************************/
 729   EVENT_HEADER header;
 730   int major_version;
 731   int minor_version;
 732
 733   /***************************************************************************/
 734   /* Mandatory fields                                                        */
 735   /***************************************************************************/
 736   char * flow_direction;
 737   MOBILE_GTP_PER_FLOW_METRICS * gtp_per_flow_metrics;
 738   char * ip_protocol_type;
 739   char * ip_version;
 740   char * other_endpoint_ip_address;
 741   int other_endpoint_port;
 742   char * reporting_endpoint_ip_addr;
 743   int reporting_endpoint_port;
 744
 745   /***************************************************************************/
 746   /* Optional fields                                                         */
 747   /***************************************************************************/
 748   EVEL_OPTION_STRING application_type;
 749   EVEL_OPTION_STRING app_protocol_type;
 750   EVEL_OPTION_STRING app_protocol_version;
 751   EVEL_OPTION_STRING cid;
 752   EVEL_OPTION_STRING connection_type;
 753   EVEL_OPTION_STRING ecgi;
 754   EVEL_OPTION_STRING gtp_protocol_type;
 755   EVEL_OPTION_STRING gtp_version;
 756   EVEL_OPTION_STRING http_header;
 757   EVEL_OPTION_STRING imei;
 758   EVEL_OPTION_STRING imsi;
 759   EVEL_OPTION_STRING lac;
 760   EVEL_OPTION_STRING mcc;
 761   EVEL_OPTION_STRING mnc;
 762   EVEL_OPTION_STRING msisdn;
 763   EVEL_OPTION_STRING other_functional_role;
 764   EVEL_OPTION_STRING rac;
 765   EVEL_OPTION_STRING radio_access_technology;
 766   EVEL_OPTION_STRING sac;
 767   EVEL_OPTION_INT sampling_algorithm;
 768   EVEL_OPTION_STRING tac;
 769   EVEL_OPTION_STRING tunnel_id;
 770   EVEL_OPTION_STRING vlan_id;
 771
 772 } EVENT_MOBILE_FLOW;
 773
 774 /**************************************************************************//**
 775  * Other.
 776  * JSON equivalent field: otherFields
 777  *****************************************************************************/
 778 typedef struct event_other {
 779   EVENT_HEADER header;
 780   DLIST other_fields;
 781
 782 } EVENT_OTHER;
 783
 784 /**************************************************************************//**
 785  * Other Field.
 786  * JSON equivalent field: otherFields
 787  *****************************************************************************/
 788 typedef struct other_field {
 789   char * name;
 790   char * value;
 791 } OTHER_FIELD;
 792
 793 /**************************************************************************//**
 794  * Event Instance Identifier
 795  * JSON equivalent field: eventInstanceIdentifier
 796  *****************************************************************************/
 797 typedef struct evel_event_instance_id {
 798
 799   /***************************************************************************/
 800   /* Mandatory fields                                                        */
 801   /***************************************************************************/
 802   char * vendor_id;                                        /* JSON: vendorId */
 803   char * event_id;                                          /* JSON: eventId */
 804
 805   /***************************************************************************/
 806   /* Optional fields                                                         */
 807   /***************************************************************************/
 808   EVEL_OPTION_STRING product_id;                          /* JSON: productId */
 809   EVEL_OPTION_STRING subsystem_id;                      /* JSON: subsystemId */
 810   EVEL_OPTION_STRING event_friendly_name;         /* JSON: eventFriendlyName */
 811
 812 } EVEL_EVENT_INSTANCE_ID;
 813
 814 /*****************************************************************************/
 815 /* Supported Service Events version.                                         */
 816 /*****************************************************************************/
 817 #define EVEL_SERVICE_MAJOR_VERSION 1
 818 #define EVEL_SERVICE_MINOR_VERSION 1
 819
 820 /**************************************************************************//**
 821  * Service Events.
 822  * JSON equivalent field: serviceEventsFields
 823  *****************************************************************************/
 824 typedef struct event_service {
 825   /***************************************************************************/
 826   /* Header and version                                                      */
 827   /***************************************************************************/
 828   EVENT_HEADER header;
 829   int major_version;
 830   int minor_version;
 831
 832   /***************************************************************************/
 833   /* Mandatory fields                                                        */
 834   /***************************************************************************/
 835   EVEL_EVENT_INSTANCE_ID instance_id;       /* JSON: eventInstanceIdentifier */
 836
 837   /***************************************************************************/
 838   /* Optional fields.                                                        */
 839   /***************************************************************************/
 840   EVEL_OPTION_STRING correlator;                         /* JSON: correlator */
 841   DLIST additional_fields;                         /* JSON: additionalFields */
 842
 843   /***************************************************************************/
 844   /* Optional fields within JSON equivalent object: codecSelected            */
 845   /***************************************************************************/
 846   EVEL_OPTION_STRING codec;                                   /* JSON: codec */
 847
 848   /***************************************************************************/
 849   /* Optional fields within JSON equivalent object: codecSelectedTranscoding */
 850   /***************************************************************************/
 851   EVEL_OPTION_STRING callee_side_codec;             /* JSON: calleeSideCodec */
 852   EVEL_OPTION_STRING caller_side_codec;             /* JSON: callerSideCodec */
 853
 854   /***************************************************************************/
 855   /* Optional fields within JSON equivalent object: midCallRtcp              */
 856   /***************************************************************************/
 857   EVEL_OPTION_STRING rtcp_data;                            /* JSON: rtcpData */
 858
 859   /***************************************************************************/
 860   /* Optional fields within JSON equivalent object: endOfCallVqmSummaries    */
 861   /***************************************************************************/
 862   EVEL_OPTION_STRING adjacency_name;                  /* JSON: adjacencyName */
 863   EVEL_OPTION_STRING endpoint_description;      /* JSON: endpointDescription */
 864   EVEL_OPTION_INT endpoint_jitter;                   /* JSON: endpointJitter */
 865   EVEL_OPTION_INT endpoint_rtp_oct_disc; /* JSON: endpointRtpOctetsDiscarded */
 866   EVEL_OPTION_INT endpoint_rtp_oct_recv;  /* JSON: endpointRtpOctetsReceived */
 867   EVEL_OPTION_INT endpoint_rtp_oct_sent;      /* JSON: endpointRtpOctetsSent */
 868   EVEL_OPTION_INT endpoint_rtp_pkt_disc;/* JSON: endpointRtpPacketsDiscarded */
 869   EVEL_OPTION_INT endpoint_rtp_pkt_recv; /* JSON: endpointRtpPacketsReceived */
 870   EVEL_OPTION_INT endpoint_rtp_pkt_sent;     /* JSON: endpointRtpPacketsSent */
 871   EVEL_OPTION_INT local_jitter;                         /* JSON: localJitter */
 872   EVEL_OPTION_INT local_rtp_oct_disc;       /* JSON: localRtpOctetsDiscarded */
 873   EVEL_OPTION_INT local_rtp_oct_recv;        /* JSON: localRtpOctetsReceived */
 874   EVEL_OPTION_INT local_rtp_oct_sent;            /* JSON: localRtpOctetsSent */
 875   EVEL_OPTION_INT local_rtp_pkt_disc;      /* JSON: localRtpPacketsDiscarded */
 876   EVEL_OPTION_INT local_rtp_pkt_recv;       /* JSON: localRtpPacketsReceived */
 877   EVEL_OPTION_INT local_rtp_pkt_sent;           /* JSON: localRtpPacketsSent */
 878   EVEL_OPTION_DOUBLE mos_cqe;                                /* JSON: mosCqe */
 879   EVEL_OPTION_INT packets_lost;                         /* JSON: packetsLost */
 880   EVEL_OPTION_DOUBLE packet_loss_percent;         /* JSON: packetLossPercent */
 881   EVEL_OPTION_INT r_factor;                                 /* JSON: rFactor */
 882   EVEL_OPTION_INT round_trip_delay;                  /* JSON: roundTripDelay */
 883
 884   /***************************************************************************/
 885   /* Optional fields within JSON equivalent object: marker                   */
 886   /***************************************************************************/
 887   EVEL_OPTION_STRING phone_number;                      /* JSON: phoneNumber */
 888
 889 } EVENT_SERVICE;
 890
 891 /*****************************************************************************/
 892 /* Supported Signaling version.                                              */
 893 /*****************************************************************************/
 894 #define EVEL_SIGNALING_MAJOR_VERSION 1
 895 #define EVEL_SIGNALING_MINOR_VERSION 1
 896
 897 /**************************************************************************//**
 898  * Signaling.
 899  * JSON equivalent field: signalingFields
 900  *****************************************************************************/
 901 typedef struct event_signaling {
 902   /***************************************************************************/
 903   /* Header and version                                                      */
 904   /***************************************************************************/
 905   EVENT_HEADER header;
 906   int major_version;
 907   int minor_version;
 908
 909   /***************************************************************************/
 910   /* Mandatory fields                                                        */
 911   /***************************************************************************/
 912   EVEL_EVENT_INSTANCE_ID instance_id;       /* JSON: eventInstanceIdentifier */
 913
 914   /***************************************************************************/
 915   /* Optional fields                                                         */
 916   /***************************************************************************/
 917   EVEL_OPTION_STRING correlator;                         /* JSON: correlator */
 918   EVEL_OPTION_STRING local_ip_address;               /* JSON: localIpAddress */
 919   EVEL_OPTION_STRING local_port;                          /* JSON: localPort */
 920   EVEL_OPTION_STRING remote_ip_address;             /* JSON: remoteIpAddress */
 921   EVEL_OPTION_STRING remote_port;                        /* JSON: remotePort */
 922   EVEL_OPTION_STRING compressed_sip;                  /* JSON: compressedSip */
 923   EVEL_OPTION_STRING summary_sip;                        /* JSON: summarySip */
 924
 925 } EVENT_SIGNALING;
 926
 927 /*****************************************************************************/
 928 /* Supported State Change version.                                           */
 929 /*****************************************************************************/
 930 #define EVEL_STATE_CHANGE_MAJOR_VERSION 1
 931 #define EVEL_STATE_CHANGE_MINOR_VERSION 1
 932
 933 /**************************************************************************//**
 934  * State Change.
 935  * JSON equivalent field: stateChangeFields
 936  *****************************************************************************/
 937 typedef struct event_state_change {
 938   /***************************************************************************/
 939   /* Header and version                                                      */
 940   /***************************************************************************/
 941   EVENT_HEADER header;
 942   int major_version;
 943   int minor_version;
 944
 945   /***************************************************************************/
 946   /* Mandatory fields                                                        */
 947   /***************************************************************************/
 948   EVEL_ENTITY_STATE new_state;
 949   EVEL_ENTITY_STATE old_state;
 950   char * state_interface;
 951
 952   /***************************************************************************/
 953   /* Optional fields                                                         */
 954   /***************************************************************************/
 955   DLIST additional_fields;
 956
 957 } EVENT_STATE_CHANGE;
 958
 959 /**************************************************************************//**
 960  * State Change Additional Field.
 961  * JSON equivalent field: additionalFields
 962  *****************************************************************************/
 963 typedef struct state_change_additional_field {
 964   char * name;
 965   char * value;
 966 } STATE_CHANGE_ADDL_FIELD;
 967
 968 /*****************************************************************************/
 969 /* Supported Syslog version.                                                 */
 970 /*****************************************************************************/
 971 #define EVEL_SYSLOG_MAJOR_VERSION 1
 972 #define EVEL_SYSLOG_MINOR_VERSION 1
 973
 974 /**************************************************************************//**
 975  * Syslog.
 976  * JSON equivalent field: syslogFields
 977  *****************************************************************************/
 978 typedef struct event_syslog {
 979   /***************************************************************************/
 980   /* Header and version                                                      */
 981   /***************************************************************************/
 982   EVENT_HEADER header;
 983   int major_version;
 984   int minor_version;
 985
 986   /***************************************************************************/
 987   /* Mandatory fields                                                        */
 988   /***************************************************************************/
 989   EVEL_SOURCE_TYPES event_source_type;
 990   char * syslog_msg;
 991   char * syslog_tag;
 992
 993   /***************************************************************************/
 994   /* Optional fields                                                         */
 995   /***************************************************************************/
 996   DLIST additional_fields;
 997   EVEL_OPTION_STRING event_source_host;
 998   EVEL_OPTION_INT syslog_facility;
 999   EVEL_OPTION_STRING syslog_proc;
1000   EVEL_OPTION_INT syslog_proc_id;
1001   EVEL_OPTION_STRING syslog_s_data;
1002   EVEL_OPTION_INT syslog_ver;
1003
1004 } EVENT_SYSLOG;
1005
1006 /**************************************************************************//**
1007  * Syslog Additional Field.
1008  * JSON equivalent field: additionalFields
1009  *****************************************************************************/
1010 typedef struct syslog_additional_field {
1011   char * name;
1012   char * value;
1013 } SYSLOG_ADDL_FIELD;
1014
1015 /**************************************************************************//**
1016  * Copyright.
1017  * JSON equivalent object: attCopyrightNotice
1018  *****************************************************************************/
1019 typedef struct copyright {
1020   char * useAndRedistribution;
1021   char * condition1;
1022   char * condition2;
1023   char * condition3;
1024   char * condition4;
1025   char * disclaimerLine1;
1026   char * disclaimerLine2;
1027   char * disclaimerLine3;
1028   char * disclaimerLine4;
1029 } COPYRIGHT;
1030
1031 /**************************************************************************//**
1032  * Library initialization.
1033  *
1034  * Initialize the EVEL library.
1035  *
1036  * @note  This function initializes the cURL library.  Applications making use
1037  *        of libcurl may need to pull the initialization out of here.  Note
1038  *        also that this function is not threadsafe as a result - refer to
1039  *        libcurl's API documentation for relevant warnings.
1040  *
1041  * @sa  Matching Term function.
1042  *
1043  * @param   fqdn    The API's FQDN or IP address.
1044  * @param   port    The API's port.
1045  * @param   path    The optional path (may be NULL).
1046  * @param   topic   The optional topic part of the URL (may be NULL).
1047  * @param   secure  Whether to use HTTPS (0=HTTP, 1=HTTPS).
1048  * @param   username  Username for Basic Authentication of requests.
1049  * @param   password  Password for Basic Authentication of requests.
1050  * @param   source_type The kind of node we represent.
1051  * @param   role    The role this node undertakes.
1052  * @param   verbosity  0 for normal operation, positive values for chattier
1053  *                     logs.
1054  *
1055  * @returns Status code
1056  * @retval  EVEL_SUCCESS      On success
1057  * @retval  ::EVEL_ERR_CODES  On failure.
1058  *****************************************************************************/
1059 EVEL_ERR_CODES evel_initialize(const char * const fqdn,
1060                                int port,
1061                                const char * const path,
1062                                const char * const topic,
1063                                int secure,
1064                                const char * const username,
1065                                const char * const password,
1066                                EVEL_SOURCE_TYPES source_type,
1067                                const char * const role,
1068                                int verbosity
1069                                );
1070
1071 /**************************************************************************//**
1072  * Clean up the EVEL library.
1073  *
1074  * @note that at present don't expect Init/Term cycling not to leak memory!
1075  *
1076  * @returns Status code
1077  * @retval  EVEL_SUCCESS On success
1078  * @retval  "One of ::EVEL_ERR_CODES" On failure.
1079  *****************************************************************************/
1080 EVEL_ERR_CODES evel_terminate(void);
1081
1082 EVEL_ERR_CODES evel_post_event(EVENT_HEADER * event);
1083 const char * evel_error_string(void);
1084
1085
1086 /**************************************************************************//**
1087  * Free an event.
1088  *
1089  * Free off the event supplied.  Will free all the contained allocated memory.
1090  *
1091  * @note  It is safe to free a NULL pointer.
1092  *****************************************************************************/
1093 void evel_free_event(void * event);
1094
1095 /**************************************************************************//**
1096  * Encode the event as a JSON event object according to AT&T's schema.
1097  *
1098  * @param json      Pointer to where to store the JSON encoded data.
1099  * @param max_size  Size of storage available in json_body.
1100  * @param event     Pointer to the ::EVENT_HEADER to encode.
1101  * @returns Number of bytes actually written.
1102  *****************************************************************************/
1103 int evel_json_encode_event(char * json,
1104                            int max_size,
1105                            EVENT_HEADER * event);
1106
1107 /**************************************************************************//**
1108  * Callback function to provide returned data.
1109  *
1110  * Copy data into the supplied buffer, write_callback::ptr, checking size
1111  * limits.
1112  *
1113  * @returns   Number of bytes placed into write_callback::ptr. 0 for EOF.
1114  *****************************************************************************/
1115 size_t evel_write_callback(void *contents,
1116                            size_t size,
1117                            size_t nmemb,
1118                            void *userp);
1119
1120 /*****************************************************************************/
1121 /*****************************************************************************/
1122 /*                                                                           */
1123 /*   HEARTBEAT - (includes common header, too)                               */
1124 /*                                                                           */
1125 /*****************************************************************************/
1126 /*****************************************************************************/
1127
1128 /**************************************************************************//**
1129  * Create a new heartbeat event.
1130  *
1131  * @note that the heartbeat is just a "naked" commonEventHeader!
1132  *
1133  * @returns pointer to the newly manufactured ::EVENT_HEADER.  If the event is
1134  *          not used it must be released using ::evel_free_event
1135  * @retval  NULL  Failed to create the event.
1136  *****************************************************************************/
1137 EVENT_HEADER * evel_new_heartbeat(void);
1138
1139 /**************************************************************************//**
1140  * Free an event header.
1141  *
1142  * Free off the event header supplied.  Will free all the contained allocated
1143  * memory.
1144  *
1145  * @note It does not free the header itself, since that may be part of a
1146  * larger structure.
1147  *****************************************************************************/
1148 void evel_free_header(EVENT_HEADER * const event);
1149
1150 /**************************************************************************//**
1151  * Initialize a newly created event header.
1152  *
1153  * @param header  Pointer to the header being initialized.
1154  *****************************************************************************/
1155 void evel_init_header(EVENT_HEADER * const header);
1156
1157 /**************************************************************************//**
1158  * Set the Event Type property of the event header.
1159  *
1160  * @param header        Pointer to the ::EVENT_HEADER.
1161  * @param type          The Event Type to be set. ASCIIZ string. The caller
1162  *                      does not need to preserve the value once the function
1163  *                      returns.
1164  *****************************************************************************/
1165 void evel_header_type_set(EVENT_HEADER * const header,
1166                           const char * const type);
1167
1168 /**************************************************************************//**
1169  * Set the Start Epoch property of the event header.
1170  *
1171  * @note The Start Epoch defaults to the time of event creation.
1172  *
1173  * @param header        Pointer to the ::EVENT_HEADER.
1174  * @param start_epoch_microsec
1175  *                      The start epoch to set, in microseconds.
1176  *****************************************************************************/
1177 void evel_start_epoch_set(EVENT_HEADER * const header,
1178                           const unsigned long long start_epoch_microsec);
1179
1180 /**************************************************************************//**
1181  * Set the Last Epoch property of the event header.
1182  *
1183  * @note The Last Epoch defaults to the time of event creation.
1184  *
1185  * @param header        Pointer to the ::EVENT_HEADER.
1186  * @param last_epoch_microsec
1187  *                      The last epoch to set, in microseconds.
1188  *****************************************************************************/
1189 void evel_last_epoch_set(EVENT_HEADER * const header,
1190                          const unsigned long long last_epoch_microsec);
1191
1192 /**************************************************************************//**
1193  * Set the Reporting Entity Name property of the event header.
1194  *
1195  * @note The Reporting Entity Name defaults to the OpenStack VM Name.
1196  *
1197  * @param header        Pointer to the ::EVENT_HEADER.
1198  * @param entity_name   The entity name to set.
1199  *****************************************************************************/
1200 void evel_reporting_entity_name_set(EVENT_HEADER * const header,
1201                                     const char * const entity_name);
1202
1203 /**************************************************************************//**
1204  * Set the Reporting Entity Id property of the event header.
1205  *
1206  * @note The Reporting Entity Id defaults to the OpenStack VM UUID.
1207  *
1208  * @param header        Pointer to the ::EVENT_HEADER.
1209  * @param entity_id     The entity id to set.
1210  *****************************************************************************/
1211 void evel_reporting_entity_id_set(EVENT_HEADER * const header,
1212                                   const char * const entity_id);
1213
1214 /*****************************************************************************/
1215 /*****************************************************************************/
1216 /*                                                                           */
1217 /*   FAULT                                                                   */
1218 /*                                                                           */
1219 /*****************************************************************************/
1220 /*****************************************************************************/
1221
1222 /**************************************************************************//**
1223  * Create a new fault event.
1224  *
1225  *
1226  * @returns pointer to the newly manufactured ::EVENT_FAULT.  If the event is
1227  *          not used it must be released using ::evel_free_fault
1228  * @retval  NULL  Failed to create the event.
1229  *****************************************************************************/
1230 EVENT_FAULT * evel_new_fault(const char * const condition,
1231                              const char * const specific_problem,
1232                              EVEL_EVENT_PRIORITIES priority,
1233                              EVEL_SEVERITIES severity);
1234
1235 /**************************************************************************//**
1236  * Free a Fault.
1237  *
1238  * Free off the Fault supplied.  Will free all the contained allocated memory.
1239  *
1240  * @note It does not free the Fault itself, since that may be part of a
1241  * larger structure.
1242  *****************************************************************************/
1243 void evel_free_fault(EVENT_FAULT * event);
1244
1245
1246 /**************************************************************************//**
1247  * Set the Alarm Interface A property of the Fault.
1248  *
1249  * @note  The property is treated as immutable: it is only valid to call
1250  *        the setter once.  However, we don't assert if the caller tries to
1251  *        overwrite, just ignoring the update instead.
1252  *
1253  * @param fault      Pointer to the fault.
1254  * @param interface  The Alarm Interface A to be set. ASCIIZ string. The caller
1255  *                   does not need to preserve the value once the function
1256  *                   returns.
1257  *****************************************************************************/
1258 void evel_fault_interface_set(EVENT_FAULT * fault,
1259                               const char * const interface);
1260
1261 /**************************************************************************//**
1262  * Add an additional value name/value pair to the Fault.
1263  *
1264  * The name and value are null delimited ASCII strings.  The library takes
1265  * a copy so the caller does not have to preserve values after the function
1266  * returns.
1267  *
1268  * @param fault     Pointer to the fault.
1269  * @param name      ASCIIZ string with the attribute's name.
1270  * @param value     ASCIIZ string with the attribute's value.
1271  *****************************************************************************/
1272 void evel_fault_addl_info_add(EVENT_FAULT * fault, char * name, char * value);
1273
1274 /**************************************************************************//**
1275  * Set the Event Type property of the Fault.
1276  *
1277  * @note  The property is treated as immutable: it is only valid to call
1278  *        the setter once.  However, we don't assert if the caller tries to
1279  *        overwrite, just ignoring the update instead.
1280  *
1281  * @param fault      Pointer to the fault.
1282  * @param type       The Event Type to be set. ASCIIZ string. The caller
1283  *                   does not need to preserve the value once the function
1284  *                   returns.
1285  *****************************************************************************/
1286 void evel_fault_type_set(EVENT_FAULT * fault, const char * const type);
1287
1288 /*****************************************************************************/
1289 /*****************************************************************************/
1290 /*                                                                           */
1291 /*   MEASUREMENT                                                             */
1292 /*                                                                           */
1293 /*****************************************************************************/
1294 /*****************************************************************************/
1295
1296 /**************************************************************************//**
1297  * Create a new Measurement event.
1298  *
1299  * @note    The mandatory fields on the Measurement must be supplied to this
1300  *          factory function and are immutable once set.  Optional fields have
1301  *          explicit setter functions, but again values may only be set once so
1302  *          that the Measurement has immutable properties.
1303  *
1304  * @param   measurement_interval
1305  *
1306  * @returns pointer to the newly manufactured ::EVENT_MEASUREMENT.  If the
1307  *          event is not used (i.e. posted) it must be released using
1308  *          ::evel_free_event.
1309  * @retval  NULL  Failed to create the event.
1310  *****************************************************************************/
1311 EVENT_MEASUREMENT * evel_new_measurement(double measurement_interval);
1312
1313 /**************************************************************************//**
1314  * Free a Measurement.
1315  *
1316  * Free off the Measurement supplied.  Will free all the contained allocated
1317  * memory.
1318  *
1319  * @note It does not free the Measurement itself, since that may be part of a
1320  * larger structure.
1321  *****************************************************************************/
1322 void evel_free_measurement(EVENT_MEASUREMENT * event);
1323
1324 /**************************************************************************//**
1325  * Set the Event Type property of the Measurement.
1326  *
1327  * @note  The property is treated as immutable: it is only valid to call
1328  *        the setter once.  However, we don't assert if the caller tries to
1329  *        overwrite, just ignoring the update instead.
1330  *
1331  * @param measurement Pointer to the Measurement.
1332  * @param type        The Event Type to be set. ASCIIZ string. The caller
1333  *                    does not need to preserve the value once the function
1334  *                    returns.
1335  *****************************************************************************/
1336 void evel_measurement_type_set(EVENT_MEASUREMENT * measurement,
1337                                const char * const type);
1338
1339 /**************************************************************************//**
1340  * Set the Concurrent Sessions property of the Measurement.
1341  *
1342  * @note  The property is treated as immutable: it is only valid to call
1343  *        the setter once.  However, we don't assert if the caller tries to
1344  *        overwrite, just ignoring the update instead.
1345  *
1346  * @param measurement         Pointer to the Measurement.
1347  * @param concurrent_sessions The Concurrent Sessions to be set.
1348  *****************************************************************************/
1349 void evel_measurement_conc_sess_set(EVENT_MEASUREMENT * measurement,
1350                                     int concurrent_sessions);
1351
1352 /**************************************************************************//**
1353  * Set the Configured Entities property of the Measurement.
1354  *
1355  * @note  The property is treated as immutable: it is only valid to call
1356  *        the setter once.  However, we don't assert if the caller tries to
1357  *        overwrite, just ignoring the update instead.
1358  *
1359  * @param measurement         Pointer to the Measurement.
1360  * @param configured_entities The Configured Entities to be set.
1361  *****************************************************************************/
1362 void evel_measurement_cfg_ents_set(EVENT_MEASUREMENT * measurement,
1363                                    int configured_entities);
1364
1365 /**************************************************************************//**
1366  * Add an additional set of Errors to the Measurement.
1367  *
1368  * @note  The property is treated as immutable: it is only valid to call
1369  *        the setter once.  However, we don't assert if the caller tries to
1370  *        overwrite, just ignoring the update instead.
1371  *
1372  * @param measurement       Pointer to the measurement.
1373  * @param receive_discards  The number of receive discards.
1374  * @param receive_errors    The number of receive errors.
1375  * @param transmit_discards The number of transmit discards.
1376  * @param transmit_errors   The number of transmit errors.
1377  *****************************************************************************/
1378 void evel_measurement_errors_set(EVENT_MEASUREMENT * measurement,
1379                                  int receive_discards,
1380                                  int receive_errors,
1381                                  int transmit_discards,
1382                                  int transmit_errors);
1383
1384 /**************************************************************************//**
1385  * Set the Mean Request Latency property of the Measurement.
1386  *
1387  * @note  The property is treated as immutable: it is only valid to call
1388  *        the setter once.  However, we don't assert if the caller tries to
1389  *        overwrite, just ignoring the update instead.
1390  *
1391  * @param measurement          Pointer to the Measurement.
1392  * @param mean_request_latency The Mean Request Latency to be set.
1393  *****************************************************************************/
1394 void evel_measurement_mean_req_lat_set(EVENT_MEASUREMENT * measurement,
1395                                        double mean_request_latency);
1396
1397 /**************************************************************************//**
1398  * Set the Memory Configured property of the Measurement.
1399  *
1400  * @note  The property is treated as immutable: it is only valid to call
1401  *        the setter once.  However, we don't assert if the caller tries to
1402  *        overwrite, just ignoring the update instead.
1403  *
1404  * @param measurement       Pointer to the Measurement.
1405  * @param memory_configured The Memory Configured to be set.
1406  *****************************************************************************/
1407 void evel_measurement_mem_cfg_set(EVENT_MEASUREMENT * measurement,
1408                                   double memory_configured);
1409
1410 /**************************************************************************//**
1411  * Set the Memory Used property of the Measurement.
1412  *
1413  * @note  The property is treated as immutable: it is only valid to call
1414  *        the setter once.  However, we don't assert if the caller tries to
1415  *        overwrite, just ignoring the update instead.
1416  *
1417  * @param measurement       Pointer to the Measurement.
1418  * @param memory_used The Memory Used to be set.
1419  *****************************************************************************/
1420 void evel_measurement_mem_used_set(EVENT_MEASUREMENT * measurement,
1421                                    double memory_used);
1422
1423 /**************************************************************************//**
1424  * Set the Request Rate property of the Measurement.
1425  *
1426  * @note  The property is treated as immutable: it is only valid to call
1427  *        the setter once.  However, we don't assert if the caller tries to
1428  *        overwrite, just ignoring the update instead.
1429  *
1430  * @param measurement  Pointer to the Measurement.
1431  * @param request_rate The Request Rate to be set.
1432  *****************************************************************************/
1433 void evel_measurement_request_rate_set(EVENT_MEASUREMENT * measurement,
1434                                        int request_rate);
1435
1436 /**************************************************************************//**
1437  * Add an additional CPU usage value name/value pair to the Measurement.
1438  *
1439  * The name and value are null delimited ASCII strings.  The library takes
1440  * a copy so the caller does not have to preserve values after the function
1441  * returns.
1442  *
1443  * @param measurement   Pointer to the measurement.
1444  * @param id            ASCIIZ string with the CPU's identifier.
1445  * @param usage         CPU utilization.
1446  *****************************************************************************/
1447 void evel_measurement_cpu_use_add(EVENT_MEASUREMENT * measurement,
1448                                   char * id, double usage);
1449
1450 /**************************************************************************//**
1451  * Add an additional File System usage value name/value pair to the
1452  * Measurement.
1453  *
1454  * The filesystem_name is null delimited ASCII string.  The library takes a
1455  * copy so the caller does not have to preserve values after the function
1456  * returns.
1457  *
1458  * @param measurement     Pointer to the measurement.
1459  * @param filesystem_name   ASCIIZ string with the file-system's UUID.
1460  * @param block_configured  Block storage configured.
1461  * @param block_used        Block storage in use.
1462  * @param block_iops        Block storage IOPS.
1463  * @param ephemeral_configured  Ephemeral storage configured.
1464  * @param ephemeral_used        Ephemeral storage in use.
1465  * @param ephemeral_iops        Ephemeral storage IOPS.
1466  *****************************************************************************/
1467 void evel_measurement_fsys_use_add(EVENT_MEASUREMENT * measurement,
1468                                    char * filesystem_name,
1469                                    double block_configured,
1470                                    double block_used,
1471                                    int block_iops,
1472                                    double ephemeral_configured,
1473                                    double ephemeral_used,
1474                                    int ephemeral_iops);
1475
1476 /**************************************************************************//**
1477  * Add a Feature usage value name/value pair to the Measurement.
1478  *
1479  * The name is null delimited ASCII string.  The library takes
1480  * a copy so the caller does not have to preserve values after the function
1481  * returns.
1482  *
1483  * @param measurement     Pointer to the measurement.
1484  * @param feature         ASCIIZ string with the feature's name.
1485  * @param utilization     Utilization of the feature.
1486  *****************************************************************************/
1487 void evel_measurement_feature_use_add(EVENT_MEASUREMENT * measurement,
1488                                       char * feature,
1489                                       int utilization);
1490
1491 /**************************************************************************//**
1492  * Add a Additional Measurement value name/value pair to the Measurement.
1493  *
1494  * The name is null delimited ASCII string.  The library takes
1495  * a copy so the caller does not have to preserve values after the function
1496  * returns.
1497  *
1498  * @param measurement   Pointer to the Measurement.
1499  * @param group    ASCIIZ string with the measurement group's name.
1500  * @param name     ASCIIZ string containing the measurement's name.
1501  * @param name     ASCIIZ string containing the measurement's value.
1502  *****************************************************************************/
1503 void evel_measurement_custom_measurement_add(EVENT_MEASUREMENT * measurement,
1504                                              const char * const group,
1505                                              const char * const name,
1506                                              const char * const value);
1507
1508 /**************************************************************************//**
1509  * Add a Codec usage value name/value pair to the Measurement.
1510  *
1511  * The name is null delimited ASCII string.  The library takes
1512  * a copy so the caller does not have to preserve values after the function
1513  * returns.
1514  *
1515  * @param measurement     Pointer to the measurement.
1516  * @param codec           ASCIIZ string with the codec's name.
1517  * @param utilization     Utilization of the feature.
1518  *****************************************************************************/
1519 void evel_measurement_codec_use_add(EVENT_MEASUREMENT * measurement,
1520                                     char * codec,
1521                                     int utilization);
1522
1523 /**************************************************************************//**
1524 }
1525  * Set the Aggregate CPU Use property of the Measurement.
1526  *
1527  * @note  The property is treated as immutable: it is only valid to call
1528  *        the setter once.  However, we don't assert if the caller tries to
1529  *        overwrite, just ignoring the update instead.
1530  *
1531  * @param measurement   Pointer to the measurement.
1532  * @param cpu_use       The CPU use to set.
1533  *****************************************************************************/
1534 void evel_measurement_agg_cpu_use_set(EVENT_MEASUREMENT * measurement,
1535                                       double cpu_use);
1536
1537 /**************************************************************************//**
1538  * Set the Media Ports in Use property of the Measurement.
1539  *
1540  * @note  The property is treated as immutable: it is only valid to call
1541  *        the setter once.  However, we don't assert if the caller tries to
1542  *        overwrite, just ignoring the update instead.
1543  *
1544  * @param measurement         Pointer to the measurement.
1545  * @param media_ports_in_use  The media port usage to set.
1546  *****************************************************************************/
1547 void evel_measurement_media_port_use_set(EVENT_MEASUREMENT * measurement,
1548                                          int media_ports_in_use);
1549
1550 /**************************************************************************//**
1551  * Set the VNFC Scaling Metric property of the Measurement.
1552  *
1553  * @note  The property is treated as immutable: it is only valid to call
1554  *        the setter once.  However, we don't assert if the caller tries to
1555  *        overwrite, just ignoring the update instead.
1556  *
1557  * @param measurement     Pointer to the measurement.
1558  * @param scaling_metric  The scaling metric to set.
1559  *****************************************************************************/
1560 void evel_measurement_vnfc_scaling_metric_set(EVENT_MEASUREMENT * measurement,
1561                                               double scaling_metric);
1562
1563 /**************************************************************************//**
1564  * Create a new Latency Bucket to be added to a Measurement event.
1565  *
1566  * @note    The mandatory fields on the ::MEASUREMENT_LATENCY_BUCKET must be
1567  *          supplied to this factory function and are immutable once set.
1568  *          Optional fields have explicit setter functions, but again values
1569  *          may only be set once so that the ::MEASUREMENT_LATENCY_BUCKET has
1570  *          immutable properties.
1571  *
1572  * @param count         Count of events in this bucket.
1573  *
1574  * @returns pointer to the newly manufactured ::MEASUREMENT_LATENCY_BUCKET.
1575  * @retval  NULL  Failed to create the Latency Bucket.
1576  *****************************************************************************/
1577 MEASUREMENT_LATENCY_BUCKET * evel_new_meas_latency_bucket(const int count);
1578
1579 /**************************************************************************//**
1580  * Set the High End property of the Measurement Latency Bucket.
1581  *
1582  * @note  The property is treated as immutable: it is only valid to call
1583  *        the setter once.  However, we don't assert if the caller tries to
1584  *        overwrite, just ignoring the update instead.
1585  *
1586  * @param bucket        Pointer to the Measurement Latency Bucket.
1587  * @param high_end      High end of the bucket's range.
1588  *****************************************************************************/
1589 void evel_meas_latency_bucket_high_end_set(
1590                                      MEASUREMENT_LATENCY_BUCKET * const bucket,
1591                                      const double high_end);
1592
1593 /**************************************************************************//**
1594  * Set the Low End property of the Measurement Latency Bucket.
1595  *
1596  * @note  The property is treated as immutable: it is only valid to call
1597  *        the setter once.  However, we don't assert if the caller tries to
1598  *        overwrite, just ignoring the update instead.
1599  *
1600  * @param bucket        Pointer to the Measurement Latency Bucket.
1601  * @param low_end       Low end of the bucket's range.
1602  *****************************************************************************/
1603 void evel_meas_latency_bucket_low_end_set(
1604                                      MEASUREMENT_LATENCY_BUCKET * const bucket,
1605                                      const double low_end);
1606
1607 /**************************************************************************//**
1608  * Add an additional Measurement Latency Bucket to the specified event.
1609  *
1610  * @param measurement   Pointer to the Measurement event.
1611  * @param bucket        Pointer to the Measurement Latency Bucket to add.
1612  *****************************************************************************/
1613 void evel_meas_latency_bucket_add(EVENT_MEASUREMENT * const measurement,
1614                                   MEASUREMENT_LATENCY_BUCKET * const bucket);
1615
1616 /**************************************************************************//**
1617  * Add an additional Latency Distribution bucket to the Measurement.
1618  *
1619  * This function implements the previous API, purely for convenience.
1620  *
1621  * @param measurement   Pointer to the measurement.
1622  * @param low_end       Low end of the bucket's range.
1623  * @param high_end      High end of the bucket's range.
1624  * @param count         Count of events in this bucket.
1625  *****************************************************************************/
1626 void evel_measurement_latency_add(EVENT_MEASUREMENT * const measurement,
1627                                   const double low_end,
1628                                   const double high_end,
1629                                   const int count);
1630
1631 /**************************************************************************//**
1632  * Create a new vNIC Use to be added to a Measurement event.
1633  *
1634  * @note    The mandatory fields on the ::MEASUREMENT_VNIC_USE must be supplied
1635  *          to this factory function and are immutable once set. Optional
1636  *          fields have explicit setter functions, but again values may only be
1637  *          set once so that the ::MEASUREMENT_VNIC_USE has immutable
1638  *          properties.
1639  *
1640  * @param vnic_id               ASCIIZ string with the vNIC's ID.
1641  * @param packets_in            Total packets received.
1642  * @param packets_out           Total packets transmitted.
1643  * @param bytes_in              Total bytes received.
1644  * @param bytes_out             Total bytes transmitted.
1645  *
1646  * @returns pointer to the newly manufactured ::MEASUREMENT_VNIC_USE.
1647  *          If the structure is not used it must be released using
1648  *          ::evel_free_measurement_vnic_use.
1649  * @retval  NULL  Failed to create the vNIC Use.
1650  *****************************************************************************/
1651 MEASUREMENT_VNIC_USE * evel_new_measurement_vnic_use(char * const vnic_id,
1652                                                      const int packets_in,
1653                                                      const int packets_out,
1654                                                      const int bytes_in,
1655                                                      const int bytes_out);
1656
1657 /**************************************************************************//**
1658  * Free a vNIC Use.
1659  *
1660  * Free off the ::MEASUREMENT_VNIC_USE supplied.  Will free all the contained
1661  * allocated memory.
1662  *
1663  * @note It does not free the vNIC Use itself, since that may be part of a
1664  * larger structure.
1665  *****************************************************************************/
1666 void evel_free_measurement_vnic_use(MEASUREMENT_VNIC_USE * const vnic_use);
1667
1668 /**************************************************************************//**
1669  * Set the Broadcast Packets Received property of the vNIC Use.
1670  *
1671  * @note  The property is treated as immutable: it is only valid to call
1672  *        the setter once.  However, we don't assert if the caller tries to
1673  *        overwrite, just ignoring the update instead.
1674  *
1675  * @param vnic_use      Pointer to the vNIC Use.
1676  * @param broadcast_packets_in
1677  *                      Broadcast packets received.
1678  *****************************************************************************/
1679 void evel_vnic_use_bcast_pkt_in_set(MEASUREMENT_VNIC_USE * const vnic_use,
1680                                     const int broadcast_packets_in);
1681
1682 /**************************************************************************//**
1683  * Set the Broadcast Packets Transmitted property of the vNIC Use.
1684  *
1685  * @note  The property is treated as immutable: it is only valid to call
1686  *        the setter once.  However, we don't assert if the caller tries to
1687  *        overwrite, just ignoring the update instead.
1688  *
1689  * @param vnic_use      Pointer to the vNIC Use.
1690  * @param broadcast_packets_out
1691  *                      Broadcast packets transmitted.
1692  *****************************************************************************/
1693 void evel_vnic_use_bcast_pkt_out_set(MEASUREMENT_VNIC_USE * const vnic_use,
1694                                      const int broadcast_packets_out);
1695
1696 /**************************************************************************//**
1697  * Set the Multicast Packets Received property of the vNIC Use.
1698  *
1699  * @note  The property is treated as immutable: it is only valid to call
1700  *        the setter once.  However, we don't assert if the caller tries to
1701  *        overwrite, just ignoring the update instead.
1702  *
1703  * @param vnic_use      Pointer to the vNIC Use.
1704  * @param multicast_packets_in
1705  *                      Multicast packets received.
1706  *****************************************************************************/
1707 void evel_vnic_use_mcast_pkt_in_set(MEASUREMENT_VNIC_USE * const vnic_use,
1708                                     const int multicast_packets_in);
1709
1710 /**************************************************************************//**
1711  * Set the Multicast Packets Transmitted property of the vNIC Use.
1712  *
1713  * @note  The property is treated as immutable: it is only valid to call
1714  *        the setter once.  However, we don't assert if the caller tries to
1715  *        overwrite, just ignoring the update instead.
1716  *
1717  * @param vnic_use      Pointer to the vNIC Use.
1718  * @param multicast_packets_out
1719  *                      Multicast packets transmitted.
1720  *****************************************************************************/
1721 void evel_vnic_use_mcast_pkt_out_set(MEASUREMENT_VNIC_USE * const vnic_use,
1722                                      const int multicast_packets_out);
1723
1724 /**************************************************************************//**
1725  * Set the Unicast Packets Received property of the vNIC Use.
1726  *
1727  * @note  The property is treated as immutable: it is only valid to call
1728  *        the setter once.  However, we don't assert if the caller tries to
1729  *        overwrite, just ignoring the update instead.
1730  *
1731  * @param vnic_use      Pointer to the vNIC Use.
1732  * @param unicast_packets_in
1733  *                      Unicast packets received.
1734  *****************************************************************************/
1735 void evel_vnic_use_ucast_pkt_in_set(MEASUREMENT_VNIC_USE * const vnic_use,
1736                                     const int unicast_packets_in);
1737
1738 /**************************************************************************//**
1739  * Set the Unicast Packets Transmitted property of the vNIC Use.
1740  *
1741  * @note  The property is treated as immutable: it is only valid to call
1742  *        the setter once.  However, we don't assert if the caller tries to
1743  *        overwrite, just ignoring the update instead.
1744  *
1745  * @param vnic_use      Pointer to the vNIC Use.
1746  * @param unicast_packets_out
1747  *                      Unicast packets transmitted.
1748  *****************************************************************************/
1749 void evel_vnic_use_ucast_pkt_out_set(MEASUREMENT_VNIC_USE * const vnic_use,
1750                                      const int unicast_packets_out);
1751
1752 /**************************************************************************//**
1753  * Add an additional vNIC Use to the specified Measurement event.
1754  *
1755  * @param measurement   Pointer to the measurement.
1756  * @param vnic_use      Pointer to the vNIC Use to add.
1757  *****************************************************************************/
1758 void evel_meas_vnic_use_add(EVENT_MEASUREMENT * const measurement,
1759                             MEASUREMENT_VNIC_USE * const vnic_use);
1760
1761 /**************************************************************************//**
1762  * Add an additional vNIC usage record Measurement.
1763  *
1764  * This function implements the previous API, purely for convenience.
1765  *
1766  * The ID is null delimited ASCII string.  The library takes a copy so the
1767  * caller does not have to preserve values after the function returns.
1768  *
1769  * @param measurement           Pointer to the measurement.
1770  * @param vnic_id               ASCIIZ string with the vNIC's ID.
1771  * @param packets_in            Total packets received.
1772  * @param packets_out           Total packets transmitted.
1773  * @param broadcast_packets_in  Broadcast packets received.
1774  * @param broadcast_packets_out Broadcast packets transmitted.
1775  * @param bytes_in              Total bytes received.
1776  * @param bytes_out             Total bytes transmitted.
1777  * @param multicast_packets_in  Multicast packets received.
1778  * @param multicast_packets_out Multicast packets transmitted.
1779  * @param unicast_packets_in    Unicast packets received.
1780  * @param unicast_packets_out   Unicast packets transmitted.
1781  *****************************************************************************/
1782 void evel_measurement_vnic_use_add(EVENT_MEASUREMENT * const measurement,
1783                                    char * const vnic_id,
1784                                    const int packets_in,
1785                                    const int packets_out,
1786                                    const int broadcast_packets_in,
1787                                    const int broadcast_packets_out,
1788                                    const int bytes_in,
1789                                    const int bytes_out,
1790                                    const int multicast_packets_in,
1791                                    const int multicast_packets_out,
1792                                    const int unicast_packets_in,
1793                                    const int unicast_packets_out);
1794
1795 /*****************************************************************************/
1796 /*****************************************************************************/
1797 /*                                                                           */
1798 /*   REPORT                                                                  */
1799 /*                                                                           */
1800 /*****************************************************************************/
1801 /*****************************************************************************/
1802
1803 /**************************************************************************//**
1804  * Create a new Report event.
1805  *
1806  * @note    The mandatory fields on the Report must be supplied to this
1807  *          factory function and are immutable once set.  Optional fields have
1808  *          explicit setter functions, but again values may only be set once so
1809  *          that the Report has immutable properties.
1810  *
1811  * @param   measurement_interval
1812  *
1813  * @returns pointer to the newly manufactured ::EVENT_REPORT.  If the event is
1814  *          not used (i.e. posted) it must be released using
1815  *          ::evel_free_report.
1816  * @retval  NULL  Failed to create the event.
1817  *****************************************************************************/
1818 EVENT_REPORT * evel_new_report(double measurement_interval);
1819
1820 /**************************************************************************//**
1821  * Free a Report.
1822  *
1823  * Free off the Report supplied.  Will free all the contained allocated memory.
1824  *
1825  * @note It does not free the Report itself, since that may be part of a
1826  * larger structure.
1827  *****************************************************************************/
1828 void evel_free_report(EVENT_REPORT * event);
1829
1830 /**************************************************************************//**
1831  * Set the Event Type property of the Report.
1832  *
1833  * @note  The property is treated as immutable: it is only valid to call
1834  *        the setter once.  However, we don't assert if the caller tries to
1835  *        overwrite, just ignoring the update instead.
1836  *
1837  * @param report Pointer to the Report.
1838  * @param type        The Event Type to be set. ASCIIZ string. The caller
1839  *                    does not need to preserve the value once the function
1840  *                    returns.
1841  *****************************************************************************/
1842 void evel_report_type_set(EVENT_REPORT * report, const char * const type);
1843
1844 /**************************************************************************//**
1845  * Add a Feature usage value name/value pair to the Report.
1846  *
1847  * The name is null delimited ASCII string.  The library takes
1848  * a copy so the caller does not have to preserve values after the function
1849  * returns.
1850  *
1851  * @param report          Pointer to the report.
1852  * @param feature         ASCIIZ string with the feature's name.
1853  * @param utilization     Utilization of the feature.
1854  *****************************************************************************/
1855 void evel_report_feature_use_add(EVENT_REPORT * report,
1856                                  char * feature,
1857                                  int utilization);
1858
1859 /**************************************************************************//**
1860  * Add a Additional Measurement value name/value pair to the Report.
1861  *
1862  * The name is null delimited ASCII string.  The library takes
1863  * a copy so the caller does not have to preserve values after the function
1864  * returns.
1865  *
1866  * @param report   Pointer to the report.
1867  * @param group    ASCIIZ string with the measurement group's name.
1868  * @param name     ASCIIZ string containing the measurement's name.
1869  * @param value    ASCIIZ string containing the measurement's value.
1870  *****************************************************************************/
1871 void evel_report_custom_measurement_add(EVENT_REPORT * report,
1872                                         const char * const group,
1873                                         const char * const name,
1874                                         const char * const value);
1875
1876 /*****************************************************************************/
1877 /*****************************************************************************/
1878 /*                                                                           */
1879 /*   MOBILE_FLOW                                                             */
1880 /*                                                                           */
1881 /*****************************************************************************/
1882 /*****************************************************************************/
1883
1884 /**************************************************************************//**
1885  * Create a new Mobile Flow event.
1886  *
1887  * @note    The mandatory fields on the Mobile Flow must be supplied to this
1888  *          factory function and are immutable once set.  Optional fields have
1889  *          explicit setter functions, but again values may only be set once so
1890  *          that the Mobile Flow has immutable properties.
1891  *
1892  * @param   flow_direction
1893  * @param   gtp_per_flow_metrics
1894  * @param   ip_protocol_type
1895  * @param   ip_version
1896  * @param   other_endpoint_ip_address
1897  * @param   other_endpoint_port
1898  * @param   reporting_endpoint_ip_addr
1899  * @param   reporting_endpoint_port
1900  *
1901  * @returns pointer to the newly manufactured ::EVENT_MOBILE_FLOW.  If the
1902  *          event is not used (i.e. posted) it must be released using
1903  *          ::evel_free_mobile_flow.
1904  * @retval  NULL  Failed to create the event.
1905  *****************************************************************************/
1906 EVENT_MOBILE_FLOW * evel_new_mobile_flow(
1907                       const char * const flow_direction,
1908                       MOBILE_GTP_PER_FLOW_METRICS * gtp_per_flow_metrics,
1909                       const char * const ip_protocol_type,
1910                       const char * const ip_version,
1911                       const char * const other_endpoint_ip_address,
1912                       int other_endpoint_port,
1913                       const char * const reporting_endpoint_ip_addr,
1914                       int reporting_endpoint_port);
1915
1916 /**************************************************************************//**
1917  * Free a Mobile Flow.
1918  *
1919  * Free off the Mobile Flow supplied.  Will free all the contained allocated
1920  * memory.
1921  *
1922  * @note It does not free the Mobile Flow itself, since that may be part of a
1923  * larger structure.
1924  *****************************************************************************/
1925 void evel_free_mobile_flow(EVENT_MOBILE_FLOW * event);
1926
1927 /**************************************************************************//**
1928  * Set the Event Type property of the Mobile Flow.
1929  *
1930  * @note  The property is treated as immutable: it is only valid to call
1931  *        the setter once.  However, we don't assert if the caller tries to
1932  *        overwrite, just ignoring the update instead.
1933  *
1934  * @param mobile_flow Pointer to the Mobile Flow.
1935  * @param type        The Event Type to be set. ASCIIZ string. The caller
1936  *                    does not need to preserve the value once the function
1937  *                    returns.
1938  *****************************************************************************/
1939 void evel_mobile_flow_type_set(EVENT_MOBILE_FLOW * mobile_flow,
1940                                const char * const type);
1941
1942 /**************************************************************************//**
1943  * Set the Application Type property of the Mobile Flow.
1944  *
1945  * @note  The property is treated as immutable: it is only valid to call
1946  *        the setter once.  However, we don't assert if the caller tries to
1947  *        overwrite, just ignoring the update instead.
1948  *
1949  * @param mobile_flow Pointer to the Mobile Flow.
1950  * @param type        The Application Type to be set. ASCIIZ string. The caller
1951  *                    does not need to preserve the value once the function
1952  *                    returns.
1953  *****************************************************************************/
1954 void evel_mobile_flow_app_type_set(EVENT_MOBILE_FLOW * mobile_flow,
1955                                    const char * const type);
1956
1957 /**************************************************************************//**
1958  * Set the Application Protocol Type property of the Mobile Flow.
1959  *
1960  * @note  The property is treated as immutable: it is only valid to call
1961  *        the setter once.  However, we don't assert if the caller tries to
1962  *        overwrite, just ignoring the update instead.
1963  *
1964  * @param mobile_flow Pointer to the Mobile Flow.
1965  * @param type        The Application Protocol Type to be set. ASCIIZ string.
1966  *                    The caller does not need to preserve the value once the
1967  *                    function returns.
1968  *****************************************************************************/
1969 void evel_mobile_flow_app_prot_type_set(EVENT_MOBILE_FLOW * mobile_flow,
1970                                         const char * const type);
1971
1972 /**************************************************************************//**
1973  * Set the Application Protocol Version property of the Mobile Flow.
1974  *
1975  * @note  The property is treated as immutable: it is only valid to call
1976  *        the setter once.  However, we don't assert if the caller tries to
1977  *        overwrite, just ignoring the update instead.
1978  *
1979  * @param mobile_flow Pointer to the Mobile Flow.
1980  * @param version     The Application Protocol Version to be set. ASCIIZ
1981  *                    string.  The caller does not need to preserve the value
1982  *                    once the function returns.
1983  *****************************************************************************/
1984 void evel_mobile_flow_app_prot_ver_set(EVENT_MOBILE_FLOW * mobile_flow,
1985                                        const char * const version);
1986
1987 /**************************************************************************//**
1988  * Set the CID property of the Mobile Flow.
1989  *
1990  * @note  The property is treated as immutable: it is only valid to call
1991  *        the setter once.  However, we don't assert if the caller tries to
1992  *        overwrite, just ignoring the update instead.
1993  *
1994  * @param mobile_flow Pointer to the Mobile Flow.
1995  * @param cid         The CID to be set. ASCIIZ string.  The caller does not
1996  *                    need to preserve the value once the function returns.
1997  *****************************************************************************/
1998 void evel_mobile_flow_cid_set(EVENT_MOBILE_FLOW * mobile_flow,
1999                               const char * const cid);
2000
2001 /**************************************************************************//**
2002  * Set the Connection Type property of the Mobile Flow.
2003  *
2004  * @note  The property is treated as immutable: it is only valid to call
2005  *        the setter once.  However, we don't assert if the caller tries to
2006  *        overwrite, just ignoring the update instead.
2007  *
2008  * @param mobile_flow Pointer to the Mobile Flow.
2009  * @param type        The Connection Type to be set. ASCIIZ string. The caller
2010  *                    does not need to preserve the value once the function
2011  *                    returns.
2012  *****************************************************************************/
2013 void evel_mobile_flow_con_type_set(EVENT_MOBILE_FLOW * mobile_flow,
2014                                    const char * const type);
2015
2016 /**************************************************************************//**
2017  * Set the ECGI property of the Mobile Flow.
2018  *
2019  * @note  The property is treated as immutable: it is only valid to call
2020  *        the setter once.  However, we don't assert if the caller tries to
2021  *        overwrite, just ignoring the update instead.
2022  *
2023  * @param mobile_flow Pointer to the Mobile Flow.
2024  * @param ecgi        The ECGI to be set. ASCIIZ string.  The caller does not
2025  *                    need to preserve the value once the function returns.
2026  *****************************************************************************/
2027 void evel_mobile_flow_ecgi_set(EVENT_MOBILE_FLOW * mobile_flow,
2028                                const char * const ecgi);
2029
2030 /**************************************************************************//**
2031  * Set the GTP Protocol Type property of the Mobile Flow.
2032  *
2033  * @note  The property is treated as immutable: it is only valid to call
2034  *        the setter once.  However, we don't assert if the caller tries to
2035  *        overwrite, just ignoring the update instead.
2036  *
2037  * @param mobile_flow Pointer to the Mobile Flow.
2038  * @param type        The GTP Protocol Type to be set. ASCIIZ string.  The
2039  *                    caller does not need to preserve the value once the
2040  *                    function returns.
2041  *****************************************************************************/
2042 void evel_mobile_flow_gtp_prot_type_set(EVENT_MOBILE_FLOW * mobile_flow,
2043                                         const char * const type);
2044
2045 /**************************************************************************//**
2046  * Set the GTP Protocol Version property of the Mobile Flow.
2047  *
2048  * @note  The property is treated as immutable: it is only valid to call
2049  *        the setter once.  However, we don't assert if the caller tries to
2050  *        overwrite, just ignoring the update instead.
2051  *
2052  * @param mobile_flow Pointer to the Mobile Flow.
2053  * @param version     The GTP Protocol Version to be set. ASCIIZ string.  The
2054  *                    caller does not need to preserve the value once the
2055  *                    function returns.
2056  *****************************************************************************/
2057 void evel_mobile_flow_gtp_prot_ver_set(EVENT_MOBILE_FLOW * mobile_flow,
2058                                        const char * const version);
2059
2060 /**************************************************************************//**
2061  * Set the HTTP Header property of the Mobile Flow.
2062  *
2063  * @note  The property is treated as immutable: it is only valid to call
2064  *        the setter once.  However, we don't assert if the caller tries to
2065  *        overwrite, just ignoring the update instead.
2066  *
2067  * @param mobile_flow Pointer to the Mobile Flow.
2068  * @param header      The HTTP header to be set. ASCIIZ string. The caller does
2069  *                    not need to preserve the value once the function returns.
2070  *****************************************************************************/
2071 void evel_mobile_flow_http_header_set(EVENT_MOBILE_FLOW * mobile_flow,
2072                                       const char * const header);
2073
2074 /**************************************************************************//**
2075  * Set the IMEI property of the Mobile Flow.
2076  *
2077  * @note  The property is treated as immutable: it is only valid to call
2078  *        the setter once.  However, we don't assert if the caller tries to
2079  *        overwrite, just ignoring the update instead.
2080  *
2081  * @param mobile_flow Pointer to the Mobile Flow.
2082  * @param imei        The IMEI to be set. ASCIIZ string.  The caller does not
2083  *                    need to preserve the value once the function returns.
2084  *****************************************************************************/
2085 void evel_mobile_flow_imei_set(EVENT_MOBILE_FLOW * mobile_flow,
2086                                const char * const imei);
2087
2088 /**************************************************************************//**
2089  * Set the IMSI property of the Mobile Flow.
2090  *
2091  * @note  The property is treated as immutable: it is only valid to call
2092  *        the setter once.  However, we don't assert if the caller tries to
2093  *        overwrite, just ignoring the update instead.
2094  *
2095  * @param mobile_flow Pointer to the Mobile Flow.
2096  * @param imsi        The IMSI to be set. ASCIIZ string.  The caller does not
2097  *                    need to preserve the value once the function returns.
2098  *****************************************************************************/
2099 void evel_mobile_flow_imsi_set(EVENT_MOBILE_FLOW * mobile_flow,
2100                                const char * const imsi);
2101
2102 /**************************************************************************//**
2103  * Set the LAC property of the Mobile Flow.
2104  *
2105  * @note  The property is treated as immutable: it is only valid to call
2106  *        the setter once.  However, we don't assert if the caller tries to
2107  *        overwrite, just ignoring the update instead.
2108  *
2109  * @param mobile_flow Pointer to the Mobile Flow.
2110  * @param lac         The LAC to be set. ASCIIZ string.  The caller does not
2111  *                    need to preserve the value once the function returns.
2112  *****************************************************************************/
2113 void evel_mobile_flow_lac_set(EVENT_MOBILE_FLOW * mobile_flow,
2114                               const char * const lac);
2115
2116 /**************************************************************************//**
2117  * Set the MCC property of the Mobile Flow.
2118  *
2119  * @note  The property is treated as immutable: it is only valid to call
2120  *        the setter once.  However, we don't assert if the caller tries to
2121  *        overwrite, just ignoring the update instead.
2122  *
2123  * @param mobile_flow Pointer to the Mobile Flow.
2124  * @param mcc         The MCC to be set. ASCIIZ string.  The caller does not
2125  *                    need to preserve the value once the function returns.
2126  *****************************************************************************/
2127 void evel_mobile_flow_mcc_set(EVENT_MOBILE_FLOW * mobile_flow,
2128                               const char * const mcc);
2129
2130 /**************************************************************************//**
2131  * Set the MNC property of the Mobile Flow.
2132  *
2133  * @note  The property is treated as immutable: it is only valid to call
2134  *        the setter once.  However, we don't assert if the caller tries to
2135  *        overwrite, just ignoring the update instead.
2136  *
2137  * @param mobile_flow Pointer to the Mobile Flow.
2138  * @param mnc         The MNC to be set. ASCIIZ string.  The caller does not
2139  *                    need to preserve the value once the function returns.
2140  *****************************************************************************/
2141 void evel_mobile_flow_mnc_set(EVENT_MOBILE_FLOW * mobile_flow,
2142                               const char * const mnc);
2143
2144 /**************************************************************************//**
2145  * Set the MSISDN property of the Mobile Flow.
2146  *
2147  * @note  The property is treated as immutable: it is only valid to call
2148  *        the setter once.  However, we don't assert if the caller tries to
2149  *        overwrite, just ignoring the update instead.
2150  *
2151  * @param mobile_flow Pointer to the Mobile Flow.
2152  * @param msisdn      The MSISDN to be set. ASCIIZ string.  The caller does not
2153  *                    need to preserve the value once the function returns.
2154  *****************************************************************************/
2155 void evel_mobile_flow_msisdn_set(EVENT_MOBILE_FLOW * mobile_flow,
2156                                  const char * const msisdn);
2157
2158 /**************************************************************************//**
2159  * Set the Other Functional Role property of the Mobile Flow.
2160  *
2161  * @note  The property is treated as immutable: it is only valid to call
2162  *        the setter once.  However, we don't assert if the caller tries to
2163  *        overwrite, just ignoring the update instead.
2164  *
2165  * @param mobile_flow Pointer to the Mobile Flow.
2166  * @param role        The Other Functional Role to be set. ASCIIZ string. The
2167  *                    caller does not need to preserve the value once the
2168  *                    function returns.
2169  *****************************************************************************/
2170 void evel_mobile_flow_other_func_role_set(EVENT_MOBILE_FLOW * mobile_flow,
2171                                           const char * const role);
2172
2173 /**************************************************************************//**
2174  * Set the RAC property of the Mobile Flow.
2175  *
2176  * @note  The property is treated as immutable: it is only valid to call
2177  *        the setter once.  However, we don't assert if the caller tries to
2178  *        overwrite, just ignoring the update instead.
2179  *
2180  * @param mobile_flow Pointer to the Mobile Flow.
2181  * @param rac         The RAC to be set. ASCIIZ string.  The caller does not
2182  *                    need to preserve the value once the function returns.
2183  *****************************************************************************/
2184 void evel_mobile_flow_rac_set(EVENT_MOBILE_FLOW * mobile_flow,
2185                               const char * const rac);
2186
2187 /**************************************************************************//**
2188  * Set the Radio Access Technology property of the Mobile Flow.
2189  *
2190  * @note  The property is treated as immutable: it is only valid to call
2191  *        the setter once.  However, we don't assert if the caller tries to
2192  *        overwrite, just ignoring the update instead.
2193  *
2194  * @param mobile_flow Pointer to the Mobile Flow.
2195  * @param tech        The Radio Access Technology to be set. ASCIIZ string. The
2196  *                    caller does not need to preserve the value once the
2197  *                    function returns.
2198  *****************************************************************************/
2199 void evel_mobile_flow_radio_acc_tech_set(EVENT_MOBILE_FLOW * mobile_flow,
2200                                          const char * const tech);
2201
2202 /**************************************************************************//**
2203  * Set the SAC property of the Mobile Flow.
2204  *
2205  * @note  The property is treated as immutable: it is only valid to call
2206  *        the setter once.  However, we don't assert if the caller tries to
2207  *        overwrite, just ignoring the update instead.
2208  *
2209  * @param mobile_flow Pointer to the Mobile Flow.
2210  * @param sac         The SAC to be set. ASCIIZ string.  The caller does not
2211  *                    need to preserve the value once the function returns.
2212  *****************************************************************************/
2213 void evel_mobile_flow_sac_set(EVENT_MOBILE_FLOW * mobile_flow,
2214                               const char * const sac);
2215
2216 /**************************************************************************//**
2217  * Set the Sampling Algorithm property of the Mobile Flow.
2218  *
2219  * @note  The property is treated as immutable: it is only valid to call
2220  *        the setter once.  However, we don't assert if the caller tries to
2221  *        overwrite, just ignoring the update instead.
2222  *
2223  * @param mobile_flow Pointer to the Mobile Flow.
2224  * @param algorithm   The Sampling Algorithm to be set.
2225  *****************************************************************************/
2226 void evel_mobile_flow_samp_alg_set(EVENT_MOBILE_FLOW * mobile_flow,
2227                                    int algorithm);
2228
2229 /**************************************************************************//**
2230  * Set the TAC property of the Mobile Flow.
2231  *
2232  * @note  The property is treated as immutable: it is only valid to call
2233  *        the setter once.  However, we don't assert if the caller tries to
2234  *        overwrite, just ignoring the update instead.
2235  *
2236  * @param mobile_flow Pointer to the Mobile Flow.
2237  * @param tac         The TAC to be set. ASCIIZ string.  The caller does not
2238  *                    need to preserve the value once the function returns.
2239  *****************************************************************************/
2240 void evel_mobile_flow_tac_set(EVENT_MOBILE_FLOW * mobile_flow,
2241                               const char * const tac);
2242
2243 /**************************************************************************//**
2244  * Set the Tunnel ID property of the Mobile Flow.
2245  *
2246  * @note  The property is treated as immutable: it is only valid to call
2247  *        the setter once.  However, we don't assert if the caller tries to
2248  *        overwrite, just ignoring the update instead.
2249  *
2250  * @param mobile_flow Pointer to the Mobile Flow.
2251  * @param tunnel_id   The Tunnel ID to be set. ASCIIZ string.  The caller does
2252  *                    not need to preserve the value once the function returns.
2253  *****************************************************************************/
2254 void evel_mobile_flow_tunnel_id_set(EVENT_MOBILE_FLOW * mobile_flow,
2255                                     const char * const tunnel_id);
2256
2257 /**************************************************************************//**
2258  * Set the VLAN ID property of the Mobile Flow.
2259  *
2260  * @note  The property is treated as immutable: it is only valid to call
2261  *        the setter once.  However, we don't assert if the caller tries to
2262  *        overwrite, just ignoring the update instead.
2263  *
2264  * @param mobile_flow Pointer to the Mobile Flow.
2265  * @param vlan_id     The VLAN ID to be set. ASCIIZ string.  The caller does
2266  *                    not need to preserve the value once the function returns.
2267  *****************************************************************************/
2268 void evel_mobile_flow_vlan_id_set(EVENT_MOBILE_FLOW * mobile_flow,
2269                                   const char * const vlan_id);
2270
2271 /**************************************************************************//**
2272  * Create a new Mobile GTP Per Flow Metrics.
2273  *
2274  * @note    The mandatory fields on the Mobile GTP Per Flow Metrics must be
2275  *          supplied to this factory function and are immutable once set.
2276  *          Optional fields have explicit setter functions, but again values
2277  *          may only be set once so that the Mobile GTP Per Flow Metrics has
2278  *          immutable properties.
2279  *
2280  * @param   avg_bit_error_rate
2281  * @param   avg_packet_delay_variation
2282  * @param   avg_packet_latency
2283  * @param   avg_receive_throughput
2284  * @param   avg_transmit_throughput
2285  * @param   flow_activation_epoch
2286  * @param   flow_activation_microsec
2287  * @param   flow_deactivation_epoch
2288  * @param   flow_deactivation_microsec
2289  * @param   flow_deactivation_time
2290  * @param   flow_status
2291  * @param   max_packet_delay_variation
2292  * @param   num_activation_failures
2293  * @param   num_bit_errors
2294  * @param   num_bytes_received
2295  * @param   num_bytes_transmitted
2296  * @param   num_dropped_packets
2297  * @param   num_l7_bytes_received
2298  * @param   num_l7_bytes_transmitted
2299  * @param   num_lost_packets
2300  * @param   num_out_of_order_packets
2301  * @param   num_packet_errors
2302  * @param   num_packets_received_excl_retrans
2303  * @param   num_packets_received_incl_retrans
2304  * @param   num_packets_transmitted_incl_retrans
2305  * @param   num_retries
2306  * @param   num_timeouts
2307  * @param   num_tunneled_l7_bytes_received
2308  * @param   round_trip_time
2309  * @param   time_to_first_byte
2310  *
2311  * @returns pointer to the newly manufactured ::MOBILE_GTP_PER_FLOW_METRICS.
2312  *          If the structure is not used it must be released using
2313  *          ::evel_free_mobile_gtp_flow_metrics.
2314  * @retval  NULL  Failed to create the event.
2315  *****************************************************************************/
2316 MOBILE_GTP_PER_FLOW_METRICS * evel_new_mobile_gtp_flow_metrics(
2317                                       double avg_bit_error_rate,
2318                                       double avg_packet_delay_variation,
2319                                       int avg_packet_latency,
2320                                       int avg_receive_throughput,
2321                                       int avg_transmit_throughput,
2322                                       int flow_activation_epoch,
2323                                       int flow_activation_microsec,
2324                                       int flow_deactivation_epoch,
2325                                       int flow_deactivation_microsec,
2326                                       time_t flow_deactivation_time,
2327                                       const char * const flow_status,
2328                                       int max_packet_delay_variation,
2329                                       int num_activation_failures,
2330                                       int num_bit_errors,
2331                                       int num_bytes_received,
2332                                       int num_bytes_transmitted,
2333                                       int num_dropped_packets,
2334                                       int num_l7_bytes_received,
2335                                       int num_l7_bytes_transmitted,
2336                                       int num_lost_packets,
2337                                       int num_out_of_order_packets,
2338                                       int num_packet_errors,
2339                                       int num_packets_received_excl_retrans,
2340                                       int num_packets_received_incl_retrans,
2341                                       int num_packets_transmitted_incl_retrans,
2342                                       int num_retries,
2343                                       int num_timeouts,
2344                                       int num_tunneled_l7_bytes_received,
2345                                       int round_trip_time,
2346                                       int time_to_first_byte);
2347
2348 /**************************************************************************//**
2349  * Free a Mobile GTP Per Flow Metrics.
2350  *
2351  * Free off the Mobile GTP Per Flow Metrics supplied.  Will free all the
2352  * contained allocated memory.
2353  *
2354  * @note It does not free the Mobile GTP Per Flow Metrics itself, since that
2355  * may be part of a larger structure.
2356  *****************************************************************************/
2357 void evel_free_mobile_gtp_flow_metrics(MOBILE_GTP_PER_FLOW_METRICS * metrics);
2358
2359 /**************************************************************************//**
2360  * Set the Duration of Connection Failed Status property of the Mobile GTP Per
2361  * Flow Metrics.
2362  *
2363  * @note  The property is treated as immutable: it is only valid to call
2364  *        the setter once.  However, we don't assert if the caller tries to
2365  *        overwrite, just ignoring the update instead.
2366  *
2367  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2368  * @param duration    The Duration of Connection Failed Status to be set.
2369  *****************************************************************************/
2370 void evel_mobile_gtp_metrics_dur_con_fail_set(
2371                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2372                                          int duration);
2373
2374 /**************************************************************************//**
2375  * Set the Duration of Tunnel Failed Status property of the Mobile GTP Per Flow
2376  * Metrics.
2377  *
2378  * @note  The property is treated as immutable: it is only valid to call
2379  *        the setter once.  However, we don't assert if the caller tries to
2380  *        overwrite, just ignoring the update instead.
2381  *
2382  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2383  * @param duration    The Duration of Tunnel Failed Status to be set.
2384  *****************************************************************************/
2385 void evel_mobile_gtp_metrics_dur_tun_fail_set(
2386                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2387                                          int duration);
2388
2389 /**************************************************************************//**
2390  * Set the Activated By property of the Mobile GTP Per Flow metrics.
2391  *
2392  * @note  The property is treated as immutable: it is only valid to call
2393  *        the setter once.  However, we don't assert if the caller tries to
2394  *        overwrite, just ignoring the update instead.
2395  *
2396  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2397  * @param act_by      The Activated By to be set.  ASCIIZ string. The caller
2398  *                    does not need to preserve the value once the function
2399  *                    returns.
2400  *****************************************************************************/
2401 void evel_mobile_gtp_metrics_act_by_set(MOBILE_GTP_PER_FLOW_METRICS * metrics,
2402                                         const char * const act_by);
2403
2404 /**************************************************************************//**
2405  * Set the Activation Time property of the Mobile GTP Per Flow metrics.
2406  *
2407  * @note  The property is treated as immutable: it is only valid to call
2408  *        the setter once.  However, we don't assert if the caller tries to
2409  *        overwrite, just ignoring the update instead.
2410  *
2411  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2412  * @param act_time    The Activation Time to be set.  ASCIIZ string. The caller
2413  *                    does not need to preserve the value once the function
2414  *                    returns.
2415  *****************************************************************************/
2416 void evel_mobile_gtp_metrics_act_time_set(
2417                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2418                                          time_t act_time);
2419
2420 /**************************************************************************//**
2421  * Set the Deactivated By property of the Mobile GTP Per Flow metrics.
2422  *
2423  * @note  The property is treated as immutable: it is only valid to call
2424  *        the setter once.  However, we don't assert if the caller tries to
2425  *        overwrite, just ignoring the update instead.
2426  *
2427  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2428  * @param deact_by    The Deactivated By to be set.  ASCIIZ string. The caller
2429  *                    does not need to preserve the value once the function
2430  *                    returns.
2431  *****************************************************************************/
2432 void evel_mobile_gtp_metrics_deact_by_set(
2433                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2434                                          const char * const deact_by);
2435
2436 /**************************************************************************//**
2437  * Set the GTP Connection Status property of the Mobile GTP Per Flow metrics.
2438  *
2439  * @note  The property is treated as immutable: it is only valid to call
2440  *        the setter once.  However, we don't assert if the caller tries to
2441  *        overwrite, just ignoring the update instead.
2442  *
2443  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2444  * @param status      The GTP Connection Status to be set.  ASCIIZ string. The
2445  *                    caller does not need to preserve the value once the
2446  *                    function returns.
2447  *****************************************************************************/
2448 void evel_mobile_gtp_metrics_con_status_set(
2449                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2450                                          const char * const status);
2451
2452 /**************************************************************************//**
2453  * Set the GTP Tunnel Status property of the Mobile GTP Per Flow metrics.
2454  *
2455  * @note  The property is treated as immutable: it is only valid to call
2456  *        the setter once.  However, we don't assert if the caller tries to
2457  *        overwrite, just ignoring the update instead.
2458  *
2459  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2460  * @param status      The GTP Tunnel Status to be set.  ASCIIZ string. The
2461  *                    caller does not need to preserve the value once the
2462  *                    function returns.
2463  *****************************************************************************/
2464 void evel_mobile_gtp_metrics_tun_status_set(
2465                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2466                                          const char * const status);
2467
2468 /**************************************************************************//**
2469  * Set an IP Type-of-Service count property of the Mobile GTP Per Flow metrics.
2470  *
2471  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2472  * @param index       The index of the IP Type-of-Service.
2473  * @param count       The count.
2474  *****************************************************************************/
2475 void evel_mobile_gtp_metrics_iptos_set(MOBILE_GTP_PER_FLOW_METRICS * metrics,
2476                                        int index,
2477                                        int count);
2478
2479 /**************************************************************************//**
2480  * Set the Large Packet Round-Trip Time property of the Mobile GTP Per Flow
2481  * Metrics.
2482  *
2483  * @note  The property is treated as immutable: it is only valid to call
2484  *        the setter once.  However, we don't assert if the caller tries to
2485  *        overwrite, just ignoring the update instead.
2486  *
2487  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2488  * @param rtt         The Large Packet Round-Trip Time to be set.
2489  *****************************************************************************/
2490 void evel_mobile_gtp_metrics_large_pkt_rtt_set(
2491                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2492                                          int rtt);
2493
2494 /**************************************************************************//**
2495  * Set the Large Packet Threshold property of the Mobile GTP Per Flow Metrics.
2496  *
2497  * @note  The property is treated as immutable: it is only valid to call
2498  *        the setter once.  However, we don't assert if the caller tries to
2499  *        overwrite, just ignoring the update instead.
2500  *
2501  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2502  * @param threshold   The Large Packet Threshold to be set.
2503  *****************************************************************************/
2504 void evel_mobile_gtp_metrics_large_pkt_thresh_set(
2505                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2506                                          double threshold);
2507
2508 /**************************************************************************//**
2509  * Set the Max Receive Bit Rate property of the Mobile GTP Per Flow Metrics.
2510  *
2511  * @note  The property is treated as immutable: it is only valid to call
2512  *        the setter once.  However, we don't assert if the caller tries to
2513  *        overwrite, just ignoring the update instead.
2514  *
2515  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2516  * @param rate        The Max Receive Bit Rate to be set.
2517  *****************************************************************************/
2518 void evel_mobile_gtp_metrics_max_rcv_bit_rate_set(
2519                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2520                                          int rate);
2521
2522 /**************************************************************************//**
2523  * Set the Max Transmit Bit Rate property of the Mobile GTP Per Flow Metrics.
2524  *
2525  * @note  The property is treated as immutable: it is only valid to call
2526  *        the setter once.  However, we don't assert if the caller tries to
2527  *        overwrite, just ignoring the update instead.
2528  *
2529  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2530  * @param rate        The Max Transmit Bit Rate to be set.
2531  *****************************************************************************/
2532 void evel_mobile_gtp_metrics_max_trx_bit_rate_set(
2533                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2534                                          int rate);
2535
2536 /**************************************************************************//**
2537  * Set the Number of GTP Echo Failures property of the Mobile GTP Per Flow
2538  * Metrics.
2539  *
2540  * @note  The property is treated as immutable: it is only valid to call
2541  *        the setter once.  However, we don't assert if the caller tries to
2542  *        overwrite, just ignoring the update instead.
2543  *
2544  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2545  * @param num         The Number of GTP Echo Failures to be set.
2546  *****************************************************************************/
2547 void evel_mobile_gtp_metrics_num_echo_fail_set(
2548                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2549                                          int num);
2550
2551 /**************************************************************************//**
2552  * Set the Number of GTP Tunnel Errors property of the Mobile GTP Per Flow
2553  * Metrics.
2554  *
2555  * @note  The property is treated as immutable: it is only valid to call
2556  *        the setter once.  However, we don't assert if the caller tries to
2557  *        overwrite, just ignoring the update instead.
2558  *
2559  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2560  * @param num         The Number of GTP Tunnel Errors to be set.
2561  *****************************************************************************/
2562 void evel_mobile_gtp_metrics_num_tun_fail_set(
2563                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2564                                          int num);
2565
2566 /**************************************************************************//**
2567  * Set the Number of HTTP Errors property of the Mobile GTP Per Flow Metrics.
2568  *
2569  * @note  The property is treated as immutable: it is only valid to call
2570  *        the setter once.  However, we don't assert if the caller tries to
2571  *        overwrite, just ignoring the update instead.
2572  *
2573  * @param metrics     Pointer to the Mobile GTP Per Flow Metrics.
2574  * @param num         The Number of HTTP Errors to be set.
2575  *****************************************************************************/
2576 void evel_mobile_gtp_metrics_num_http_errors_set(
2577                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2578                                          int num);
2579
2580 /**************************************************************************//**
2581  * Add a TCP flag count to the metrics.
2582  *
2583  * @note  The property is treated as immutable: it is only valid to call
2584  *        the setter once.  However, we don't assert if the caller tries to
2585  *        overwrite, just ignoring the update instead.
2586  *
2587  * @param metrics       Pointer to the Mobile GTP Per Flow Metrics.
2588  * @param tcp_flag      The TCP flag count to be updated.
2589  * @param count         The associated flag count.
2590  *****************************************************************************/
2591 void evel_mobile_gtp_metrics_tcp_flag_count_add(
2592                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2593                                          const EVEL_TCP_FLAGS tcp_flag,
2594                                          const int count);
2595
2596 /**************************************************************************//**
2597  * Add a QCI COS count to the metrics.
2598  *
2599  * @note  The property is treated as immutable: it is only valid to call
2600  *        the setter once.  However, we don't assert if the caller tries to
2601  *        overwrite, just ignoring the update instead.
2602  *
2603  * @param metrics       Pointer to the Mobile GTP Per Flow Metrics.
2604  * @param qci_cos       The QCI COS count to be updated.
2605  * @param count         The associated QCI COS count.
2606  *****************************************************************************/
2607 void evel_mobile_gtp_metrics_qci_cos_count_add(
2608                                          MOBILE_GTP_PER_FLOW_METRICS * metrics,
2609                                          const EVEL_QCI_COS_TYPES qci_cos,
2610                                          const int count);
2611
2612 /*****************************************************************************/
2613 /*****************************************************************************/
2614 /*                                                                           */
2615 /*   SERVICE EVENTS                                                          */
2616 /*                                                                           */
2617 /*****************************************************************************/
2618 /*****************************************************************************/
2619
2620 /**************************************************************************//**
2621  * Create a new Service event.
2622  *
2623  * @note    The mandatory fields on the Service must be supplied to
2624  *          this factory function and are immutable once set.  Optional fields
2625  *          have explicit setter functions, but again values may only be set
2626  *          once so that the event has immutable properties.
2627  * @param vendor_id     The vendor id to encode in the event instance id.
2628  * @param event_id      The vendor event id to encode in the event instance id.
2629  * @returns pointer to the newly manufactured ::EVENT_SERVICE.  If the event
2630  *          is not used (i.e. posted) it must be released using
2631  *          ::evel_free_service.
2632  * @retval  NULL  Failed to create the event.
2633  *****************************************************************************/
2634 EVENT_SERVICE * evel_new_service(const char * const vendor_id,
2635                                  const char * const event_id);
2636
2637 /**************************************************************************//**
2638  * Free a Service Events event.
2639  *
2640  * Free off the event supplied.  Will free all the contained allocated memory.
2641  *
2642  * @note It does not free the event itself, since that may be part of a larger
2643  * structure.
2644  *****************************************************************************/
2645 void evel_free_service(EVENT_SERVICE * const event);
2646
2647 /**************************************************************************//**
2648  * Set the Event Type property of the Service event.
2649  *
2650  * @note  The property is treated as immutable: it is only valid to call
2651  *        the setter once.  However, we don't assert if the caller tries to
2652  *        overwrite, just ignoring the update instead.
2653  *
2654  * @param event         Pointer to the Service event.
2655  * @param type          The Event Type to be set. ASCIIZ string. The caller
2656  *                      does not need to preserve the value once the function
2657  *                      returns.
2658  *****************************************************************************/
2659 void evel_service_type_set(EVENT_SERVICE * const event,
2660                            const char * const type);
2661
2662 /**************************************************************************//**
2663  * Set the Product Id property of the Service event.
2664  *
2665  * @note  The property is treated as immutable: it is only valid to call
2666  *        the setter once.  However, we don't assert if the caller tries to
2667  *        overwrite, just ignoring the update instead.
2668  *
2669  * @param event         Pointer to the Service event.
2670  * @param product_id    The vendor product id to be set. ASCIIZ string. The
2671  *                      caller does not need to preserve the value once the
2672  *                      function returns.
2673  *****************************************************************************/
2674 void evel_service_product_id_set(EVENT_SERVICE * const event,
2675                                  const char * const product_id);
2676
2677 /**************************************************************************//**
2678  * Set the Subsystem Id property of the Service event.
2679  *
2680  * @note  The property is treated as immutable: it is only valid to call
2681  *        the setter once.  However, we don't assert if the caller tries to
2682  *        overwrite, just ignoring the update instead.
2683  *
2684  * @param event         Pointer to the Service event.
2685  * @param subsystem_id  The vendor subsystem id to be set. ASCIIZ string. The
2686  *                      caller does not need to preserve the value once the
2687  *                      function returns.
2688  *****************************************************************************/
2689 void evel_service_subsystem_id_set(EVENT_SERVICE * const event,
2690                                    const char * const subsystem_id);
2691
2692 /**************************************************************************//**
2693  * Set the Friendly Name property of the Service event.
2694  *
2695  * @note  The property is treated as immutable: it is only valid to call
2696  *        the setter once.  However, we don't assert if the caller tries to
2697  *        overwrite, just ignoring the update instead.
2698  *
2699  * @param event         Pointer to the Service event.
2700  * @param friendly_name The vendor friendly name to be set. ASCIIZ string. The
2701  *                      caller does not need to preserve the value once the
2702  *                      function returns.
2703  *****************************************************************************/
2704 void evel_service_friendly_name_set(EVENT_SERVICE * const event,
2705                                     const char * const friendly_name);
2706
2707 /**************************************************************************//**
2708  * Set the correlator property of the Service event.
2709  *
2710  * @note  The property is treated as immutable: it is only valid to call
2711  *        the setter once.  However, we don't assert if the caller tries to
2712  *        overwrite, just ignoring the update instead.
2713  *
2714  * @param event         Pointer to the Service event.
2715  * @param correlator    The correlator to be set. ASCIIZ string. The caller
2716  *                      does not need to preserve the value once the function
2717  *                      returns.
2718  *****************************************************************************/
2719 void evel_service_correlator_set(EVENT_SERVICE * const event,
2720                                  const char * const correlator);
2721
2722 /**************************************************************************//**
2723  * Set the Codec property of the Service event.
2724  *
2725  * @note  The property is treated as immutable: it is only valid to call
2726  *        the setter once.  However, we don't assert if the caller tries to
2727  *        overwrite, just ignoring the update instead.
2728  *
2729  * @param event         Pointer to the Service event.
2730  * @param codec         The codec to be set. ASCIIZ string. The caller does not
2731  *                      need to preserve the value once the function returns.
2732  *****************************************************************************/
2733 void evel_service_codec_set(EVENT_SERVICE * const event,
2734                             const char * const codec);
2735
2736 /**************************************************************************//**
2737  * Set the Callee Side Codec property of the Service event.
2738  *
2739  * @note  The property is treated as immutable: it is only valid to call
2740  *        the setter once.  However, we don't assert if the caller tries to
2741  *        overwrite, just ignoring the update instead.
2742  *
2743  * @param event         Pointer to the Service event.
2744  * @param codec         The codec to be set. ASCIIZ string. The caller does not
2745  *                      need to preserve the value once the function returns.
2746  *****************************************************************************/
2747 void evel_service_callee_codec_set(EVENT_SERVICE * const event,
2748                                    const char * const codec);
2749
2750 /**************************************************************************//**
2751  * Set the Caller Side Codec property of the Service event.
2752  *
2753  * @note  The property is treated as immutable: it is only valid to call
2754  *        the setter once.  However, we don't assert if the caller tries to
2755  *        overwrite, just ignoring the update instead.
2756  *
2757  * @param event         Pointer to the Service event.
2758  * @param codec         The codec to be set. ASCIIZ string. The caller does not
2759  *                      need to preserve the value once the function returns.
2760  *****************************************************************************/
2761 void evel_service_caller_codec_set(EVENT_SERVICE * const event,
2762                                    const char * const codec);
2763
2764 /**************************************************************************//**
2765  * Set the RTCP Data property of the Service event.
2766  *
2767  * @note  The property is treated as immutable: it is only valid to call
2768  *        the setter once.  However, we don't assert if the caller tries to
2769  *        overwrite, just ignoring the update instead.
2770  *
2771  * @param event         Pointer to the Service event.
2772  * @param rtcp_data     The RTCP Data to be set. ASCIIZ string. The caller
2773  *                      does not need to preserve the value once the function
2774  *                      returns.
2775  *****************************************************************************/
2776 void evel_service_rtcp_data_set(EVENT_SERVICE * const event,
2777                                 const char * const rtcp_data);
2778
2779 /**************************************************************************//**
2780  * Set the Adjacency Name property of the Service event.
2781  *
2782  * @note  The property is treated as immutable: it is only valid to call
2783  *        the setter once.  However, we don't assert if the caller tries to
2784  *        overwrite, just ignoring the update instead.
2785  *
2786  * @param event         Pointer to the Service event.
2787  * @param adjacency_name
2788  *                      The adjacency name to be set. ASCIIZ string. The caller
2789  *                      does not need to preserve the value once the function
2790  *                      returns.
2791  *****************************************************************************/
2792 void evel_service_adjacency_name_set(EVENT_SERVICE * const event,
2793                                      const char * const adjacency_name);
2794
2795 /**************************************************************************//**
2796  * Set the Endpoint Descriptor property of the Service event.
2797  *
2798  * @note  The property is treated as immutable: it is only valid to call
2799  *        the setter once.  However, we don't assert if the caller tries to
2800  *        overwrite, just ignoring the update instead.
2801  *
2802  * @param event         Pointer to the Service event.
2803  * @param endpoint_desc The endpoint descriptor to be set.
2804  *****************************************************************************/
2805 void evel_service_endpoint_desc_set(
2806                                 EVENT_SERVICE * const event,
2807                                 const EVEL_SERVICE_ENDPOINT_DESC endpoint_desc);
2808
2809 /**************************************************************************//**
2810  * Set the Endpoint Jitter property of the Service event.
2811  *
2812  * @note  The property is treated as immutable: it is only valid to call
2813  *        the setter once.  However, we don't assert if the caller tries to
2814  *        overwrite, just ignoring the update instead.
2815  *
2816  * @param event         Pointer to the Service event.
2817  * @param jitter        The jitter to be set.
2818  *****************************************************************************/
2819 void evel_service_endpoint_jitter_set(EVENT_SERVICE * const event,
2820                                       const int jitter);
2821
2822 /**************************************************************************//**
2823  * Set the Endpoint Rtp Octets Discarded property of the Service event.
2824  *
2825  * @note  The property is treated as immutable: it is only valid to call
2826  *        the setter once.  However, we don't assert if the caller tries to
2827  *        overwrite, just ignoring the update instead.
2828  *
2829  * @param event         Pointer to the Service event.
2830  * @param rtp_oct_disc  The discard count.
2831  *****************************************************************************/
2832 void evel_service_endpoint_rtp_oct_disc_set(EVENT_SERVICE * const event,
2833                                             const int rtp_oct_disc);
2834
2835 /**************************************************************************//**
2836  * Set the Endpoint Rtp Octets Received property of the Service event.
2837  *
2838  * @note  The property is treated as immutable: it is only valid to call
2839  *        the setter once.  However, we don't assert if the caller tries to
2840  *        overwrite, just ignoring the update instead.
2841  *
2842  * @param event         Pointer to the Service event.
2843  * @param rtp_oct_recv  The receive count.
2844  *****************************************************************************/
2845 void evel_service_endpoint_rtp_oct_recv_set(EVENT_SERVICE * const event,
2846                                             const int rtp_oct_recv);
2847
2848 /**************************************************************************//**
2849  * Set the Endpoint Rtp Octets Sent property of the Service event.
2850  *
2851  * @note  The property is treated as immutable: it is only valid to call
2852  *        the setter once.  However, we don't assert if the caller tries to
2853  *        overwrite, just ignoring the update instead.
2854  *
2855  * @param event         Pointer to the Service event.
2856  * @param rtp_oct_sent  The send count.
2857  *****************************************************************************/
2858 void evel_service_endpoint_rtp_oct_sent_set(EVENT_SERVICE * const event,
2859                                             const int rtp_oct_sent);
2860
2861 /**************************************************************************//**
2862  * Set the Endpoint Rtp Packets Discarded property of the Service event.
2863  *
2864  * @note  The property is treated as immutable: it is only valid to call
2865  *        the setter once.  However, we don't assert if the caller tries to
2866  *        overwrite, just ignoring the update instead.
2867  *
2868  * @param event         Pointer to the Service event.
2869  * @param rtp_pkt_disc  The discard count.
2870  *****************************************************************************/
2871 void evel_service_endpoint_rtp_pkt_disc_set(EVENT_SERVICE * const event,
2872                                             const int rtp_pkt_disc);
2873
2874 /**************************************************************************//**
2875  * Set the Endpoint Rtp Packets Received property of the Service event.
2876  *
2877  * @note  The property is treated as immutable: it is only valid to call
2878  *        the setter once.  However, we don't assert if the caller tries to
2879  *        overwrite, just ignoring the update instead.
2880  *
2881  * @param event         Pointer to the Service event.
2882  * @param rtp_pkt_recv  The receive count.
2883  *****************************************************************************/
2884 void evel_service_endpoint_rtp_pkt_recv_set(EVENT_SERVICE * const event,
2885                                             const int rtp_pkt_recv);
2886
2887 /**************************************************************************//**
2888  * Set the Endpoint Rtp Packets Sent property of the Service event.
2889  *
2890  * @note  The property is treated as immutable: it is only valid to call
2891  *        the setter once.  However, we don't assert if the caller tries to
2892  *        overwrite, just ignoring the update instead.
2893  *
2894  * @param event         Pointer to the Service event.
2895  * @param rtp_pkt_sent  The send count.
2896  *****************************************************************************/
2897 void evel_service_endpoint_rtp_pkt_sent_set(EVENT_SERVICE * const event,
2898                                             const int rtp_pkt_sent);
2899
2900 /**************************************************************************//**
2901  * Set the Local Jitter property of the Service event.
2902  *
2903  * @note  The property is treated as immutable: it is only valid to call
2904  *        the setter once.  However, we don't assert if the caller tries to
2905  *        overwrite, just ignoring the update instead.
2906  *
2907  * @param event         Pointer to the Service event.
2908  * @param jitter        The jitter to be set.
2909  *****************************************************************************/
2910 void evel_service_local_jitter_set(EVENT_SERVICE * const event,
2911                                    const int jitter);
2912
2913 /**************************************************************************//**
2914  * Set the Local Rtp Octets Discarded property of the Service event.
2915  *
2916  * @note  The property is treated as immutable: it is only valid to call
2917  *        the setter once.  However, we don't assert if the caller tries to
2918  *        overwrite, just ignoring the update instead.
2919  *
2920  * @param event         Pointer to the Service event.
2921  * @param rtp_oct_disc  The discard count.
2922  *****************************************************************************/
2923 void evel_service_local_rtp_oct_disc_set(EVENT_SERVICE * const event,
2924                                          const int rtp_oct_disc);
2925
2926 /**************************************************************************//**
2927  * Set the Local Rtp Octets Received property of the Service event.
2928  *
2929  * @note  The property is treated as immutable: it is only valid to call
2930  *        the setter once.  However, we don't assert if the caller tries to
2931  *        overwrite, just ignoring the update instead.
2932  *
2933  * @param event         Pointer to the Service event.
2934  * @param rtp_oct_recv  The receive count.
2935  *****************************************************************************/
2936 void evel_service_local_rtp_oct_recv_set(EVENT_SERVICE * const event,
2937                                          const int rtp_oct_recv);
2938
2939 /**************************************************************************//**
2940  * Set the Local Rtp Octets Sent property of the Service event.
2941  *
2942  * @note  The property is treated as immutable: it is only valid to call
2943  *        the setter once.  However, we don't assert if the caller tries to
2944  *        overwrite, just ignoring the update instead.
2945  *
2946  * @param event         Pointer to the Service event.
2947  * @param rtp_oct_sent  The send count.
2948  *****************************************************************************/
2949 void evel_service_local_rtp_oct_sent_set(EVENT_SERVICE * const event,
2950                                          const int rtp_oct_sent);
2951
2952 /**************************************************************************//**
2953  * Set the Local Rtp Packets Discarded property of the Service event.
2954  *
2955  * @note  The property is treated as immutable: it is only valid to call
2956  *        the setter once.  However, we don't assert if the caller tries to
2957  *        overwrite, just ignoring the update instead.
2958  *
2959  * @param event         Pointer to the Service event.
2960  * @param rtp_pkt_disc  The discard count.
2961  *****************************************************************************/
2962 void evel_service_local_rtp_pkt_disc_set(EVENT_SERVICE * const event,
2963                                          const int rtp_pkt_disc);
2964
2965 /**************************************************************************//**
2966  * Set the Local Rtp Packets Received property of the Service event.
2967  *
2968  * @note  The property is treated as immutable: it is only valid to call
2969  *        the setter once.  However, we don't assert if the caller tries to
2970  *        overwrite, just ignoring the update instead.
2971  *
2972  * @param event         Pointer to the Service event.
2973  * @param rtp_pkt_recv  The receive count.
2974  *****************************************************************************/
2975 void evel_service_local_rtp_pkt_recv_set(EVENT_SERVICE * const event,
2976                                          const int rtp_pkt_recv);
2977
2978 /**************************************************************************//**
2979  * Set the Local Rtp Packets Sent property of the Service event.
2980  *
2981  * @note  The property is treated as immutable: it is only valid to call
2982  *        the setter once.  However, we don't assert if the caller tries to
2983  *        overwrite, just ignoring the update instead.
2984  *
2985  * @param event         Pointer to the Service event.
2986  * @param rtp_pkt_sent  The send count.
2987  *****************************************************************************/
2988 void evel_service_local_rtp_pkt_sent_set(EVENT_SERVICE * const event,
2989                                          const int rtp_pkt_sent);
2990
2991 /**************************************************************************//**
2992  * Set the Mos Cqe property of the Service event.
2993  *
2994  * @note  The property is treated as immutable: it is only valid to call
2995  *        the setter once.  However, we don't assert if the caller tries to
2996  *        overwrite, just ignoring the update instead.
2997  *
2998  * @param event         Pointer to the Service event.
2999  * @param mos_cqe       The mosCqe to be set.
3000  *****************************************************************************/
3001 void evel_service_mos_cqe_set(EVENT_SERVICE * const event,
3002                               const double mos_cqe);
3003
3004 /**************************************************************************//**
3005  * Set the Packets Lost property of the Service event.
3006  *
3007  * @note  The property is treated as immutable: it is only valid to call
3008  *        the setter once.  However, we don't assert if the caller tries to
3009  *        overwrite, just ignoring the update instead.
3010  *
3011  * @param event         Pointer to the Service event.
3012  * @param packets_lost  The number of packets lost to be set.
3013  *****************************************************************************/
3014 void evel_service_packets_lost_set(EVENT_SERVICE * const event,
3015                                    const int packets_lost);
3016
3017 /**************************************************************************//**
3018  * Set the packet Loss Percent property of the Service event.
3019  *
3020  * @note  The property is treated as immutable: it is only valid to call
3021  *        the setter once.  However, we don't assert if the caller tries to
3022  *        overwrite, just ignoring the update instead.
3023  *
3024  * @param event         Pointer to the Service event.
3025  * @param packet_loss_percent
3026  *                      The packet loss in percent.
3027  *****************************************************************************/
3028 void evel_service_packet_loss_percent_set(EVENT_SERVICE * const event,
3029                                           const double packet_loss_percent);
3030
3031 /**************************************************************************//**
3032  * Set the R Factor property of the Service event.
3033  *
3034  * @note  The property is treated as immutable: it is only valid to call
3035  *        the setter once.  However, we don't assert if the caller tries to
3036  *        overwrite, just ignoring the update instead.
3037  *
3038  * @param event         Pointer to the Service event.
3039  * @param r_factor      The R Factor to be set.
3040  *****************************************************************************/
3041 void evel_service_r_factor_set(EVENT_SERVICE * const event,
3042                                const int r_factor);
3043
3044 /**************************************************************************//**
3045  * Set the Round Trip Delay property of the Service event.
3046  *
3047  * @note  The property is treated as immutable: it is only valid to call
3048  *        the setter once.  However, we don't assert if the caller tries to
3049  *        overwrite, just ignoring the update instead.
3050  *
3051  * @param event         Pointer to the Service event.
3052  * @param round_trip_delay
3053  *                      The Round trip delay to be set.
3054  *****************************************************************************/
3055 void evel_service_round_trip_delay_set(EVENT_SERVICE * const event,
3056                                        const int round_trip_delay);
3057
3058 /**************************************************************************//**
3059  * Set the Phone Number property of the Service event.
3060  *
3061  * @note  The property is treated as immutable: it is only valid to call
3062  *        the setter once.  However, we don't assert if the caller tries to
3063  *        overwrite, just ignoring the update instead.
3064  *
3065  * @param event         Pointer to the Service event.
3066  * @param phone_number  The Phone Number to be set. ASCIIZ string. The caller
3067  *                      does not need to preserve the value once the function
3068  *                      returns.
3069  *****************************************************************************/
3070 void evel_service_phone_number_set(EVENT_SERVICE * const event,
3071                                    const char * const phone_number);
3072
3073 /**************************************************************************//**
3074  * Add a name/value pair to the Service, under the additionalFields array.
3075  *
3076  * The name and value are null delimited ASCII strings.  The library takes
3077  * a copy so the caller does not have to preserve values after the function
3078  * returns.
3079  *
3080  * @param event     Pointer to the Service event.
3081  * @param name      ASCIIZ string with the field's name.  The caller does not
3082  *                  need to preserve the value once the function returns.
3083  * @param value     ASCIIZ string with the field's value.  The caller does not
3084  *                  need to preserve the value once the function returns.
3085  *****************************************************************************/
3086 void evel_service_addl_field_add(EVENT_SERVICE * const event,
3087                                  const char * const name,
3088                                  const char * const value);
3089
3090 /*****************************************************************************/
3091 /*****************************************************************************/
3092 /*                                                                           */
3093 /*   SIGNALING                                                               */
3094 /*                                                                           */
3095 /*****************************************************************************/
3096 /*****************************************************************************/
3097
3098 /**************************************************************************//**
3099  * Create a new Signaling event.
3100  *
3101  * @note    The mandatory fields on the Signaling must be supplied to
3102  *          this factory function and are immutable once set.  Optional fields
3103  *          have explicit setter functions, but again values may only be set
3104  *          once so that the event has immutable properties.
3105  * @param vendor_id     The vendor id to encode in the event instance id.
3106  * @param event_id      The vendor event id to encode in the event instance id.
3107  * @returns pointer to the newly manufactured ::EVENT_SIGNALING.  If the event
3108  *          is not used (i.e. posted) it must be released using
3109  *          ::evel_free_signaling.
3110  * @retval  NULL  Failed to create the event.
3111  *****************************************************************************/
3112 EVENT_SIGNALING * evel_new_signaling(const char * const vendor_id,
3113                                      const char * const event_id);
3114
3115 /**************************************************************************//**
3116  * Free a Signaling event.
3117  *
3118  * Free off the event supplied.  Will free all the contained allocated memory.
3119  *
3120  * @note It does not free the event itself, since that may be part of a larger
3121  * structure.
3122  *****************************************************************************/
3123 void evel_free_signaling(EVENT_SIGNALING * const event);
3124
3125 /**************************************************************************//**
3126  * Set the Event Type property of the Signaling event.
3127  *
3128  * @note  The property is treated as immutable: it is only valid to call
3129  *        the setter once.  However, we don't assert if the caller tries to
3130  *        overwrite, just ignoring the update instead.
3131  *
3132  * @param event         Pointer to the Signaling event.
3133  * @param type          The Event Type to be set. ASCIIZ string. The caller
3134  *                      does not need to preserve the value once the function
3135  *                      returns.
3136  *****************************************************************************/
3137 void evel_signaling_type_set(EVENT_SIGNALING * const event,
3138                              const char * const type);
3139
3140 /**************************************************************************//**
3141  * Set the Product Id property of the Signaling event.
3142  *
3143  * @note  The property is treated as immutable: it is only valid to call
3144  *        the setter once.  However, we don't assert if the caller tries to
3145  *        overwrite, just ignoring the update instead.
3146  *
3147  * @param event         Pointer to the Signaling event.
3148  * @param product_id    The vendor product id to be set. ASCIIZ string. The
3149  *                      caller does not need to preserve the value once the
3150  *                      function returns.
3151  *****************************************************************************/
3152 void evel_signaling_product_id_set(EVENT_SIGNALING * const event,
3153                                    const char * const product_id);
3154
3155 /**************************************************************************//**
3156  * Set the Subsystem Id property of the Signaling event.
3157  *
3158  * @note  The property is treated as immutable: it is only valid to call
3159  *        the setter once.  However, we don't assert if the caller tries to
3160  *        overwrite, just ignoring the update instead.
3161  *
3162  * @param event         Pointer to the Signaling event.
3163  * @param subsystem_id  The vendor subsystem id to be set. ASCIIZ string. The
3164  *                      caller does not need to preserve the value once the
3165  *                      function returns.
3166  *****************************************************************************/
3167 void evel_signaling_subsystem_id_set(EVENT_SIGNALING * const event,
3168                                      const char * const subsystem_id);
3169
3170 /**************************************************************************//**
3171  * Set the Friendly Name property of the Signaling event.
3172  *
3173  * @note  The property is treated as immutable: it is only valid to call
3174  *        the setter once.  However, we don't assert if the caller tries to
3175  *        overwrite, just ignoring the update instead.
3176  *
3177  * @param event         Pointer to the Signaling event.
3178  * @param friendly_name The vendor friendly name to be set. ASCIIZ string. The
3179  *                      caller does not need to preserve the value once the
3180  *                      function returns.
3181  *****************************************************************************/
3182 void evel_signaling_friendly_name_set(EVENT_SIGNALING * const event,
3183                                       const char * const friendly_name);
3184
3185 /**************************************************************************//**
3186  * Set the Correlator property of the Signaling event.
3187  *
3188  * @note  The property is treated as immutable: it is only valid to call
3189  *        the setter once.  However, we don't assert if the caller tries to
3190  *        overwrite, just ignoring the update instead.
3191  *
3192  * @param event         Pointer to the Signaling event.
3193  * @param correlator    The correlator to be set. ASCIIZ string. The caller
3194  *                      does not need to preserve the value once the function
3195  *                      returns.
3196  *****************************************************************************/
3197 void evel_signaling_correlator_set(EVENT_SIGNALING * const event,
3198                                    const char * const correlator);
3199
3200 /**************************************************************************//**
3201  * Set the Local Ip Address property of the Signaling event.
3202  *
3203  * @note  The property is treated as immutable: it is only valid to call
3204  *        the setter once.  However, we don't assert if the caller tries to
3205  *        overwrite, just ignoring the update instead.
3206  *
3207  * @param event         Pointer to the Signaling event.
3208  * @param local_ip_address
3209  *                      The Local Ip Address to be set. ASCIIZ string. The
3210  *                      caller does not need to preserve the value once the
3211  *                      function returns.
3212  *****************************************************************************/
3213 void evel_signaling_local_ip_address_set(EVENT_SIGNALING * const event,
3214                                          const char * const local_ip_address);
3215
3216 /**************************************************************************//**
3217  * Set the Local Port property of the Signaling event.
3218  *
3219  * @note  The property is treated as immutable: it is only valid to call
3220  *        the setter once.  However, we don't assert if the caller tries to
3221  *        overwrite, just ignoring the update instead.
3222  *
3223  * @param event         Pointer to the Signaling event.
3224  * @param local_port    The Local Port to be set. ASCIIZ string. The caller
3225  *                      does not need to preserve the value once the function
3226  *                      returns.
3227  *****************************************************************************/
3228 void evel_signaling_local_port_set(EVENT_SIGNALING * const event,
3229                                    const char * const local_port);
3230
3231 /**************************************************************************//**
3232  * Set the Remote Ip Address property of the Signaling event.
3233  *
3234  * @note  The property is treated as immutable: it is only valid to call
3235  *        the setter once.  However, we don't assert if the caller tries to
3236  *        overwrite, just ignoring the update instead.
3237  *
3238  * @param event         Pointer to the Signaling event.
3239  * @param remote_ip_address
3240  *                      The Remote Ip Address to be set. ASCIIZ string. The
3241  *                      caller does not need to preserve the value once the
3242  *                      function returns.
3243  *****************************************************************************/
3244 void evel_signaling_remote_ip_address_set(EVENT_SIGNALING * const event,
3245                                          const char * const remote_ip_address);
3246
3247 /**************************************************************************//**
3248  * Set the Remote Port property of the Signaling event.
3249  *
3250  * @note  The property is treated as immutable: it is only valid to call
3251  *        the setter once.  However, we don't assert if the caller tries to
3252  *        overwrite, just ignoring the update instead.
3253  *
3254  * @param event         Pointer to the Signaling event.
3255  * @param remote_port   The Remote Port to be set. ASCIIZ string. The caller
3256  *                      does not need to preserve the value once the function
3257  *                      returns.
3258  *****************************************************************************/
3259 void evel_signaling_remote_port_set(EVENT_SIGNALING * const event,
3260                                     const char * const remote_port);
3261
3262 /**************************************************************************//**
3263  * Set the Compressed SIP property of the Signaling event.
3264  *
3265  * @note  The property is treated as immutable: it is only valid to call
3266  *        the setter once.  However, we don't assert if the caller tries to
3267  *        overwrite, just ignoring the update instead.
3268  *
3269  * @param event         Pointer to the Signaling event.
3270  * @param compressed_sip
3271  *                      The Compressed SIP to be set. ASCIIZ string. The caller
3272  *                      does not need to preserve the value once the function
3273  *                      returns.
3274  *****************************************************************************/
3275 void evel_signaling_compressed_sip_set(EVENT_SIGNALING * const event,
3276                                        const char * const compressed_sip);
3277
3278 /**************************************************************************//**
3279  * Set the Summary SIP property of the Signaling event.
3280  *
3281  * @note  The property is treated as immutable: it is only valid to call
3282  *        the setter once.  However, we don't assert if the caller tries to
3283  *        overwrite, just ignoring the update instead.
3284  *
3285  * @param event         Pointer to the Signaling event.
3286  * @param summary_sip   The Summary SIP to be set. ASCIIZ string. The caller
3287  *                      does not need to preserve the value once the function
3288  *                      returns.
3289  *****************************************************************************/
3290 void evel_signaling_summary_sip_set(EVENT_SIGNALING * const event,
3291                                     const char * const summary_sip);
3292
3293 /*****************************************************************************/
3294 /*****************************************************************************/
3295 /*                                                                           */
3296 /*   STATE CHANGE                                                            */
3297 /*                                                                           */
3298 /*****************************************************************************/
3299 /*****************************************************************************/
3300
3301 /**************************************************************************//**
3302  * Create a new State Change event.
3303  *
3304  * @note    The mandatory fields on the Syslog must be supplied to this factory
3305  *          function and are immutable once set.  Optional fields have explicit
3306  *          setter functions, but again values may only be set once so that the
3307  *          Syslog has immutable properties.
3308  *
3309  * @param new_state     The new state of the reporting entity.
3310  * @param old_state     The old state of the reporting entity.
3311  * @param interface     The card or port name of the reporting entity.
3312  *
3313  * @returns pointer to the newly manufactured ::EVENT_STATE_CHANGE.  If the
3314  *          event is not used it must be released using
3315  *          ::evel_free_state_change
3316  * @retval  NULL  Failed to create the event.
3317  *****************************************************************************/
3318 EVENT_STATE_CHANGE * evel_new_state_change(const EVEL_ENTITY_STATE new_state,
3319                                            const EVEL_ENTITY_STATE old_state,
3320                                            const char * const interface);
3321
3322 /**************************************************************************//**
3323  * Free a State Change.
3324  *
3325  * Free off the State Change supplied.  Will free all the contained allocated
3326  * memory.
3327  *
3328  * @note It does not free the State Change itself, since that may be part of a
3329  * larger structure.
3330  *****************************************************************************/
3331 void evel_free_state_change(EVENT_STATE_CHANGE * const state_change);
3332
3333 /**************************************************************************//**
3334  * Set the Event Type property of the State Change.
3335  *
3336  * @note  The property is treated as immutable: it is only valid to call
3337  *        the setter once.  However, we don't assert if the caller tries to
3338  *        overwrite, just ignoring the update instead.
3339  *
3340  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
3341  * @param type          The Event Type to be set. ASCIIZ string. The caller
3342  *                      does not need to preserve the value once the function
3343  *                      returns.
3344  *****************************************************************************/
3345 void evel_state_change_type_set(EVENT_STATE_CHANGE * const state_change,
3346                                 const char * const type);
3347
3348 /**************************************************************************//**
3349  * Add an additional field name/value pair to the State Change.
3350  *
3351  * The name and value are null delimited ASCII strings.  The library takes
3352  * a copy so the caller does not have to preserve values after the function
3353  * returns.
3354  *
3355  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
3356  * @param name          ASCIIZ string with the attribute's name.  The caller
3357  *                      does not need to preserve the value once the function
3358  *                      returns.
3359  * @param value         ASCIIZ string with the attribute's value.  The caller
3360  *                      does not need to preserve the value once the function
3361  *                      returns.
3362  *****************************************************************************/
3363 void evel_state_change_addl_field_add(EVENT_STATE_CHANGE * const state_change,
3364                                       const char * const name,
3365                                       const char * const value);
3366
3367 /*****************************************************************************/
3368 /*****************************************************************************/
3369 /*                                                                           */
3370 /*   SYSLOG                                                                  */
3371 /*                                                                           */
3372 /*****************************************************************************/
3373 /*****************************************************************************/
3374
3375 /**************************************************************************//**
3376  * Create a new syslog event.
3377  *
3378  * @note    The mandatory fields on the Syslog must be supplied to this factory
3379  *          function and are immutable once set.  Optional fields have explicit
3380  *          setter functions, but again values may only be set once so that the
3381  *          Syslog has immutable properties.
3382  *
3383  * @param   event_source_type
3384  * @param   syslog_msg
3385  * @param   syslog_tag
3386  *
3387  * @returns pointer to the newly manufactured ::EVENT_SYSLOG.  If the event is
3388  *          not used it must be released using ::evel_free_syslog
3389  * @retval  NULL  Failed to create the event.
3390  *****************************************************************************/
3391 EVENT_SYSLOG * evel_new_syslog(EVEL_SOURCE_TYPES event_source_type,
3392                                const char * const syslog_msg,
3393                                const char * const syslog_tag);
3394
3395 /**************************************************************************//**
3396  * Set the Event Type property of the Syslog.
3397  *
3398  * @note  The property is treated as immutable: it is only valid to call
3399  *        the setter once.  However, we don't assert if the caller tries to
3400  *        overwrite, just ignoring the update instead.
3401  *
3402  * @param syslog      Pointer to the syslog.
3403  * @param type        The Event Type to be set. ASCIIZ string. The caller
3404  *                    does not need to preserve the value once the function
3405  *                    returns.
3406  *****************************************************************************/
3407 void evel_syslog_type_set(EVENT_SYSLOG * syslog,
3408                           const char * const type);
3409
3410 /**************************************************************************//**
3411  * Free a Syslog.
3412  *
3413  * Free off the Syslog supplied.  Will free all the contained allocated memory.
3414  *
3415  * @note It does not free the Syslog itself, since that may be part of a
3416  * larger structure.
3417  *****************************************************************************/
3418 void evel_free_syslog(EVENT_SYSLOG * event);
3419
3420 /**************************************************************************//**
3421  * Add an additional field name/value pair to the Syslog.
3422  *
3423  * The name and value are null delimited ASCII strings.  The library takes
3424  * a copy so the caller does not have to preserve values after the function
3425  * returns.
3426  *
3427  * @param syslog    Pointer to the syslog.
3428  * @param name      ASCIIZ string with the attribute's name.  The caller
3429  *                  does not need to preserve the value once the function
3430  *                  returns.
3431  * @param value     ASCIIZ string with the attribute's value.  The caller
3432  *                  does not need to preserve the value once the function
3433  *                  returns.
3434  *****************************************************************************/
3435 void evel_syslog_addl_field_add(EVENT_SYSLOG * syslog,
3436                                 char * name,
3437                                 char * value);
3438
3439 /**************************************************************************//**
3440  * Set the Event Source Host property of the Syslog.
3441  *
3442  * @note  The property is treated as immutable: it is only valid to call
3443  *        the setter once.  However, we don't assert if the caller tries to
3444  *        overwrite, just ignoring the update instead.
3445  *
3446  * @param syslog      Pointer to the Syslog.
3447  * @param host        The Event Source Host to be set.  ASCIIZ string. The
3448  *                    caller does not need to preserve the value once the
3449  *                    function returns.
3450  *****************************************************************************/
3451 void evel_syslog_event_source_host_set(EVENT_SYSLOG * syslog,
3452                                        const char * const host);
3453
3454 /**************************************************************************//**
3455  * Set the Syslog Facility property of the Syslog.
3456  *
3457  * @note  The property is treated as immutable: it is only valid to call
3458  *        the setter once.  However, we don't assert if the caller tries to
3459  *        overwrite, just ignoring the update instead.
3460  *
3461  * @param syslog      Pointer to the Syslog.
3462  * @param facility    The Syslog Facility to be set.  ASCIIZ string. The caller
3463  *                    does not need to preserve the value once the function
3464  *                    returns.
3465  *****************************************************************************/
3466 void evel_syslog_facility_set(EVENT_SYSLOG * syslog,
3467                               EVEL_SYSLOG_FACILITIES facility);
3468
3469 /**************************************************************************//**
3470  * Set the Process property of the Syslog.
3471  *
3472  * @note  The property is treated as immutable: it is only valid to call
3473  *        the setter once.  However, we don't assert if the caller tries to
3474  *        overwrite, just ignoring the update instead.
3475  *
3476  * @param syslog      Pointer to the Syslog.
3477  * @param proc        The Process to be set.  ASCIIZ string. The caller does
3478  *                    not need to preserve the value once the function returns.
3479  *****************************************************************************/
3480 void evel_syslog_proc_set(EVENT_SYSLOG * syslog, const char * const proc);
3481
3482 /**************************************************************************//**
3483  * Set the Process ID property of the Syslog.
3484  *
3485  * @note  The property is treated as immutable: it is only valid to call
3486  *        the setter once.  However, we don't assert if the caller tries to
3487  *        overwrite, just ignoring the update instead.
3488  *
3489  * @param syslog      Pointer to the Syslog.
3490  * @param proc_id     The Process ID to be set.
3491  *****************************************************************************/
3492 void evel_syslog_proc_id_set(EVENT_SYSLOG * syslog, int proc_id);
3493
3494 /**************************************************************************//**
3495  * Set the Version property of the Syslog.
3496  *
3497  * @note  The property is treated as immutable: it is only valid to call
3498  *        the setter once.  However, we don't assert if the caller tries to
3499  *        overwrite, just ignoring the update instead.
3500  *
3501  * @param syslog      Pointer to the Syslog.
3502  * @param version     The Version to be set.
3503  *****************************************************************************/
3504 void evel_syslog_version_set(EVENT_SYSLOG * syslog, int version);
3505
3506 /**************************************************************************//**
3507  * Set the Structured Data property of the Syslog.
3508  *
3509  * @note  The property is treated as immutable: it is only valid to call
3510  *        the setter once.  However, we don't assert if the caller tries to
3511  *        overwrite, just ignoring the update instead.
3512  *
3513  * @param syslog      Pointer to the Syslog.
3514  * @param s_data      The Structured Data to be set.  ASCIIZ string. The caller
3515  *                    does not need to preserve the value once the function
3516  *                    returns.
3517  *****************************************************************************/
3518 void evel_syslog_s_data_set(EVENT_SYSLOG * syslog, const char * const s_data);
3519
3520 /*****************************************************************************/
3521 /*****************************************************************************/
3522 /*                                                                           */
3523 /*   OTHER                                                                   */
3524 /*                                                                           */
3525 /*****************************************************************************/
3526 /*****************************************************************************/
3527
3528 /**************************************************************************//**
3529  * Create a new other event.
3530  *
3531  *
3532  * @returns pointer to the newly manufactured ::EVENT_OTHER.  If the event is
3533  *          not used it must be released using ::evel_free_other.
3534  * @retval  NULL  Failed to create the event.
3535  *****************************************************************************/
3536 EVENT_OTHER * evel_new_other(void);
3537
3538 /**************************************************************************//**
3539  * Free an Other.
3540  *
3541  * Free off the Other supplied.  Will free all the contained allocated memory.
3542  *
3543  * @note It does not free the Other itself, since that may be part of a
3544  * larger structure.
3545  *****************************************************************************/
3546 void evel_free_other(EVENT_OTHER * event);
3547
3548 /**************************************************************************//**
3549  * Set the Event Type property of the Other.
3550  *
3551  * @note  The property is treated as immutable: it is only valid to call
3552  *        the setter once.  However, we don't assert if the caller tries to
3553  *        overwrite, just ignoring the update instead.
3554  *
3555  * @param other       Pointer to the Other.
3556  * @param type        The Event Type to be set. ASCIIZ string. The caller
3557  *                    does not need to preserve the value once the function
3558  *                    returns.
3559  *****************************************************************************/
3560 void evel_other_type_set(EVENT_OTHER * other,
3561                          const char * const type);
3562
3563 /**************************************************************************//**
3564  * Add a value name/value pair to the Other.
3565  *
3566  * The name and value are null delimited ASCII strings.  The library takes
3567  * a copy so the caller does not have to preserve values after the function
3568  * returns.
3569  *
3570  * @param other     Pointer to the Other.
3571  * @param name      ASCIIZ string with the attribute's name.
3572  * @param value     ASCIIZ string with the attribute's value.
3573  *****************************************************************************/
3574 void evel_other_field_add(EVENT_OTHER * other,
3575                           char * name,
3576                           char * value);
3577
3578 /*****************************************************************************/
3579 /*****************************************************************************/
3580 /*                                                                           */
3581 /*   THROTTLING                                                              */
3582 /*                                                                           */
3583 /*****************************************************************************/
3584 /*****************************************************************************/
3585
3586 /**************************************************************************//**
3587  * Return the current measurement interval provided by the Event Listener.
3588  *
3589  * @returns The current measurement interval
3590  * @retval  EVEL_MEASUREMENT_INTERVAL_UKNOWN (0) - interval has not been
3591  *          specified
3592  *****************************************************************************/
3593 int evel_get_measurement_interval();
3594
3595 /*****************************************************************************/
3596 /*****************************************************************************/
3597 /*                                                                           */
3598 /*   LOGGING                                                                 */
3599 /*                                                                           */
3600 /*****************************************************************************/
3601 /*****************************************************************************/
3602
3603 /*****************************************************************************/
3604 /* Debug macros.                                                             */
3605 /*****************************************************************************/
3606 #define EVEL_DEBUG(FMT, ...)   log_debug(EVEL_LOG_DEBUG, (FMT), ##__VA_ARGS__)
3607 #define EVEL_INFO(FMT, ...)    log_debug(EVEL_LOG_INFO, (FMT), ##__VA_ARGS__)
3608 #define EVEL_SPAMMY(FMT, ...)  log_debug(EVEL_LOG_SPAMMY, (FMT), ##__VA_ARGS__)
3609 #define EVEL_ERROR(FMT, ...)   log_debug(EVEL_LOG_ERROR, "ERROR: " FMT, \
3610                                          ##__VA_ARGS__)
3611 #define EVEL_ENTER()                                                          \
3612         {                                                                     \
3613           log_debug(EVEL_LOG_DEBUG, "Enter %s {", __FUNCTION__);              \
3614           debug_indent += 2;                                                  \
3615         }
3616 #define EVEL_EXIT()                                                           \
3617         {                                                                     \
3618           debug_indent -= 2;                                                  \
3619           log_debug(EVEL_LOG_DEBUG, "Exit %s }", __FUNCTION__);               \
3620         }
3621
3622 #define INDENT_SEPARATORS                                                     \
3623         "| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | "
3624
3625 extern EVEL_LOG_LEVELS debug_level;
3626 extern int debug_indent;
3627 extern FILE * fout;
3628
3629 #define EVEL_DEBUG_ON() ((debug_level) >= EVEL_LOG_DEBUG)
3630
3631 /**************************************************************************//**
3632  * Initialize logging
3633  *
3634  * @param[in] level  The debugging level - one of ::EVEL_LOG_LEVELS.
3635  * @param[in] ident  The identifier for our logs.
3636  *****************************************************************************/
3637 void log_initialize(EVEL_LOG_LEVELS level, const char * ident);
3638
3639 /**************************************************************************//**
3640  * Log debug information
3641  *
3642  * Logs debugging information in a platform independent manner.
3643  *
3644  * @param[in] level   The debugging level - one of ::EVEL_LOG_LEVELS.
3645  * @param[in] format  Log formatting string in printf format.
3646  * @param[in] ...     Variable argument list.
3647  *****************************************************************************/
3648 void log_debug(EVEL_LOG_LEVELS level, char * format, ...);
3649
3650 /***************************************************************************//*
3651  * Store the formatted string into the static error string and log the error.
3652  *
3653  * @param format  Error string in standard printf format.
3654  * @param ...     Variable parameters to be substituted into the format string.
3655  *****************************************************************************/
3656 void log_error_state(char * format, ...);
3657
3658 #ifdef __cplusplus
3659 }
3660 #endif
3661
3662 #endif