VES5.0/evel/evel-library/code/evel_library/evel_internal.h

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