vnfs/VES5.0/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                                         int activitymode,
 205                                         const char * const cert_file_path,
 206                                         const char * const key_file_path,
 207                                         const char * const ca_info,
 208                                         const char * const ca_file_path,
 209                                         long verify_peer,
 210                                         long verify_host,
 211                                         const char * const username,
 212                                         const char * const password,
 213                                         const char * const username2,
 214                                         const char * const password2,
 215                                         int verbosity);
 216
 217 /**************************************************************************//**
 218  * Terminate the event handler.
 219  *
 220  * Shuts down the event handler thread in as clean a way as possible. Sets the
 221  * global exit flag and then signals the thread to interrupt it since it's
 222  * most likely waiting on the ring-buffer.
 223  *
 224  * Having achieved an orderly shutdown of the event handler thread, clean up
 225  * the cURL library's resources cleanly.
 226  *
 227  *  @return Status code.
 228  *  @retval ::EVEL_SUCCESS if everything OK.
 229  *  @retval One of ::EVEL_ERR_CODES if there was a problem.
 230  *****************************************************************************/
 231 EVEL_ERR_CODES event_handler_terminate();
 232
 233 /**************************************************************************//**
 234  * Run the event handler.
 235  *
 236  * Spawns the thread responsible for handling events and sending them to the
 237  * API.
 238  *
 239  *  @return Status code.
 240  *  @retval ::EVEL_SUCCESS if everything OK.
 241  *  @retval One of ::EVEL_ERR_CODES if there was a problem.
 242  *****************************************************************************/
 243 EVEL_ERR_CODES event_handler_run();
 244
 245 /**************************************************************************//**
 246  * Create a new internal event.
 247  *
 248  * @note    The mandatory fields on the Fault must be supplied to this factory
 249  *          function and are immutable once set.  Optional fields have explicit
 250  *          setter functions, but again values may only be set once so that the
 251  *          Fault has immutable properties.
 252  * @param   command   The condition indicated by the event.
 253  * @returns pointer to the newly manufactured ::EVENT_INTERNAL.  If the event
 254  *          is not used (i.e. posted) it must be released using
 255  *          ::evel_free_event.
 256  * @retval  NULL  Failed to create the event.
 257  *****************************************************************************/
 258 EVENT_INTERNAL * evel_new_internal_event(EVT_HANDLER_COMMAND command,const char* ev_name, const char *ev_id);
 259
 260 /**************************************************************************//**
 261  * Free an internal event.
 262  *
 263  * Free off the event supplied.  Will free all the contained* allocated memory.
 264  *
 265  * @note It does not free the internal event itself, since that may be part of
 266  * a larger structure.
 267  *****************************************************************************/
 268 void evel_free_internal_event(EVENT_INTERNAL * event);
 269
 270 /*****************************************************************************/
 271 /* Structure to hold JSON buffer and associated tracking, as it is written.  */
 272 /*****************************************************************************/
 273 typedef struct evel_json_buffer
 274 {
 275   char * json;
 276   int offset;
 277   int max_size;
 278
 279   /***************************************************************************/
 280   /* The working throttle specification, which can be NULL.                  */
 281   /***************************************************************************/
 282   EVEL_THROTTLE_SPEC * throttle_spec;
 283
 284   /***************************************************************************/
 285   /* Current object/list nesting depth.                                      */
 286   /***************************************************************************/
 287   int depth;
 288
 289   /***************************************************************************/
 290   /* The checkpoint.                                                         */
 291   /***************************************************************************/
 292   int checkpoint;
 293
 294 } EVEL_JSON_BUFFER;
 295
 296 /**************************************************************************//**
 297  * Encode the event as a JSON event object according to AT&T's schema.
 298  *
 299  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 300  * @param event         Pointer to the ::EVENT_HEADER to encode.
 301  *****************************************************************************/
 302 void evel_json_encode_header(EVEL_JSON_BUFFER * jbuf,
 303                              EVENT_HEADER * event);
 304
 305 /**************************************************************************//**
 306  * Encode the fault in JSON according to AT&T's schema for the fault type.
 307  *
 308  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 309  * @param event         Pointer to the ::EVENT_HEADER to encode.
 310  *****************************************************************************/
 311 void evel_json_encode_fault(EVEL_JSON_BUFFER * jbuf,
 312                             EVENT_FAULT * event);
 313
 314 /**************************************************************************//**
 315  * Encode the measurement as a JSON measurement.
 316  *
 317  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 318  * @param event         Pointer to the ::EVENT_HEADER to encode.
 319  *****************************************************************************/
 320 void evel_json_encode_measurement(EVEL_JSON_BUFFER * jbuf,
 321                                   EVENT_MEASUREMENT * event);
 322
 323 /**************************************************************************//**
 324  * Encode the Mobile Flow in JSON according to AT&T's schema for the event
 325  * type.
 326  *
 327  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 328  * @param event         Pointer to the ::EVENT_HEADER to encode.
 329  *****************************************************************************/
 330 void evel_json_encode_mobile_flow(EVEL_JSON_BUFFER * jbuf,
 331                                   EVENT_MOBILE_FLOW * event);
 332
 333 /**************************************************************************//**
 334  * Encode the report as a JSON report.
 335  *
 336  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 337  * @param event         Pointer to the ::EVENT_HEADER to encode.
 338  *****************************************************************************/
 339 void evel_json_encode_report(EVEL_JSON_BUFFER * jbuf,
 340                              EVENT_REPORT * event);
 341
 342 /**************************************************************************//**
 343  * Encode the Heartbeat fields in JSON according to AT&T's schema for the
 344  * event type.
 345  *
 346  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 347  * @param event         Pointer to the ::EVENT_HEADER to encode.
 348  *****************************************************************************/
 349 void evel_json_encode_hrtbt_field(EVEL_JSON_BUFFER * const jbuf,
 350                                 EVENT_HEARTBEAT_FIELD * const event);
 351
 352 /**************************************************************************//**
 353  * Encode the Signaling in JSON according to AT&T's schema for the event type.
 354  *
 355  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 356  * @param event         Pointer to the ::EVENT_HEADER to encode.
 357  *****************************************************************************/
 358 void evel_json_encode_signaling(EVEL_JSON_BUFFER * const jbuf,
 359                                 EVENT_SIGNALING * const event);
 360
 361 /**************************************************************************//**
 362  * Encode the state change as a JSON state change.
 363  *
 364  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 365  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 366  *****************************************************************************/
 367 void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
 368                                    EVENT_STATE_CHANGE * state_change);
 369
 370 /**************************************************************************//**
 371  * Encode the Syslog in JSON according to AT&T's schema for the event type.
 372  *
 373  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 374  * @param event         Pointer to the ::EVENT_HEADER to encode.
 375  *****************************************************************************/
 376 void evel_json_encode_syslog(EVEL_JSON_BUFFER * jbuf,
 377                              EVENT_SYSLOG * event);
 378
 379 /**************************************************************************//**
 380  * Encode the Other in JSON according to AT&T's schema for the event type.
 381  *
 382  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 383  * @param event         Pointer to the ::EVENT_HEADER to encode.
 384  *****************************************************************************/
 385 void evel_json_encode_other(EVEL_JSON_BUFFER * jbuf,
 386                             EVENT_OTHER * event);
 387
 388 /**************************************************************************//**
 389  * Set the next event_sequence to use.
 390  *
 391  * @param sequence      The next sequence number to use.
 392  *****************************************************************************/
 393 void evel_set_next_event_sequence(const int sequence);
 394
 395 /**************************************************************************//**
 396  * Handle a JSON response from the listener, contained in a ::MEMORY_CHUNK.
 397  *
 398  * Tokenize the response, and decode any tokens found.
 399  *
 400  * @param chunk         The memory chunk containing the response.
 401  * @param post          The memory chunk in which to place any resulting POST.
 402  *****************************************************************************/
 403 void evel_handle_event_response(const MEMORY_CHUNK * const chunk,
 404                                 MEMORY_CHUNK * const post);
 405
 406 /**************************************************************************//**
 407  * Initialize a ::EVEL_JSON_BUFFER.
 408  *
 409  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to initialise.
 410  * @param json          Pointer to the underlying working buffer to use.
 411  * @param max_size      Size of storage available in the JSON buffer.
 412  * @param throttle_spec Pointer to throttle specification. Can be NULL.
 413  *****************************************************************************/
 414 void evel_json_buffer_init(EVEL_JSON_BUFFER * jbuf,
 415                            char * const json,
 416                            const int max_size,
 417                            EVEL_THROTTLE_SPEC * throttle_spec);
 418
 419 /**************************************************************************//**
 420  * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 421  *
 422  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 423  * @param key           Pointer to the key to encode.
 424  * @param option        Pointer to holder of the corresponding value to encode.
 425  * @return true if the key, value was added, false if it was suppressed.
 426  *****************************************************************************/
 427 bool evel_enc_kv_opt_string(EVEL_JSON_BUFFER * jbuf,
 428                             const char * const key,
 429                             const EVEL_OPTION_STRING * const option);
 430
 431 /**************************************************************************//**
 432  * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 433  *
 434  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 435  * @param key           Pointer to the key to encode.
 436  * @param value         Pointer to the corresponding value to encode.
 437  *****************************************************************************/
 438 void evel_enc_kv_string(EVEL_JSON_BUFFER * jbuf,
 439                         const char * const key,
 440                         const char * const value);
 441
 442 /**************************************************************************//**
 443  * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 444  *
 445  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 446  * @param key           Pointer to the key to encode.
 447  * @param option        Pointer to holder of the corresponding value to encode.
 448  * @return true if the key, value was added, false if it was suppressed.
 449  *****************************************************************************/
 450 bool evel_enc_kv_opt_int(EVEL_JSON_BUFFER * jbuf,
 451                          const char * const key,
 452                          const EVEL_OPTION_INT * const option);
 453
 454 /**************************************************************************//**
 455  * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 456  *
 457  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 458  * @param key           Pointer to the key to encode.
 459  * @param value         The corresponding value to encode.
 460  *****************************************************************************/
 461 void evel_enc_kv_int(EVEL_JSON_BUFFER * jbuf,
 462                      const char * const key,
 463                      const int value);
 464
 465 /**************************************************************************//**
 466  * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 467  *
 468  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 469  * @param key           Pointer to the key to encode.
 470  * @param option        Pointer to holder of the corresponding value to encode.
 471  * @return true if the key, value was added, false if it was suppressed.
 472  *****************************************************************************/
 473 bool evel_enc_kv_opt_double(EVEL_JSON_BUFFER * jbuf,
 474                             const char * const key,
 475                             const EVEL_OPTION_DOUBLE * const option);
 476
 477 /**************************************************************************//**
 478  * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 479  *
 480  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 481  * @param key           Pointer to the key to encode.
 482  * @param value         The corresponding value to encode.
 483  *****************************************************************************/
 484 void evel_enc_kv_double(EVEL_JSON_BUFFER * jbuf,
 485                         const char * const key,
 486                         const double value);
 487
 488 /**************************************************************************//**
 489  * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 490  *
 491  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 492  * @param key           Pointer to the key to encode.
 493  * @param option        Pointer to holder of the corresponding value to encode.
 494  * @return true if the key, value was added, false if it was suppressed.
 495  *****************************************************************************/
 496 bool evel_enc_kv_opt_ull(EVEL_JSON_BUFFER * jbuf,
 497                          const char * const key,
 498                          const EVEL_OPTION_ULL * const option);
 499
 500 /**************************************************************************//**
 501  * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 502  *
 503  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 504  * @param key           Pointer to the key to encode.
 505  * @param value         The corresponding value to encode.
 506  *****************************************************************************/
 507 void evel_enc_kv_ull(EVEL_JSON_BUFFER * jbuf,
 508                      const char * const key,
 509                      const unsigned long long value);
 510
 511 /**************************************************************************//**
 512  * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 513  *
 514  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 515  * @param key           Pointer to the key to encode.
 516  * @param option        Pointer to holder of the corresponding value to encode.
 517  * @return true if the key, value was added, false if it was suppressed.
 518  *****************************************************************************/
 519 bool evel_enc_kv_opt_time(EVEL_JSON_BUFFER * jbuf,
 520                           const char * const key,
 521                           const EVEL_OPTION_TIME * const option);
 522
 523 /**************************************************************************//**
 524  * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 525  *
 526  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 527  * @param key           Pointer to the key to encode.
 528  * @param time          Pointer to the time to encode.
 529  *****************************************************************************/
 530 void evel_enc_kv_time(EVEL_JSON_BUFFER * jbuf,
 531                       const char * const key,
 532                       const time_t * time);
 533
 534 /**************************************************************************//**
 535  * Encode a key and version.
 536  *
 537  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 538  * @param key           Pointer to the key to encode.
 539  * @param major_version The major version to encode.
 540  * @param minor_version The minor version to encode.
 541  *****************************************************************************/
 542 void evel_enc_version(EVEL_JSON_BUFFER * jbuf,
 543                       const char * const key,
 544                       const int major_version,
 545                       const int minor_version);
 546
 547 /**************************************************************************//**
 548  * Add the key and opening bracket of an optional named list to a JSON buffer.
 549  *
 550  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 551  * @param key           Pointer to the key to encode.
 552  * @return true if the list was opened, false if it was suppressed.
 553  *****************************************************************************/
 554 bool evel_json_open_opt_named_list(EVEL_JSON_BUFFER * jbuf,
 555                                    const char * const key);
 556
 557 /**************************************************************************//**
 558  * Add the key and opening bracket of a named list to a JSON buffer.
 559  *
 560  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 561  * @param key           Pointer to the key to encode.
 562  *****************************************************************************/
 563 void evel_json_open_named_list(EVEL_JSON_BUFFER * jbuf,
 564                                const char * const key);
 565
 566 /**************************************************************************//**
 567  * Add the closing bracket of a list to a JSON buffer.
 568  *
 569  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 570  *****************************************************************************/
 571 void evel_json_close_list(EVEL_JSON_BUFFER * jbuf);
 572
 573 /**************************************************************************//**
 574  * Encode a list item with format and param list to a ::EVEL_JSON_BUFFER.
 575  *
 576  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 577  * @param format        Format string in standard printf format.
 578  * @param ...           Variable parameters for format string.
 579  *****************************************************************************/
 580 void evel_enc_list_item(EVEL_JSON_BUFFER * jbuf,
 581                         const char * const format,
 582                         ...);
 583
 584 /**************************************************************************//**
 585  * Add the opening bracket of an optional named object to a JSON buffer.
 586  *
 587  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 588  * @param key           Pointer to the key to encode.
 589  *****************************************************************************/
 590 bool evel_json_open_opt_named_object(EVEL_JSON_BUFFER * jbuf,
 591                                      const char * const key);
 592
 593 /**************************************************************************//**
 594  * Add the opening bracket of an object to a JSON buffer.
 595  *
 596  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 597  * @param key           Pointer to the key to encode.
 598  * @return true if the object was opened, false if it was suppressed.
 599  *****************************************************************************/
 600 void evel_json_open_named_object(EVEL_JSON_BUFFER * jbuf,
 601                                  const char * const key);
 602
 603 /**************************************************************************//**
 604  * Add the opening bracket of an object to a JSON buffer.
 605  *
 606  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 607  *****************************************************************************/
 608 void evel_json_open_object(EVEL_JSON_BUFFER * jbuf);
 609
 610 /**************************************************************************//**
 611  * Add the closing bracket of an object to a JSON buffer.
 612  *
 613  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 614  *****************************************************************************/
 615 void evel_json_close_object(EVEL_JSON_BUFFER * jbuf);
 616
 617 /**************************************************************************//**
 618  * Add a checkpoint - a stake in the ground to which we can rewind.
 619  *
 620  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 621  *****************************************************************************/
 622 void evel_json_checkpoint(EVEL_JSON_BUFFER * jbuf);
 623
 624 /**************************************************************************//**
 625  * Rewind to the latest checkoint.
 626  *
 627  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 628  *****************************************************************************/
 629 void evel_json_rewind(EVEL_JSON_BUFFER * jbuf);
 630
 631 /**************************************************************************//**
 632  * Free the underlying resources of an ::EVEL_OPTION_STRING.
 633  *
 634  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 635  *****************************************************************************/
 636 void evel_free_option_string(EVEL_OPTION_STRING * const option);
 637
 638 /**************************************************************************//**
 639  * Initialize an ::EVEL_OPTION_STRING to a not-set state.
 640  *
 641  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 642  *****************************************************************************/
 643 void evel_init_option_string(EVEL_OPTION_STRING * const option);
 644
 645 /**************************************************************************//**
 646  * Set the value of an ::EVEL_OPTION_STRING.
 647  *
 648  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 649  * @param value         The value to set.
 650  * @param description   Description to be used in logging.
 651  *****************************************************************************/
 652 void evel_set_option_string(EVEL_OPTION_STRING * const option,
 653                             const char * const value,
 654                             const char * const description);
 655
 656 /**************************************************************************//**
 657  * Force the value of an ::EVEL_OPTION_STRING.
 658  *
 659  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 660  * @param value         The value to set.
 661  *****************************************************************************/
 662 void evel_force_option_string(EVEL_OPTION_STRING * const option,
 663                               const char * const value);
 664
 665 /**************************************************************************//**
 666  * Initialize an ::EVEL_OPTION_INT to a not-set state.
 667  *
 668  * @param option        Pointer to the ::EVEL_OPTION_INT.
 669  *****************************************************************************/
 670 void evel_init_option_int(EVEL_OPTION_INT * const option);
 671
 672 /**************************************************************************//**
 673  * Force the value of an ::EVEL_OPTION_INT.
 674  *
 675  * @param option        Pointer to the ::EVEL_OPTION_INT.
 676  * @param value         The value to set.
 677  *****************************************************************************/
 678 void evel_force_option_int(EVEL_OPTION_INT * const option,
 679                            const int value);
 680
 681 /**************************************************************************//**
 682  * Set the value of an ::EVEL_OPTION_INT.
 683  *
 684  * @param option        Pointer to the ::EVEL_OPTION_INT.
 685  * @param value         The value to set.
 686  * @param description   Description to be used in logging.
 687  *****************************************************************************/
 688 void evel_set_option_int(EVEL_OPTION_INT * const option,
 689                          const int value,
 690                          const char * const description);
 691
 692 /**************************************************************************//**
 693  * Initialize an ::EVEL_OPTION_DOUBLE to a not-set state.
 694  *
 695  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 696  *****************************************************************************/
 697 void evel_init_option_double(EVEL_OPTION_DOUBLE * const option);
 698
 699 /**************************************************************************//**
 700  * Force the value of an ::EVEL_OPTION_DOUBLE.
 701  *
 702  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 703  * @param value         The value to set.
 704  *****************************************************************************/
 705 void evel_force_option_double(EVEL_OPTION_DOUBLE * const option,
 706                               const double value);
 707
 708 /**************************************************************************//**
 709  * Set the value of an ::EVEL_OPTION_DOUBLE.
 710  *
 711  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 712  * @param value         The value to set.
 713  * @param description   Description to be used in logging.
 714  *****************************************************************************/
 715 void evel_set_option_double(EVEL_OPTION_DOUBLE * const option,
 716                             const double value,
 717                             const char * const description);
 718
 719 /**************************************************************************//**
 720  * Initialize an ::EVEL_OPTION_ULL to a not-set state.
 721  *
 722  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 723  *****************************************************************************/
 724 void evel_init_option_ull(EVEL_OPTION_ULL * const option);
 725
 726 /**************************************************************************//**
 727  * Force the value of an ::EVEL_OPTION_ULL.
 728  *
 729  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 730  * @param value         The value to set.
 731  *****************************************************************************/
 732 void evel_force_option_ull(EVEL_OPTION_ULL * const option,
 733                            const unsigned long long value);
 734
 735 /**************************************************************************//**
 736  * Set the value of an ::EVEL_OPTION_ULL.
 737  *
 738  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 739  * @param value         The value to set.
 740  * @param description   Description to be used in logging.
 741  *****************************************************************************/
 742 void evel_set_option_ull(EVEL_OPTION_ULL * const option,
 743                          const unsigned long long value,
 744                          const char * const description);
 745
 746 /**************************************************************************//**
 747  * Initialize an ::EVEL_OPTION_TIME to a not-set state.
 748  *
 749  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 750  *****************************************************************************/
 751 void evel_init_option_time(EVEL_OPTION_TIME * const option);
 752
 753 /**************************************************************************//**
 754  * Force the value of an ::EVEL_OPTION_TIME.
 755  *
 756  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 757  * @param value         The value to set.
 758  *****************************************************************************/
 759 void evel_force_option_time(EVEL_OPTION_TIME * const option,
 760                             const time_t value);
 761
 762 /**************************************************************************//**
 763  * Set the value of an ::EVEL_OPTION_TIME.
 764  *
 765  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 766  * @param value         The value to set.
 767  * @param description   Description to be used in logging.
 768  *****************************************************************************/
 769 void evel_set_option_time(EVEL_OPTION_TIME * const option,
 770                           const time_t value,
 771                           const char * const description);
 772
 773 /**************************************************************************//**
 774  * Map an ::EVEL_COUNTER_CRITICALITIES enum value to the equivalent string.
 775  *
 776  * @param criticality   The criticality to convert.
 777  * @returns The equivalent string.
 778  *****************************************************************************/
 779 char * evel_criticality(const EVEL_COUNTER_CRITICALITIES criticality);
 780
 781 /**************************************************************************//**
 782  * Map an ::EVEL_SEVERITIES enum value to the equivalent string.
 783  *
 784  * @param severity      The severity to convert.
 785  * @returns The equivalent string.
 786  *****************************************************************************/
 787 char * evel_severity(const EVEL_SEVERITIES severity);
 788
 789 /**************************************************************************//**
 790  * Map an ::EVEL_ALERT_ACTIONS enum value to the equivalent string.
 791  *
 792  * @param alert_action  The alert_action to convert.
 793  * @returns The equivalent string.
 794  *****************************************************************************/
 795 char * evel_alert_action(const EVEL_ALERT_ACTIONS alert_action);
 796
 797 /**************************************************************************//**
 798  * Map an ::EVEL_ALERT_TYPES enum value to the equivalent string.
 799  *
 800  * @param alert_type    The alert_type to convert.
 801  * @returns The equivalent string.
 802  *****************************************************************************/
 803 char * evel_alert_type(const EVEL_ALERT_TYPES alert_type);
 804
 805 /**************************************************************************//**
 806  * Map an ::EVEL_EVENT_DOMAINS enum value to the equivalent string.
 807  *
 808  * @param domain        The domain to convert.
 809  * @returns The equivalent string.
 810  *****************************************************************************/
 811 char * evel_event_domain(const EVEL_EVENT_DOMAINS domain);
 812
 813 /**************************************************************************//**
 814  * Map an ::EVEL_EVENT_PRIORITIES enum value to the equivalent string.
 815  *
 816  * @param priority      The priority to convert.
 817  * @returns The equivalent string.
 818  *****************************************************************************/
 819 char * evel_event_priority(const EVEL_EVENT_PRIORITIES priority);
 820
 821 /**************************************************************************//**
 822  * Map an ::EVEL_SOURCE_TYPES enum value to the equivalent string.
 823  *
 824  * @param source_type   The source type to convert.
 825  * @returns The equivalent string.
 826  *****************************************************************************/
 827 char * evel_source_type(const EVEL_SOURCE_TYPES source_type);
 828
 829 /**************************************************************************//**
 830  * Map an ::EVEL_VF_STATUSES enum value to the equivalent string.
 831  *
 832  * @param vf_status     The vf_status to convert.
 833  * @returns The equivalent string.
 834  *****************************************************************************/
 835 char * evel_vf_status(const EVEL_VF_STATUSES vf_status);
 836
 837 /**************************************************************************//**
 838  * Convert a ::EVEL_ENTITY_STATE to it's string form for JSON encoding.
 839  *
 840  * @param state         The entity state to encode.
 841  *
 842  * @returns the corresponding string
 843  *****************************************************************************/
 844 char * evel_entity_state(const EVEL_ENTITY_STATE state);
 845
 846 /**************************************************************************//**
 847  * Convert a ::EVEL_SERVICE_ENDPOINT_DESC to string form for JSON encoding.
 848  *
 849  * @param endpoint_desc endpoint description to encode.
 850  *
 851  * @returns the corresponding string
 852  *****************************************************************************/
 853 char * evel_service_endpoint_desc(const EVEL_ENTITY_STATE endpoint_desc);
 854
 855
 856 /**************************************************************************//**
 857  * Initialize an ::EVEL_OPTION_INTHEADER_FIELDS to a not-set state.
 858  *
 859  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 860  *****************************************************************************/
 861 void evel_init_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option);
 862 /**************************************************************************//**
 863  * Force the value of an ::EVEL_OPTION_INTHEADER_FIELDS.
 864  *
 865  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 866  * @param value         The value to set.
 867  *****************************************************************************/
 868 void evel_force_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option,
 869                            const void* value);
 870 /**************************************************************************//**
 871  * Set the value of an ::EVEL_OPTION_INTHEADER_FIELDS.
 872  *
 873  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 874  * @param value         The value to set.
 875  * @param description   Description to be used in logging.
 876  *****************************************************************************/
 877 void evel_set_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option,
 878                          const void * value,
 879                          const char * const description);
 880 /**************************************************************************//**
 881  * Free the underlying resources of an ::EVEL_OPTION_INTHEADER_FIELDS.
 882  *
 883  * @param option        Pointer to the ::EVEL_OPTION_INTHEADER_FIELDS.
 884  *****************************************************************************/
 885 void evel_free_option_intheader(EVEL_OPTION_INTHEADER_FIELDS * const option);
 886
 887 #endif