vnfs/VESreporting_vFW5.0_DANOS/evel/evel-library/code/evel_library/evel_internal.h

   1 /*************************************************************************//**
   2  *
   3  * Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  *
  16  ****************************************************************************/
  17 /**************************************************************************//**
  18  * @file
  19  * EVEL internal definitions.
  20  *
  21  * These are internal definitions which need to be shared between modules
  22  * within the library but are not intended for external consumption.
  23  *
  24  ****************************************************************************/
  25
  26 #ifndef EVEL_INTERNAL_INCLUDED
  27 #define EVEL_INTERNAL_INCLUDED
  28
  29 #include "evel.h"
  30
  31 /*****************************************************************************/
  32 /* Define some type-safe min/max macros.                                     */
  33 /*****************************************************************************/
  34 #define max(a,b) \
  35    ({ __typeof__ (a) _a = (a); \
  36        __typeof__ (b) _b = (b); \
  37      _a > _b ? _a : _b; })
  38
  39 #define min(a,b) \
  40    ({ __typeof__ (a) _a = (a); \
  41        __typeof__ (b) _b = (b); \
  42      _a < _b ? _a : _b; })
  43
  44
  45 /**************************************************************************//**
  46  * Compile-time assertion.
  47  *****************************************************************************/
  48 #define EVEL_CT_ASSERT(X) switch (0) {case 0: case (X):;}
  49
  50 /**************************************************************************//**
  51  * The Functional Role of the equipment represented by this VNF.
  52  *****************************************************************************/
  53 extern char * functional_role;
  54
  55 /**************************************************************************//**
  56  * The type of equipment represented by this VNF.
  57  *****************************************************************************/
  58 extern EVEL_SOURCE_TYPES event_source_type;
  59
  60 /**************************************************************************//**
  61  * A chunk of memory used in the cURL functions.
  62  *****************************************************************************/
  63 typedef struct memory_chunk {
  64   char * memory;
  65   size_t size;
  66 } MEMORY_CHUNK;
  67
  68 /**************************************************************************//**
  69  * Global commands that may be sent to the Event Handler thread.
  70  *****************************************************************************/
  71 typedef enum {
  72   EVT_CMD_TERMINATE,
  73   EVT_CMD_MAX_COMMANDS
  74 } EVT_HANDLER_COMMAND;
  75
  76 /**************************************************************************//**
  77  * State of the Event Handler thread.
  78  *****************************************************************************/
  79 typedef enum {
  80   EVT_HANDLER_UNINITIALIZED,      /** The library cannot handle events.      */
  81   EVT_HANDLER_INACTIVE,           /** The event handler thread not started.  */
  82   EVT_HANDLER_ACTIVE,             /** The event handler thread is started.   */
  83   EVT_HANDLER_REQUEST_TERMINATE,  /** Initial stages of shutdown.            */
  84   EVT_HANDLER_TERMINATING,        /** The ring-buffer is being depleted.     */
  85   EVT_HANDLER_TERMINATED,         /** The library is exited.                 */
  86   EVT_HANDLER_MAX_STATES          /** Maximum number of valid states.        */
  87 } EVT_HANDLER_STATE;
  88
  89 /**************************************************************************//**
  90  * Internal event.
  91  * Pseudo-event used for routing internal commands.
  92  *****************************************************************************/
  93 typedef struct event_internal {
  94   EVENT_HEADER header;
  95   EVT_HANDLER_COMMAND command;
  96 } EVENT_INTERNAL;
  97
  98 /**************************************************************************//**
  99  * Suppressed NV pairs list entry.
 100  * JSON equivalent field: suppressedNvPairs
 101  *****************************************************************************/
 102 typedef struct evel_suppressed_nv_pairs {
 103
 104   /***************************************************************************/
 105   /* Mandatory fields                                                        */
 106   /* JSON equivalent field: nvPairFieldName                                  */
 107   /***************************************************************************/
 108   char * nv_pair_field_name;
 109
 110   /***************************************************************************/
 111   /* Optional fields                                                         */
 112   /* JSON equivalent field: suppressedNvPairNames                            */
 113   /* Type of each list entry: char *                                         */
 114   /***************************************************************************/
 115   DLIST suppressed_nv_pair_names;
 116
 117   /***************************************************************************/
 118   /* Hash table containing suppressed_nv_pair_names as keys.                 */
 119   /***************************************************************************/
 120   struct hsearch_data * hash_nv_pair_names;
 121
 122 } EVEL_SUPPRESSED_NV_PAIRS;
 123
 124 /**************************************************************************//**
 125  * Event Throttling Specification for a domain which is in a throttled state.
 126  * JSON equivalent object: eventThrottlingState
 127  *****************************************************************************/
 128 typedef struct evel_throttle_spec {
 129
 130   /***************************************************************************/
 131   /* List of field names to be suppressed.                                   */
 132   /* JSON equivalent field: suppressedFieldNames                             */
 133   /* Type of each list entry: char *                                         */
 134   /***************************************************************************/
 135   DLIST suppressed_field_names;
 136
 137   /***************************************************************************/
 138   /* List of name-value pairs to be suppressed.                              */
 139   /* JSON equivalent field: suppressedNvPairsList                            */
 140   /* Type of each list entry: EVEL_SUPPRESSED_NV_PAIRS *                     */
 141   /***************************************************************************/
 142   DLIST suppressed_nv_pairs_list;
 143
 144   /***************************************************************************/
 145   /* Hash table containing suppressed_nv_pair_names as keys.                 */
 146   /***************************************************************************/
 147   struct hsearch_data * hash_field_names;
 148
 149   /***************************************************************************/
 150   /* Hash table containing nv_pair_field_name as keys, and                   */
 151   /* suppressed_nv_pairs_list as values.                                     */
 152   /***************************************************************************/
 153   struct hsearch_data * hash_nv_pairs_list;
 154
 155 } EVEL_THROTTLE_SPEC;
 156
 157 /*****************************************************************************/
 158 /* RFC2822 format string for strftime.                                       */
 159 /*****************************************************************************/
 160 #define EVEL_RFC2822_STRFTIME_FORMAT "%a, %d %b %Y %T %z"
 161
 162 /*****************************************************************************/
 163 /* EVEL_JSON_BUFFER depth at which we throttle fields.                       */
 164 /*****************************************************************************/
 165 #define EVEL_THROTTLE_FIELD_DEPTH 3
 166
 167 /**************************************************************************//**
 168  * Initialize the event handler.
 169  *
 170  * Primarily responsible for getting cURL ready for use.
 171  *
 172  * @param[in] event_api_url
 173  *                      The URL where the Vendor Event Listener API is expected
 174  *                      to be.
 175  * @param[in] bakup_api_url
 176  *                      The BakupURL where the Vendor Backup Listener is expected
 177  *                      to be.
 178  * @param[in] throt_api_url
 179  *                      The URL where the Throttling API is expected to be.
 180  * @param[in] source_ip        Source IP of VES Agent
 181  * @param[in] bakup_source_ip  Backup Source IP of VES Agent
 182  * @param[in] ring_buf_size    Initialization size of Ring Buffer
 183  * @param[in] secure     Whether Using http or https
 184  * @param[in] cert_file_path  Path to Client Certificate file
 185  * @param[in] key_file_path   Path to Client key file
 186  * @param[in] ca_info         Path to CA info file
 187  * @param[in] ca_file_path    Path to CA file
 188  * @param[in] verify_peer     Using peer verification or not
 189  * @param[in] verify_host     Using host verification or not
 190  * @param[in] username  The username for the Basic Authentication of requests.
 191  * @param[in] password  The password for the Basic Authentication of requests.
 192  * @param[in] username2  The username for the Bakup requests.
 193  * @param[in] password2  The password for the Bakup requests.
 194  * @param     verbosity 0 for normal operation, positive values for chattier
 195  *                        logs.
 196  *****************************************************************************/
 197 EVEL_ERR_CODES event_handler_initialize(const char * const event_api_url,
 198                                         const char * const bakup_api_url,
 199                                         const char * const throt_api_url,
 200                                         const char * const source_ip,
 201                                         const char * const bakup_source_ip,
 202                                         int ring_buf_size,
 203                                         int secure,
 204                                         const char * const cert_file_path,
 205                                         const char * const key_file_path,
 206                                         const char * const ca_info,
 207                                         const char * const ca_file_path,
 208                                         long verify_peer,
 209                                         long verify_host,
 210                                         const char * const username,
 211                                         const char * const password,
 212                                         const char * const username2,
 213                                         const char * const password2,
 214                                         int verbosity);
 215
 216 /**************************************************************************//**
 217  * Terminate the event handler.
 218  *
 219  * Shuts down the event handler thread in as clean a way as possible. Sets the
 220  * global exit flag and then signals the thread to interrupt it since it's
 221  * most likely waiting on the ring-buffer.
 222  *
 223  * Having achieved an orderly shutdown of the event handler thread, clean up
 224  * the cURL library's resources cleanly.
 225  *
 226  *  @return Status code.
 227  *  @retval ::EVEL_SUCCESS if everything OK.
 228  *  @retval One of ::EVEL_ERR_CODES if there was a problem.
 229  *****************************************************************************/
 230 EVEL_ERR_CODES event_handler_terminate();
 231
 232 /**************************************************************************//**
 233  * Run the event handler.
 234  *
 235  * Spawns the thread responsible for handling events and sending them to the
 236  * API.
 237  *
 238  *  @return Status code.
 239  *  @retval ::EVEL_SUCCESS if everything OK.
 240  *  @retval One of ::EVEL_ERR_CODES if there was a problem.
 241  *****************************************************************************/
 242 EVEL_ERR_CODES event_handler_run();
 243
 244 /**************************************************************************//**
 245  * Create a new internal event.
 246  *
 247  * @note    The mandatory fields on the Fault must be supplied to this factory
 248  *          function and are immutable once set.  Optional fields have explicit
 249  *          setter functions, but again values may only be set once so that the
 250  *          Fault has immutable properties.
 251  * @param   command   The condition indicated by the event.
 252  * @returns pointer to the newly manufactured ::EVENT_INTERNAL.  If the event
 253  *          is not used (i.e. posted) it must be released using
 254  *          ::evel_free_event.
 255  * @retval  NULL  Failed to create the event.
 256  *****************************************************************************/
 257 EVENT_INTERNAL * evel_new_internal_event(EVT_HANDLER_COMMAND command,const char* ev_name, const char *ev_id);
 258
 259 /**************************************************************************//**
 260  * Free an internal event.
 261  *
 262  * Free off the event supplied.  Will free all the contained* allocated memory.
 263  *
 264  * @note It does not free the internal event itself, since that may be part of
 265  * a larger structure.
 266  *****************************************************************************/
 267 void evel_free_internal_event(EVENT_INTERNAL * event);
 268
 269 /*****************************************************************************/
 270 /* Structure to hold JSON buffer and associated tracking, as it is written.  */
 271 /*****************************************************************************/
 272 typedef struct evel_json_buffer
 273 {
 274   char * json;
 275   int offset;
 276   int max_size;
 277
 278   /***************************************************************************/
 279   /* The working throttle specification, which can be NULL.                  */
 280   /***************************************************************************/
 281   EVEL_THROTTLE_SPEC * throttle_spec;
 282
 283   /***************************************************************************/
 284   /* Current object/list nesting depth.                                      */
 285   /***************************************************************************/
 286   int depth;
 287
 288   /***************************************************************************/
 289   /* The checkpoint.                                                         */
 290   /***************************************************************************/
 291   int checkpoint;
 292
 293 } EVEL_JSON_BUFFER;
 294
 295 /**************************************************************************//**
 296  * Encode the event as a JSON event object according to AT&T's schema.
 297  *
 298  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 299  * @param event         Pointer to the ::EVENT_HEADER to encode.
 300  *****************************************************************************/
 301 void evel_json_encode_header(EVEL_JSON_BUFFER * jbuf,
 302                              EVENT_HEADER * event);
 303
 304 /**************************************************************************//**
 305  * Encode the fault in JSON according to AT&T's schema for the fault type.
 306  *
 307  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 308  * @param event         Pointer to the ::EVENT_HEADER to encode.
 309  *****************************************************************************/
 310 void evel_json_encode_fault(EVEL_JSON_BUFFER * jbuf,
 311                             EVENT_FAULT * event);
 312
 313 /**************************************************************************//**
 314  * Encode the measurement as a JSON measurement.
 315  *
 316  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 317  * @param event         Pointer to the ::EVENT_HEADER to encode.
 318  *****************************************************************************/
 319 void evel_json_encode_measurement(EVEL_JSON_BUFFER * jbuf,
 320                                   EVENT_MEASUREMENT * event);
 321
 322 /**************************************************************************//**
 323  * Encode the Mobile Flow in JSON according to AT&T's schema for the event
 324  * type.
 325  *
 326  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 327  * @param event         Pointer to the ::EVENT_HEADER to encode.
 328  *****************************************************************************/
 329 void evel_json_encode_mobile_flow(EVEL_JSON_BUFFER * jbuf,
 330                                   EVENT_MOBILE_FLOW * event);
 331
 332 /**************************************************************************//**
 333  * Encode the report as a JSON report.
 334  *
 335  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 336  * @param event         Pointer to the ::EVENT_HEADER to encode.
 337  *****************************************************************************/
 338 void evel_json_encode_report(EVEL_JSON_BUFFER * jbuf,
 339                              EVENT_REPORT * event);
 340
 341 /**************************************************************************//**
 342  * Encode the Heartbeat fields in JSON according to AT&T's schema for the
 343  * event type.
 344  *
 345  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 346  * @param event         Pointer to the ::EVENT_HEADER to encode.
 347  *****************************************************************************/
 348 void evel_json_encode_hrtbt_field(EVEL_JSON_BUFFER * const jbuf,
 349                                 EVENT_HEARTBEAT_FIELD * const event);
 350
 351 /**************************************************************************//**
 352  * Encode the Signaling in JSON according to AT&T's schema for the event type.
 353  *
 354  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 355  * @param event         Pointer to the ::EVENT_HEADER to encode.
 356  *****************************************************************************/
 357 void evel_json_encode_signaling(EVEL_JSON_BUFFER * const jbuf,
 358                                 EVENT_SIGNALING * const event);
 359
 360 /**************************************************************************//**
 361  * Encode the state change as a JSON state change.
 362  *
 363  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 364  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 365  *****************************************************************************/
 366 void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
 367                                    EVENT_STATE_CHANGE * state_change);
 368
 369 /**************************************************************************//**
 370  * Encode the Syslog in JSON according to AT&T's schema for the event type.
 371  *
 372  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 373  * @param event         Pointer to the ::EVENT_HEADER to encode.
 374  *****************************************************************************/
 375 void evel_json_encode_syslog(EVEL_JSON_BUFFER * jbuf,
 376                              EVENT_SYSLOG * event);
 377
 378 /**************************************************************************//**
 379  * Encode the Other in JSON according to AT&T's schema for the event type.
 380  *
 381  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 382  * @param event         Pointer to the ::EVENT_HEADER to encode.
 383  *****************************************************************************/
 384 void evel_json_encode_other(EVEL_JSON_BUFFER * jbuf,
 385                             EVENT_OTHER * event);
 386
 387 /**************************************************************************//**
 388  * Set the next event_sequence to use.
 389  *
 390  * @param sequence      The next sequence number to use.
 391  *****************************************************************************/
 392 void evel_set_next_event_sequence(const int sequence);
 393
 394 /**************************************************************************//**
 395  * Handle a JSON response from the listener, contained in a ::MEMORY_CHUNK.
 396  *
 397  * Tokenize the response, and decode any tokens found.
 398  *
 399  * @param chunk         The memory chunk containing the response.
 400  * @param post          The memory chunk in which to place any resulting POST.
 401  *****************************************************************************/
 402 void evel_handle_event_response(const MEMORY_CHUNK * const chunk,
 403                                 MEMORY_CHUNK * const post);
 404
 405 /**************************************************************************//**
 406  * Initialize a ::EVEL_JSON_BUFFER.
 407  *
 408  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to initialise.
 409  * @param json          Pointer to the underlying working buffer to use.
 410  * @param max_size      Size of storage available in the JSON buffer.
 411  * @param throttle_spec Pointer to throttle specification. Can be NULL.
 412  *****************************************************************************/
 413 void evel_json_buffer_init(EVEL_JSON_BUFFER * jbuf,
 414                            char * const json,
 415                            const int max_size,
 416                            EVEL_THROTTLE_SPEC * throttle_spec);
 417
 418 /**************************************************************************//**
 419  * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 420  *
 421  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 422  * @param key           Pointer to the key to encode.
 423  * @param option        Pointer to holder of the corresponding value to encode.
 424  * @return true if the key, value was added, false if it was suppressed.
 425  *****************************************************************************/
 426 bool evel_enc_kv_opt_string(EVEL_JSON_BUFFER * jbuf,
 427                             const char * const key,
 428                             const EVEL_OPTION_STRING * const option);
 429
 430 /**************************************************************************//**
 431  * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 432  *
 433  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 434  * @param key           Pointer to the key to encode.
 435  * @param value         Pointer to the corresponding value to encode.
 436  *****************************************************************************/
 437 void evel_enc_kv_string(EVEL_JSON_BUFFER * jbuf,
 438                         const char * const key,
 439                         const char * const value);
 440
 441 /**************************************************************************//**
 442  * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 443  *
 444  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 445  * @param key           Pointer to the key to encode.
 446  * @param option        Pointer to holder of the corresponding value to encode.
 447  * @return true if the key, value was added, false if it was suppressed.
 448  *****************************************************************************/
 449 bool evel_enc_kv_opt_int(EVEL_JSON_BUFFER * jbuf,
 450                          const char * const key,
 451                          const EVEL_OPTION_INT * const option);
 452
 453 /**************************************************************************//**
 454  * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 455  *
 456  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 457  * @param key           Pointer to the key to encode.
 458  * @param value         The corresponding value to encode.
 459  *****************************************************************************/
 460 void evel_enc_kv_int(EVEL_JSON_BUFFER * jbuf,
 461                      const char * const key,
 462                      const int value);
 463
 464 /**************************************************************************//**
 465  * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 466  *
 467  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 468  * @param key           Pointer to the key to encode.
 469  * @param option        Pointer to holder of the corresponding value to encode.
 470  * @return true if the key, value was added, false if it was suppressed.
 471  *****************************************************************************/
 472 bool evel_enc_kv_opt_double(EVEL_JSON_BUFFER * jbuf,
 473                             const char * const key,
 474                             const EVEL_OPTION_DOUBLE * const option);
 475
 476 /**************************************************************************//**
 477  * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 478  *
 479  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 480  * @param key           Pointer to the key to encode.
 481  * @param value         The corresponding value to encode.
 482  *****************************************************************************/
 483 void evel_enc_kv_double(EVEL_JSON_BUFFER * jbuf,
 484                         const char * const key,
 485                         const double value);
 486
 487 /**************************************************************************//**
 488  * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 489  *
 490  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 491  * @param key           Pointer to the key to encode.
 492  * @param option        Pointer to holder of the corresponding value to encode.
 493  * @return true if the key, value was added, false if it was suppressed.
 494  *****************************************************************************/
 495 bool evel_enc_kv_opt_ull(EVEL_JSON_BUFFER * jbuf,
 496                          const char * const key,
 497                          const EVEL_OPTION_ULL * const option);
 498
 499 /**************************************************************************//**
 500  * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 501  *
 502  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 503  * @param key           Pointer to the key to encode.
 504  * @param value         The corresponding value to encode.
 505  *****************************************************************************/
 506 void evel_enc_kv_ull(EVEL_JSON_BUFFER * jbuf,
 507                      const char * const key,
 508                      const unsigned long long value);
 509
 510 /**************************************************************************//**
 511  * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 512  *
 513  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 514  * @param key           Pointer to the key to encode.
 515  * @param option        Pointer to holder of the corresponding value to encode.
 516  * @return true if the key, value was added, false if it was suppressed.
 517  *****************************************************************************/
 518 bool evel_enc_kv_opt_time(EVEL_JSON_BUFFER * jbuf,
 519                           const char * const key,
 520                           const EVEL_OPTION_TIME * const option);
 521
 522 /**************************************************************************//**
 523  * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 524  *
 525  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 526  * @param key           Pointer to the key to encode.
 527  * @param time          Pointer to the time to encode.
 528  *****************************************************************************/
 529 void evel_enc_kv_time(EVEL_JSON_BUFFER * jbuf,
 530                       const char * const key,
 531                       const time_t * time);
 532
 533 /**************************************************************************//**
 534  * Encode a key and version.
 535  *
 536  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 537  * @param key           Pointer to the key to encode.
 538  * @param major_version The major version to encode.
 539  * @param minor_version The minor version to encode.
 540  *****************************************************************************/
 541 void evel_enc_version(EVEL_JSON_BUFFER * jbuf,
 542                       const char * const key,
 543                       const int major_version,
 544                       const int minor_version);
 545
 546 /**************************************************************************//**
 547  * Add the key and opening bracket of an optional named list to a JSON buffer.
 548  *
 549  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 550  * @param key           Pointer to the key to encode.
 551  * @return true if the list was opened, false if it was suppressed.
 552  *****************************************************************************/
 553 bool evel_json_open_opt_named_list(EVEL_JSON_BUFFER * jbuf,
 554                                    const char * const key);
 555
 556 /**************************************************************************//**
 557  * Add the key and opening bracket of a named list to a JSON buffer.
 558  *
 559  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 560  * @param key           Pointer to the key to encode.
 561  *****************************************************************************/
 562 void evel_json_open_named_list(EVEL_JSON_BUFFER * jbuf,
 563                                const char * const key);
 564
 565 /**************************************************************************//**
 566  * Add the closing bracket of a list to a JSON buffer.
 567  *
 568  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 569  *****************************************************************************/
 570 void evel_json_close_list(EVEL_JSON_BUFFER * jbuf);
 571
 572 /**************************************************************************//**
 573  * Encode a list item with format and param list to a ::EVEL_JSON_BUFFER.
 574  *
 575  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 576  * @param format        Format string in standard printf format.
 577  * @param ...           Variable parameters for format string.
 578  *****************************************************************************/
 579 void evel_enc_list_item(EVEL_JSON_BUFFER * jbuf,
 580                         const char * const format,
 581                         ...);
 582
 583 /**************************************************************************//**
 584  * Add the opening bracket of an optional named object to a JSON buffer.
 585  *
 586  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 587  * @param key           Pointer to the key to encode.
 588  *****************************************************************************/
 589 bool evel_json_open_opt_named_object(EVEL_JSON_BUFFER * jbuf,
 590                                      const char * const key);
 591
 592 /**************************************************************************//**
 593  * Add the opening bracket of an object to a JSON buffer.
 594  *
 595  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 596  * @param key           Pointer to the key to encode.
 597  * @return true if the object was opened, false if it was suppressed.
 598  *****************************************************************************/
 599 void evel_json_open_named_object(EVEL_JSON_BUFFER * jbuf,
 600                                  const char * const key);
 601
 602 /**************************************************************************//**
 603  * Add the opening bracket of an object to a JSON buffer.
 604  *
 605  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 606  *****************************************************************************/
 607 void evel_json_open_object(EVEL_JSON_BUFFER * jbuf);
 608
 609 /**************************************************************************//**
 610  * Add the closing bracket of an object to a JSON buffer.
 611  *
 612  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 613  *****************************************************************************/
 614 void evel_json_close_object(EVEL_JSON_BUFFER * jbuf);
 615
 616 /**************************************************************************//**
 617  * Add a checkpoint - a stake in the ground to which we can rewind.
 618  *
 619  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 620  *****************************************************************************/
 621 void evel_json_checkpoint(EVEL_JSON_BUFFER * jbuf);
 622
 623 /**************************************************************************//**
 624  * Rewind to the latest checkoint.
 625  *
 626  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 627  *****************************************************************************/
 628 void evel_json_rewind(EVEL_JSON_BUFFER * jbuf);
 629
 630 /**************************************************************************//**
 631  * Free the underlying resources of an ::EVEL_OPTION_STRING.
 632  *
 633  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 634  *****************************************************************************/
 635 void evel_free_option_string(EVEL_OPTION_STRING * const option);
 636
 637 /**************************************************************************//**
 638  * Initialize an ::EVEL_OPTION_STRING to a not-set state.
 639  *
 640  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 641  *****************************************************************************/
 642 void evel_init_option_string(EVEL_OPTION_STRING * const option);
 643
 644 /**************************************************************************//**
 645  * Set the value of an ::EVEL_OPTION_STRING.
 646  *
 647  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 648  * @param value         The value to set.
 649  * @param description   Description to be used in logging.
 650  *****************************************************************************/
 651 void evel_set_option_string(EVEL_OPTION_STRING * const option,
 652                             const char * const value,
 653                             const char * const description);
 654
 655 /**************************************************************************//**
 656  * Force the value of an ::EVEL_OPTION_STRING.
 657  *
 658  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 659  * @param value         The value to set.
 660  *****************************************************************************/
 661 void evel_force_option_string(EVEL_OPTION_STRING * const option,
 662                               const char * const value);
 663
 664 /**************************************************************************//**
 665  * Initialize an ::EVEL_OPTION_INT to a not-set state.
 666  *
 667  * @param option        Pointer to the ::EVEL_OPTION_INT.
 668  *****************************************************************************/
 669 void evel_init_option_int(EVEL_OPTION_INT * const option);
 670
 671 /**************************************************************************//**
 672  * Force the value of an ::EVEL_OPTION_INT.
 673  *
 674  * @param option        Pointer to the ::EVEL_OPTION_INT.
 675  * @param value         The value to set.
 676  *****************************************************************************/
 677 void evel_force_option_int(EVEL_OPTION_INT * const option,
 678                            const int value);
 679
 680 /**************************************************************************//**
 681  * Set the value of an ::EVEL_OPTION_INT.
 682  *
 683  * @param option        Pointer to the ::EVEL_OPTION_INT.
 684  * @param value         The value to set.
 685  * @param description   Description to be used in logging.
 686  *****************************************************************************/
 687 void evel_set_option_int(EVEL_OPTION_INT * const option,
 688                          const int value,
 689                          const char * const description);
 690
 691 /**************************************************************************//**
 692  * Initialize an ::EVEL_OPTION_DOUBLE to a not-set state.
 693  *
 694  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 695  *****************************************************************************/
 696 void evel_init_option_double(EVEL_OPTION_DOUBLE * const option);
 697
 698 /**************************************************************************//**
 699  * Force the value of an ::EVEL_OPTION_DOUBLE.
 700  *
 701  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 702  * @param value         The value to set.
 703  *****************************************************************************/
 704 void evel_force_option_double(EVEL_OPTION_DOUBLE * const option,
 705                               const double value);
 706
 707 /**************************************************************************//**
 708  * Set the value of an ::EVEL_OPTION_DOUBLE.
 709  *
 710  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 711  * @param value         The value to set.
 712  * @param description   Description to be used in logging.
 713  *****************************************************************************/
 714 void evel_set_option_double(EVEL_OPTION_DOUBLE * const option,
 715                             const double value,
 716                             const char * const description);
 717
 718 /**************************************************************************//**
 719  * Initialize an ::EVEL_OPTION_ULL to a not-set state.
 720  *
 721  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 722  *****************************************************************************/
 723 void evel_init_option_ull(EVEL_OPTION_ULL * const option);
 724
 725 /**************************************************************************//**
 726  * Force the value of an ::EVEL_OPTION_ULL.
 727  *
 728  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 729  * @param value         The value to set.
 730  *****************************************************************************/
 731 void evel_force_option_ull(EVEL_OPTION_ULL * const option,
 732                            const unsigned long long value);
 733
 734 /**************************************************************************//**
 735  * Set the value of an ::EVEL_OPTION_ULL.
 736  *
 737  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 738  * @param value         The value to set.
 739  * @param description   Description to be used in logging.
 740  *****************************************************************************/
 741 void evel_set_option_ull(EVEL_OPTION_ULL * const option,
 742                          const unsigned long long value,
 743                          const char * const description);
 744
 745 /**************************************************************************//**
 746  * Initialize an ::EVEL_OPTION_TIME to a not-set state.
 747  *
 748  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 749  *****************************************************************************/
 750 void evel_init_option_time(EVEL_OPTION_TIME * const option);
 751
 752 /**************************************************************************//**
 753  * Force the value of an ::EVEL_OPTION_TIME.
 754  *
 755  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 756  * @param value         The value to set.
 757  *****************************************************************************/
 758 void evel_force_option_time(EVEL_OPTION_TIME * const option,
 759                             const time_t value);
 760
 761 /**************************************************************************//**
 762  * Set the value of an ::EVEL_OPTION_TIME.
 763  *
 764  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 765  * @param value         The value to set.
 766  * @param description   Description to be used in logging.
 767  *****************************************************************************/
 768 void evel_set_option_time(EVEL_OPTION_TIME * const option,
 769                           const time_t value,
 770                           const char * const description);
 771
 772 /**************************************************************************//**
 773  * Map an ::EVEL_COUNTER_CRITICALITIES enum value to the equivalent string.
 774  *
 775  * @param criticality   The criticality to convert.
 776  * @returns The equivalent string.
 777  *****************************************************************************/
 778 char * evel_criticality(const EVEL_COUNTER_CRITICALITIES criticality);
 779
 780 /**************************************************************************//**
 781  * Map an ::EVEL_SEVERITIES enum value to the equivalent string.
 782  *
 783  * @param severity      The severity to convert.
 784  * @returns The equivalent string.
 785  *****************************************************************************/
 786 char * evel_severity(const EVEL_SEVERITIES severity);
 787
 788 /**************************************************************************//**
 789  * Map an ::EVEL_ALERT_ACTIONS enum value to the equivalent string.
 790  *
 791  * @param alert_action  The alert_action to convert.
 792  * @returns The equivalent string.
 793  *****************************************************************************/
 794 char * evel_alert_action(const EVEL_ALERT_ACTIONS alert_action);
 795
 796 /**************************************************************************//**
 797  * Map an ::EVEL_ALERT_TYPES enum value to the equivalent string.
 798  *
 799  * @param alert_type    The alert_type to convert.
 800  * @returns The equivalent string.
 801  *****************************************************************************/
 802 char * evel_alert_type(const EVEL_ALERT_TYPES alert_type);
 803
 804 /**************************************************************************//**
 805  * Map an ::EVEL_EVENT_DOMAINS enum value to the equivalent string.
 806  *
 807  * @param domain        The domain to convert.
 808  * @returns The equivalent string.
 809  *****************************************************************************/
 810 char * evel_event_domain(const EVEL_EVENT_DOMAINS domain);
 811
 812 /**************************************************************************//**
 813  * Map an ::EVEL_EVENT_PRIORITIES enum value to the equivalent string.
 814  *
 815  * @param priority      The priority to convert.
 816  * @returns The equivalent string.
 817  *****************************************************************************/
 818 char * evel_event_priority(const EVEL_EVENT_PRIORITIES priority);
 819
 820 /**************************************************************************//**
 821  * Map an ::EVEL_SOURCE_TYPES enum value to the equivalent string.
 822  *
 823  * @param source_type   The source type to convert.
 824  * @returns The equivalent string.
 825  *****************************************************************************/
 826 char * evel_source_type(const EVEL_SOURCE_TYPES source_type);
 827
 828 /**************************************************************************//**
 829  * Map an ::EVEL_VF_STATUSES enum value to the equivalent string.
 830  *
 831  * @param vf_status     The vf_status to convert.
 832  * @returns The equivalent string.
 833  *****************************************************************************/
 834 char * evel_vf_status(const EVEL_VF_STATUSES vf_status);
 835
 836 /**************************************************************************//**
 837  * Convert a ::EVEL_ENTITY_STATE to it's string form for JSON encoding.
 838  *
 839  * @param state         The entity state to encode.
 840  *
 841  * @returns the corresponding string
 842  *****************************************************************************/
 843 char * evel_entity_state(const EVEL_ENTITY_STATE state);
 844
 845 /**************************************************************************//**
 846  * Convert a ::EVEL_SERVICE_ENDPOINT_DESC to string form for JSON encoding.
 847  *
 848  * @param endpoint_desc endpoint description to encode.
 849  *
 850  * @returns the corresponding string
 851  *****************************************************************************/
 852 char * evel_service_endpoint_desc(const EVEL_ENTITY_STATE endpoint_desc);
 853
 854
 855 /**************************************************************************//**
 856  * Initialize an ::EVEL_OPTION_INTHEADER_FIELDS to a not-set state.
 857  *
 858  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 859  *****************************************************************************/
 860 void evel_init_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option);
 861 /**************************************************************************//**
 862  * Force the value of an ::EVEL_OPTION_INTHEADER_FIELDS.
 863  *
 864  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 865  * @param value         The value to set.
 866  *****************************************************************************/
 867 void evel_force_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option,
 868                            const void* value);
 869 /**************************************************************************//**
 870  * Set the value of an ::EVEL_OPTION_INTHEADER_FIELDS.
 871  *
 872  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 873  * @param value         The value to set.
 874  * @param description   Description to be used in logging.
 875  *****************************************************************************/
 876 void evel_set_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option,
 877                          const void * value,
 878                          const char * const description);
 879 /**************************************************************************//**
 880  * Free the underlying resources of an ::EVEL_OPTION_INTHEADER_FIELDS.
 881  *
 882  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 883  *****************************************************************************/
 884 void evel_free_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option);
 885
 886 #endif