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