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