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(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  * Initialize an event instance id, typically embedded in an event.
 257  *
 258  * @param instance_id   Pointer to the event instance id being initialized.
 259  * @param vendor_id     The vendor id to encode in the event instance id.
 260  * @param event_id      The event id to encode in the event instance id.
 261  *****************************************************************************/
 262 void evel_init_event_instance_id(EVEL_EVENT_INSTANCE_ID * const instance_id,
 263                                  const char * const vendor_id,
 264                                  const char * const event_id);
 265
 266 /**************************************************************************//**
 267  * Free an event instance id.
 268  *
 269  * @param instance_id   Pointer to the event instance id being initialized.
 270  *****************************************************************************/
 271 void evel_free_event_instance_id(EVEL_EVENT_INSTANCE_ID * const instance_id);
 272
 273 /*****************************************************************************/
 274 /* Structure to hold JSON buffer and associated tracking, as it is written.  */
 275 /*****************************************************************************/
 276 typedef struct evel_json_buffer
 277 {
 278   char * json;
 279   int offset;
 280   int max_size;
 281
 282   /***************************************************************************/
 283   /* The working throttle specification, which can be NULL.                  */
 284   /***************************************************************************/
 285   EVEL_THROTTLE_SPEC * throttle_spec;
 286
 287   /***************************************************************************/
 288   /* Current object/list nesting depth.                                      */
 289   /***************************************************************************/
 290   int depth;
 291
 292   /***************************************************************************/
 293   /* The checkpoint.                                                         */
 294   /***************************************************************************/
 295   int checkpoint;
 296
 297 } EVEL_JSON_BUFFER;
 298
 299 /**************************************************************************//**
 300  * Encode the event as a JSON event object according to AT&T's schema.
 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_header(EVEL_JSON_BUFFER * jbuf,
 306                              EVENT_HEADER * event);
 307
 308 /**************************************************************************//**
 309  * Encode the instance id as a JSON object according to AT&T's schema.
 310  *
 311  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 312  * @param instance_id   Pointer to the ::EVEL_EVENT_INSTANCE_ID to encode.
 313  *****************************************************************************/
 314 void evel_json_encode_instance_id(EVEL_JSON_BUFFER * jbuf,
 315                                   EVEL_EVENT_INSTANCE_ID * instance_id);
 316
 317 /**************************************************************************//**
 318  * Encode the fault in JSON according to AT&T's schema for the fault type.
 319  *
 320  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 321  * @param event         Pointer to the ::EVENT_HEADER to encode.
 322  *****************************************************************************/
 323 void evel_json_encode_fault(EVEL_JSON_BUFFER * jbuf,
 324                             EVENT_FAULT * event);
 325
 326 /**************************************************************************//**
 327  * Encode the measurement as a JSON measurement.
 328  *
 329  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 330  * @param event         Pointer to the ::EVENT_HEADER to encode.
 331  *****************************************************************************/
 332 void evel_json_encode_measurement(EVEL_JSON_BUFFER * jbuf,
 333                                   EVENT_MEASUREMENT * event);
 334
 335 /**************************************************************************//**
 336  * Encode the Mobile Flow in JSON according to AT&T's schema for the event
 337  * type.
 338  *
 339  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 340  * @param event         Pointer to the ::EVENT_HEADER to encode.
 341  *****************************************************************************/
 342 void evel_json_encode_mobile_flow(EVEL_JSON_BUFFER * jbuf,
 343                                   EVENT_MOBILE_FLOW * event);
 344
 345 /**************************************************************************//**
 346  * Encode the report as a JSON report.
 347  *
 348  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 349  * @param event         Pointer to the ::EVENT_HEADER to encode.
 350  *****************************************************************************/
 351 void evel_json_encode_report(EVEL_JSON_BUFFER * jbuf,
 352                              EVENT_REPORT * event);
 353
 354 /**************************************************************************//**
 355  * Encode the Service Event in JSON according to AT&T's schema for the event
 356  * 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_service(EVEL_JSON_BUFFER * const jbuf,
 362                               EVENT_SERVICE * const event);
 363
 364 /**************************************************************************//**
 365  * Encode the Signaling 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_signaling(EVEL_JSON_BUFFER * const jbuf,
 371                                 EVENT_SIGNALING * const event);
 372
 373 /**************************************************************************//**
 374  * Encode the state change as a JSON state change.
 375  *
 376  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 377  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 378  *****************************************************************************/
 379 void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
 380                                    EVENT_STATE_CHANGE * state_change);
 381
 382 /**************************************************************************//**
 383  * Encode the Syslog in JSON according to AT&T's schema for the event type.
 384  *
 385  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 386  * @param event         Pointer to the ::EVENT_HEADER to encode.
 387  *****************************************************************************/
 388 void evel_json_encode_syslog(EVEL_JSON_BUFFER * jbuf,
 389                              EVENT_SYSLOG * event);
 390
 391 /**************************************************************************//**
 392  * Encode the Other in JSON according to AT&T's schema for the event type.
 393  *
 394  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 395  * @param event         Pointer to the ::EVENT_HEADER to encode.
 396  *****************************************************************************/
 397 void evel_json_encode_other(EVEL_JSON_BUFFER * jbuf,
 398                             EVENT_OTHER * event);
 399
 400 /**************************************************************************//**
 401  * Set the next event_sequence to use.
 402  *
 403  * @param sequence      The next sequence number to use.
 404  *****************************************************************************/
 405 void evel_set_next_event_sequence(const int sequence);
 406
 407 /**************************************************************************//**
 408  * Handle a JSON response from the listener, contained in a ::MEMORY_CHUNK.
 409  *
 410  * Tokenize the response, and decode any tokens found.
 411  *
 412  * @param chunk         The memory chunk containing the response.
 413  * @param post          The memory chunk in which to place any resulting POST.
 414  *****************************************************************************/
 415 void evel_handle_event_response(const MEMORY_CHUNK * const chunk,
 416                                 MEMORY_CHUNK * const post);
 417
 418 /**************************************************************************//**
 419  * Initialize a ::EVEL_JSON_BUFFER.
 420  *
 421  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to initialise.
 422  * @param json          Pointer to the underlying working buffer to use.
 423  * @param max_size      Size of storage available in the JSON buffer.
 424  * @param throttle_spec Pointer to throttle specification. Can be NULL.
 425  *****************************************************************************/
 426 void evel_json_buffer_init(EVEL_JSON_BUFFER * jbuf,
 427                            char * const json,
 428                            const int max_size,
 429                            EVEL_THROTTLE_SPEC * throttle_spec);
 430
 431 /**************************************************************************//**
 432  * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 433  *
 434  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 435  * @param key           Pointer to the key to encode.
 436  * @param option        Pointer to holder of the corresponding value to encode.
 437  * @return true if the key, value was added, false if it was suppressed.
 438  *****************************************************************************/
 439 bool evel_enc_kv_opt_string(EVEL_JSON_BUFFER * jbuf,
 440                             const char * const key,
 441                             const EVEL_OPTION_STRING * const option);
 442
 443 /**************************************************************************//**
 444  * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 445  *
 446  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 447  * @param key           Pointer to the key to encode.
 448  * @param value         Pointer to the corresponding value to encode.
 449  *****************************************************************************/
 450 void evel_enc_kv_string(EVEL_JSON_BUFFER * jbuf,
 451                         const char * const key,
 452                         const char * const value);
 453
 454 /**************************************************************************//**
 455  * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 456  *
 457  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 458  * @param key           Pointer to the key to encode.
 459  * @param option        Pointer to holder of the corresponding value to encode.
 460  * @return true if the key, value was added, false if it was suppressed.
 461  *****************************************************************************/
 462 bool evel_enc_kv_opt_int(EVEL_JSON_BUFFER * jbuf,
 463                          const char * const key,
 464                          const EVEL_OPTION_INT * const option);
 465
 466 /**************************************************************************//**
 467  * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 468  *
 469  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 470  * @param key           Pointer to the key to encode.
 471  * @param value         The corresponding value to encode.
 472  *****************************************************************************/
 473 void evel_enc_kv_int(EVEL_JSON_BUFFER * jbuf,
 474                      const char * const key,
 475                      const int value);
 476
 477 /**************************************************************************//**
 478  * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 479  *
 480  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 481  * @param key           Pointer to the key to encode.
 482  * @param option        Pointer to holder of the corresponding value to encode.
 483  * @return true if the key, value was added, false if it was suppressed.
 484  *****************************************************************************/
 485 bool evel_enc_kv_opt_double(EVEL_JSON_BUFFER * jbuf,
 486                             const char * const key,
 487                             const EVEL_OPTION_DOUBLE * const option);
 488
 489 /**************************************************************************//**
 490  * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 491  *
 492  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 493  * @param key           Pointer to the key to encode.
 494  * @param value         The corresponding value to encode.
 495  *****************************************************************************/
 496 void evel_enc_kv_double(EVEL_JSON_BUFFER * jbuf,
 497                         const char * const key,
 498                         const double value);
 499
 500 /**************************************************************************//**
 501  * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 502  *
 503  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 504  * @param key           Pointer to the key to encode.
 505  * @param option        Pointer to holder of the corresponding value to encode.
 506  * @return true if the key, value was added, false if it was suppressed.
 507  *****************************************************************************/
 508 bool evel_enc_kv_opt_ull(EVEL_JSON_BUFFER * jbuf,
 509                          const char * const key,
 510                          const EVEL_OPTION_ULL * const option);
 511
 512 /**************************************************************************//**
 513  * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 514  *
 515  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 516  * @param key           Pointer to the key to encode.
 517  * @param value         The corresponding value to encode.
 518  *****************************************************************************/
 519 void evel_enc_kv_ull(EVEL_JSON_BUFFER * jbuf,
 520                      const char * const key,
 521                      const unsigned long long value);
 522
 523 /**************************************************************************//**
 524  * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 525  *
 526  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 527  * @param key           Pointer to the key to encode.
 528  * @param option        Pointer to holder of the corresponding value to encode.
 529  * @return true if the key, value was added, false if it was suppressed.
 530  *****************************************************************************/
 531 bool evel_enc_kv_opt_time(EVEL_JSON_BUFFER * jbuf,
 532                           const char * const key,
 533                           const EVEL_OPTION_TIME * const option);
 534
 535 /**************************************************************************//**
 536  * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 537  *
 538  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 539  * @param key           Pointer to the key to encode.
 540  * @param time          Pointer to the time to encode.
 541  *****************************************************************************/
 542 void evel_enc_kv_time(EVEL_JSON_BUFFER * jbuf,
 543                       const char * const key,
 544                       const time_t * time);
 545
 546 /**************************************************************************//**
 547  * Encode a key and version.
 548  *
 549  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 550  * @param key           Pointer to the key to encode.
 551  * @param major_version The major version to encode.
 552  * @param minor_version The minor version to encode.
 553  *****************************************************************************/
 554 void evel_enc_version(EVEL_JSON_BUFFER * jbuf,
 555                       const char * const key,
 556                       const int major_version,
 557                       const int minor_version);
 558
 559 /**************************************************************************//**
 560  * Add the key and opening bracket of an optional named list to a JSON buffer.
 561  *
 562  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 563  * @param key           Pointer to the key to encode.
 564  * @return true if the list was opened, false if it was suppressed.
 565  *****************************************************************************/
 566 bool evel_json_open_opt_named_list(EVEL_JSON_BUFFER * jbuf,
 567                                    const char * const key);
 568
 569 /**************************************************************************//**
 570  * Add the key and opening bracket of a named list 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 void evel_json_open_named_list(EVEL_JSON_BUFFER * jbuf,
 576                                const char * const key);
 577
 578 /**************************************************************************//**
 579  * Add the closing bracket of a list to a JSON buffer.
 580  *
 581  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 582  *****************************************************************************/
 583 void evel_json_close_list(EVEL_JSON_BUFFER * jbuf);
 584
 585 /**************************************************************************//**
 586  * Encode a list item with format and param list to a ::EVEL_JSON_BUFFER.
 587  *
 588  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 589  * @param format        Format string in standard printf format.
 590  * @param ...           Variable parameters for format string.
 591  *****************************************************************************/
 592 void evel_enc_list_item(EVEL_JSON_BUFFER * jbuf,
 593                         const char * const format,
 594                         ...);
 595
 596 /**************************************************************************//**
 597  * Add the opening bracket of an optional named object to a JSON buffer.
 598  *
 599  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 600  * @param key           Pointer to the key to encode.
 601  *****************************************************************************/
 602 bool evel_json_open_opt_named_object(EVEL_JSON_BUFFER * jbuf,
 603                                      const char * const key);
 604
 605 /**************************************************************************//**
 606  * Add the opening bracket of an object to a JSON buffer.
 607  *
 608  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 609  * @param key           Pointer to the key to encode.
 610  * @return true if the object was opened, false if it was suppressed.
 611  *****************************************************************************/
 612 void evel_json_open_named_object(EVEL_JSON_BUFFER * jbuf,
 613                                  const char * const key);
 614
 615 /**************************************************************************//**
 616  * Add the opening bracket of an object to a JSON buffer.
 617  *
 618  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 619  *****************************************************************************/
 620 void evel_json_open_object(EVEL_JSON_BUFFER * jbuf);
 621
 622 /**************************************************************************//**
 623  * Add the closing bracket of an object to a JSON buffer.
 624  *
 625  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 626  *****************************************************************************/
 627 void evel_json_close_object(EVEL_JSON_BUFFER * jbuf);
 628
 629 /**************************************************************************//**
 630  * Add a checkpoint - a stake in the ground to which we can rewind.
 631  *
 632  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 633  *****************************************************************************/
 634 void evel_json_checkpoint(EVEL_JSON_BUFFER * jbuf);
 635
 636 /**************************************************************************//**
 637  * Rewind to the latest checkoint.
 638  *
 639  * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 640  *****************************************************************************/
 641 void evel_json_rewind(EVEL_JSON_BUFFER * jbuf);
 642
 643 /**************************************************************************//**
 644  * Free the underlying resources of an ::EVEL_OPTION_STRING.
 645  *
 646  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 647  *****************************************************************************/
 648 void evel_free_option_string(EVEL_OPTION_STRING * const option);
 649
 650 /**************************************************************************//**
 651  * Initialize an ::EVEL_OPTION_STRING to a not-set state.
 652  *
 653  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 654  *****************************************************************************/
 655 void evel_init_option_string(EVEL_OPTION_STRING * const option);
 656
 657 /**************************************************************************//**
 658  * Set the value of an ::EVEL_OPTION_STRING.
 659  *
 660  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 661  * @param value         The value to set.
 662  * @param description   Description to be used in logging.
 663  *****************************************************************************/
 664 void evel_set_option_string(EVEL_OPTION_STRING * const option,
 665                             const char * const value,
 666                             const char * const description);
 667
 668 /**************************************************************************//**
 669  * Force the value of an ::EVEL_OPTION_STRING.
 670  *
 671  * @param option        Pointer to the ::EVEL_OPTION_STRING.
 672  * @param value         The value to set.
 673  *****************************************************************************/
 674 void evel_force_option_string(EVEL_OPTION_STRING * const option,
 675                               const char * const value);
 676
 677 /**************************************************************************//**
 678  * Initialize an ::EVEL_OPTION_INT to a not-set state.
 679  *
 680  * @param option        Pointer to the ::EVEL_OPTION_INT.
 681  *****************************************************************************/
 682 void evel_init_option_int(EVEL_OPTION_INT * const option);
 683
 684 /**************************************************************************//**
 685  * Force the value of an ::EVEL_OPTION_INT.
 686  *
 687  * @param option        Pointer to the ::EVEL_OPTION_INT.
 688  * @param value         The value to set.
 689  *****************************************************************************/
 690 void evel_force_option_int(EVEL_OPTION_INT * const option,
 691                            const int value);
 692
 693 /**************************************************************************//**
 694  * Set the value of an ::EVEL_OPTION_INT.
 695  *
 696  * @param option        Pointer to the ::EVEL_OPTION_INT.
 697  * @param value         The value to set.
 698  * @param description   Description to be used in logging.
 699  *****************************************************************************/
 700 void evel_set_option_int(EVEL_OPTION_INT * const option,
 701                          const int value,
 702                          const char * const description);
 703
 704 /**************************************************************************//**
 705  * Initialize an ::EVEL_OPTION_DOUBLE to a not-set state.
 706  *
 707  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 708  *****************************************************************************/
 709 void evel_init_option_double(EVEL_OPTION_DOUBLE * const option);
 710
 711 /**************************************************************************//**
 712  * Force the value of an ::EVEL_OPTION_DOUBLE.
 713  *
 714  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 715  * @param value         The value to set.
 716  *****************************************************************************/
 717 void evel_force_option_double(EVEL_OPTION_DOUBLE * const option,
 718                               const double value);
 719
 720 /**************************************************************************//**
 721  * Set the value of an ::EVEL_OPTION_DOUBLE.
 722  *
 723  * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 724  * @param value         The value to set.
 725  * @param description   Description to be used in logging.
 726  *****************************************************************************/
 727 void evel_set_option_double(EVEL_OPTION_DOUBLE * const option,
 728                             const double value,
 729                             const char * const description);
 730
 731 /**************************************************************************//**
 732  * Initialize an ::EVEL_OPTION_ULL to a not-set state.
 733  *
 734  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 735  *****************************************************************************/
 736 void evel_init_option_ull(EVEL_OPTION_ULL * const option);
 737
 738 /**************************************************************************//**
 739  * Force the value of an ::EVEL_OPTION_ULL.
 740  *
 741  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 742  * @param value         The value to set.
 743  *****************************************************************************/
 744 void evel_force_option_ull(EVEL_OPTION_ULL * const option,
 745                            const unsigned long long value);
 746
 747 /**************************************************************************//**
 748  * Set the value of an ::EVEL_OPTION_ULL.
 749  *
 750  * @param option        Pointer to the ::EVEL_OPTION_ULL.
 751  * @param value         The value to set.
 752  * @param description   Description to be used in logging.
 753  *****************************************************************************/
 754 void evel_set_option_ull(EVEL_OPTION_ULL * const option,
 755                          const unsigned long long value,
 756                          const char * const description);
 757
 758 /**************************************************************************//**
 759  * Initialize an ::EVEL_OPTION_TIME to a not-set state.
 760  *
 761  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 762  *****************************************************************************/
 763 void evel_init_option_time(EVEL_OPTION_TIME * const option);
 764
 765 /**************************************************************************//**
 766  * Force the value of an ::EVEL_OPTION_TIME.
 767  *
 768  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 769  * @param value         The value to set.
 770  *****************************************************************************/
 771 void evel_force_option_time(EVEL_OPTION_TIME * const option,
 772                             const time_t value);
 773
 774 /**************************************************************************//**
 775  * Set the value of an ::EVEL_OPTION_TIME.
 776  *
 777  * @param option        Pointer to the ::EVEL_OPTION_TIME.
 778  * @param value         The value to set.
 779  * @param description   Description to be used in logging.
 780  *****************************************************************************/
 781 void evel_set_option_time(EVEL_OPTION_TIME * const option,
 782                           const time_t value,
 783                           const char * const description);
 784
 785 /**************************************************************************//**
 786  * Map an ::EVEL_COUNTER_CRITICALITIES enum value to the equivalent string.
 787  *
 788  * @param criticality   The criticality to convert.
 789  * @returns The equivalent string.
 790  *****************************************************************************/
 791 char * evel_criticality(const EVEL_COUNTER_CRITICALITIES criticality);
 792
 793 /**************************************************************************//**
 794  * Map an ::EVEL_SEVERITIES enum value to the equivalent string.
 795  *
 796  * @param severity      The severity to convert.
 797  * @returns The equivalent string.
 798  *****************************************************************************/
 799 char * evel_severity(const EVEL_SEVERITIES severity);
 800
 801 /**************************************************************************//**
 802  * Map an ::EVEL_ALERT_ACTIONS enum value to the equivalent string.
 803  *
 804  * @param alert_action  The alert_action to convert.
 805  * @returns The equivalent string.
 806  *****************************************************************************/
 807 char * evel_alert_action(const EVEL_ALERT_ACTIONS alert_action);
 808
 809 /**************************************************************************//**
 810  * Map an ::EVEL_ALERT_TYPES enum value to the equivalent string.
 811  *
 812  * @param alert_type    The alert_type to convert.
 813  * @returns The equivalent string.
 814  *****************************************************************************/
 815 char * evel_alert_type(const EVEL_ALERT_TYPES alert_type);
 816
 817 /**************************************************************************//**
 818  * Map an ::EVEL_EVENT_DOMAINS enum value to the equivalent string.
 819  *
 820  * @param domain        The domain to convert.
 821  * @returns The equivalent string.
 822  *****************************************************************************/
 823 char * evel_event_domain(const EVEL_EVENT_DOMAINS domain);
 824
 825 /**************************************************************************//**
 826  * Map an ::EVEL_EVENT_PRIORITIES enum value to the equivalent string.
 827  *
 828  * @param priority      The priority to convert.
 829  * @returns The equivalent string.
 830  *****************************************************************************/
 831 char * evel_event_priority(const EVEL_EVENT_PRIORITIES priority);
 832
 833 /**************************************************************************//**
 834  * Map an ::EVEL_SOURCE_TYPES enum value to the equivalent string.
 835  *
 836  * @param source_type   The source type to convert.
 837  * @returns The equivalent string.
 838  *****************************************************************************/
 839 char * evel_source_type(const EVEL_SOURCE_TYPES source_type);
 840
 841 /**************************************************************************//**
 842  * Map an ::EVEL_VF_STATUSES enum value to the equivalent string.
 843  *
 844  * @param vf_status     The vf_status to convert.
 845  * @returns The equivalent string.
 846  *****************************************************************************/
 847 char * evel_vf_status(const EVEL_VF_STATUSES vf_status);
 848
 849 /**************************************************************************//**
 850  * Convert a ::EVEL_ENTITY_STATE to it's string form for JSON encoding.
 851  *
 852  * @param state         The entity state to encode.
 853  *
 854  * @returns the corresponding string
 855  *****************************************************************************/
 856 char * evel_entity_state(const EVEL_ENTITY_STATE state);
 857
 858 /**************************************************************************//**
 859  * Convert a ::EVEL_SERVICE_ENDPOINT_DESC to string form for JSON encoding.
 860  *
 861  * @param endpoint_desc endpoint description to encode.
 862  *
 863  * @returns the corresponding string
 864  *****************************************************************************/
 865 char * evel_service_endpoint_desc(const EVEL_ENTITY_STATE endpoint_desc);
 866
 867 #endif