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