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