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