aboutsummaryrefslogtreecommitdiffstats
path: root/vnfs/VES/code/evel_library/evel_internal.h
blob: 4608f751780f6d361def4c425898b1d64dd5b556 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
#ifndef EVEL_INTERNAL_INCLUDED
#define EVEL_INTERNAL_INCLUDED

/**************************************************************************//**
 * @file
 * EVEL internal definitions.
 *
 * These are internal definitions which need to be shared between modules
 * within the library but are not intended for external consumption.
 *
 * License
 * -------
 *
 * Copyright © 2017 AT&T Intellectual Property. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *****************************************************************************/

#include "evel.h"

/*****************************************************************************/
/* Define some type-safe min/max macros.                                     */
/*****************************************************************************/
#define max(a,b) \
   ({ __typeof__ (a) _a = (a); \
       __typeof__ (b) _b = (b); \
     _a > _b ? _a : _b; })

#define min(a,b) \
   ({ __typeof__ (a) _a = (a); \
       __typeof__ (b) _b = (b); \
     _a < _b ? _a : _b; })


/**************************************************************************//**
 * Compile-time assertion.
 *****************************************************************************/
#define EVEL_CT_ASSERT(X) switch (0) {case 0: case (X):;}

/**************************************************************************//**
 * The Functional Role of the equipment represented by this VNF.
 *****************************************************************************/
extern char * functional_role;

/**************************************************************************//**
 * The type of equipment represented by this VNF.
 *****************************************************************************/
extern EVEL_SOURCE_TYPES event_source_type;

/**************************************************************************//**
 * A chunk of memory used in the cURL functions.
 *****************************************************************************/
typedef struct memory_chunk {
  char * memory;
  size_t size;
} MEMORY_CHUNK;

/**************************************************************************//**
 * Global commands that may be sent to the Event Handler thread.
 *****************************************************************************/
typedef enum {
  EVT_CMD_TERMINATE,
  EVT_CMD_MAX_COMMANDS
} EVT_HANDLER_COMMAND;

/**************************************************************************//**
 * State of the Event Handler thread.
 *****************************************************************************/
typedef enum {
  EVT_HANDLER_UNINITIALIZED,      /** The library cannot handle events.      */
  EVT_HANDLER_INACTIVE,           /** The event handler thread not started.  */
  EVT_HANDLER_ACTIVE,             /** The event handler thread is started.   */
  EVT_HANDLER_REQUEST_TERMINATE,  /** Initial stages of shutdown.            */
  EVT_HANDLER_TERMINATING,        /** The ring-buffer is being depleted.     */
  EVT_HANDLER_TERMINATED,         /** The library is exited.                 */
  EVT_HANDLER_MAX_STATES          /** Maximum number of valid states.        */
} EVT_HANDLER_STATE;

/**************************************************************************//**
 * Internal event.
 * Pseudo-event used for routing internal commands.
 *****************************************************************************/
typedef struct event_internal {
  EVENT_HEADER header;
  EVT_HANDLER_COMMAND command;
} EVENT_INTERNAL;

/**************************************************************************//**
 * Suppressed NV pairs list entry.
 * JSON equivalent field: suppressedNvPairs
 *****************************************************************************/
typedef struct evel_suppressed_nv_pairs {

  /***************************************************************************/
  /* Mandatory fields                                                        */
  /* JSON equivalent field: nvPairFieldName                                  */
  /***************************************************************************/
  char * nv_pair_field_name;

  /***************************************************************************/
  /* Optional fields                                                         */
  /* JSON equivalent field: suppressedNvPairNames                            */
  /* Type of each list entry: char *                                         */
  /***************************************************************************/
  DLIST suppressed_nv_pair_names;

  /***************************************************************************/
  /* Hash table containing suppressed_nv_pair_names as keys.                 */
  /***************************************************************************/
  struct hsearch_data * hash_nv_pair_names;

} EVEL_SUPPRESSED_NV_PAIRS;

/**************************************************************************//**
 * Event Throttling Specification for a domain which is in a throttled state.
 * JSON equivalent object: eventThrottlingState
 *****************************************************************************/
typedef struct evel_throttle_spec {

  /***************************************************************************/
  /* List of field names to be suppressed.                                   */
  /* JSON equivalent field: suppressedFieldNames                             */
  /* Type of each list entry: char *                                         */
  /***************************************************************************/
  DLIST suppressed_field_names;

  /***************************************************************************/
  /* List of name-value pairs to be suppressed.                              */
  /* JSON equivalent field: suppressedNvPairsList                            */
  /* Type of each list entry: EVEL_SUPPRESSED_NV_PAIRS *                     */
  /***************************************************************************/
  DLIST suppressed_nv_pairs_list;

  /***************************************************************************/
  /* Hash table containing suppressed_nv_pair_names as keys.                 */
  /***************************************************************************/
  struct hsearch_data * hash_field_names;

  /***************************************************************************/
  /* Hash table containing nv_pair_field_name as keys, and                   */
  /* suppressed_nv_pairs_list as values.                                     */
  /***************************************************************************/
  struct hsearch_data * hash_nv_pairs_list;

} EVEL_THROTTLE_SPEC;

/*****************************************************************************/
/* RFC2822 format string for strftime.                                       */
/*****************************************************************************/
#define EVEL_RFC2822_STRFTIME_FORMAT "%a, %d %b %Y %T %z"

/*****************************************************************************/
/* EVEL_JSON_BUFFER depth at which we throttle fields.                       */
/*****************************************************************************/
#define EVEL_THROTTLE_FIELD_DEPTH 3

/**************************************************************************//**
 * Initialize the event handler.
 *
 * Primarily responsible for getting cURL ready for use.
 *
 * @param[in] event_api_url
 *                      The URL where the Vendor Event Listener API is expected
 *                      to be.
 * @param[in] throt_api_url
 *                      The URL where the Throttling API is expected to be.
 * @param[in] username  The username for the Basic Authentication of requests.
 * @param[in] password  The password for the Basic Authentication of requests.
 * @param     verbosity 0 for normal operation, positive values for chattier
 *                        logs.
 *****************************************************************************/
EVEL_ERR_CODES event_handler_initialize(const char * const event_api_url,
                                        const char * const throt_api_url,
                                        const char * const username,
                                        const char * const password,
                                        int verbosity);

/**************************************************************************//**
 * Terminate the event handler.
 *
 * Shuts down the event handler thread in as clean a way as possible. Sets the
 * global exit flag and then signals the thread to interrupt it since it's
 * most likely waiting on the ring-buffer.
 *
 * Having achieved an orderly shutdown of the event handler thread, clean up
 * the cURL library's resources cleanly.
 *
 *  @return Status code.
 *  @retval ::EVEL_SUCCESS if everything OK.
 *  @retval One of ::EVEL_ERR_CODES if there was a problem.
 *****************************************************************************/
EVEL_ERR_CODES event_handler_terminate();

/**************************************************************************//**
 * Run the event handler.
 *
 * Spawns the thread responsible for handling events and sending them to the
 * API.
 *
 *  @return Status code.
 *  @retval ::EVEL_SUCCESS if everything OK.
 *  @retval One of ::EVEL_ERR_CODES if there was a problem.
 *****************************************************************************/
EVEL_ERR_CODES event_handler_run();

/**************************************************************************//**
 * Create a new internal event.
 *
 * @note    The mandatory fields on the Fault must be supplied to this factory
 *          function and are immutable once set.  Optional fields have explicit
 *          setter functions, but again values may only be set once so that the
 *          Fault has immutable properties.
 * @param   command   The condition indicated by the event.
 * @returns pointer to the newly manufactured ::EVENT_INTERNAL.  If the event
 *          is not used (i.e. posted) it must be released using
 *          ::evel_free_event.
 * @retval  NULL  Failed to create the event.
 *****************************************************************************/
EVENT_INTERNAL * evel_new_internal_event(EVT_HANDLER_COMMAND command);

/**************************************************************************//**
 * Free an internal event.
 *
 * Free off the event supplied.  Will free all the contained* allocated memory.
 *
 * @note It does not free the internal event itself, since that may be part of
 * a larger structure.
 *****************************************************************************/
void evel_free_internal_event(EVENT_INTERNAL * event);

/**************************************************************************//**
 * Initialize an event instance id, typically embedded in an event.
 *
 * @param instance_id   Pointer to the event instance id being initialized.
 * @param vendor_id     The vendor id to encode in the event instance id.
 * @param event_id      The event id to encode in the event instance id.
 *****************************************************************************/
void evel_init_event_instance_id(EVEL_EVENT_INSTANCE_ID * const instance_id,
                                 const char * const vendor_id,
                                 const char * const event_id);

/**************************************************************************//**
 * Free an event instance id.
 *
 * @param instance_id   Pointer to the event instance id being initialized.
 *****************************************************************************/
void evel_free_event_instance_id(EVEL_EVENT_INSTANCE_ID * const instance_id);

/*****************************************************************************/
/* Structure to hold JSON buffer and associated tracking, as it is written.  */
/*****************************************************************************/
typedef struct evel_json_buffer
{
  char * json;
  int offset;
  int max_size;

  /***************************************************************************/
  /* The working throttle specification, which can be NULL.                  */
  /***************************************************************************/
  EVEL_THROTTLE_SPEC * throttle_spec;

  /***************************************************************************/
  /* Current object/list nesting depth.                                      */
  /***************************************************************************/
  int depth;

  /***************************************************************************/
  /* The checkpoint.                                                         */
  /***************************************************************************/
  int checkpoint;

} EVEL_JSON_BUFFER;

/**************************************************************************//**
 * Encode the event as a JSON event object according to AT&T's schema.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_header(EVEL_JSON_BUFFER * jbuf,
                             EVENT_HEADER * event);

/**************************************************************************//**
 * Encode the instance id as a JSON object according to AT&T's schema.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param instance_id   Pointer to the ::EVEL_EVENT_INSTANCE_ID to encode.
 *****************************************************************************/
void evel_json_encode_instance_id(EVEL_JSON_BUFFER * jbuf,
                                  EVEL_EVENT_INSTANCE_ID * instance_id);

/**************************************************************************//**
 * Encode the fault in JSON according to AT&T's schema for the fault type.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_fault(EVEL_JSON_BUFFER * jbuf,
                            EVENT_FAULT * event);

/**************************************************************************//**
 * Encode the measurement as a JSON measurement.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_measurement(EVEL_JSON_BUFFER * jbuf,
                                  EVENT_MEASUREMENT * event);

/**************************************************************************//**
 * Encode the Mobile Flow in JSON according to AT&T's schema for the event
 * type.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_mobile_flow(EVEL_JSON_BUFFER * jbuf,
                                  EVENT_MOBILE_FLOW * event);

/**************************************************************************//**
 * Encode the report as a JSON report.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_report(EVEL_JSON_BUFFER * jbuf,
                             EVENT_REPORT * event);

/**************************************************************************//**
 * Encode the Service Event in JSON according to AT&T's schema for the event
 * type.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_service(EVEL_JSON_BUFFER * const jbuf,
                              EVENT_SERVICE * const event);

/**************************************************************************//**
 * Encode the Signaling in JSON according to AT&T's schema for the event type.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_signaling(EVEL_JSON_BUFFER * const jbuf,
                                EVENT_SIGNALING * const event);

/**************************************************************************//**
 * Encode the state change as a JSON state change.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 *****************************************************************************/
void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
                                   EVENT_STATE_CHANGE * state_change);

/**************************************************************************//**
 * Encode the Syslog in JSON according to AT&T's schema for the event type.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_syslog(EVEL_JSON_BUFFER * jbuf,
                             EVENT_SYSLOG * event);

/**************************************************************************//**
 * Encode the Other in JSON according to AT&T's schema for the event type.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 * @param event         Pointer to the ::EVENT_HEADER to encode.
 *****************************************************************************/
void evel_json_encode_other(EVEL_JSON_BUFFER * jbuf,
                            EVENT_OTHER * event);

/**************************************************************************//**
 * Set the next event_sequence to use.
 *
 * @param sequence      The next sequence number to use.
 *****************************************************************************/
void evel_set_next_event_sequence(const int sequence);

/**************************************************************************//**
 * Handle a JSON response from the listener, contained in a ::MEMORY_CHUNK.
 *
 * Tokenize the response, and decode any tokens found.
 *
 * @param chunk         The memory chunk containing the response.
 * @param post          The memory chunk in which to place any resulting POST.
 *****************************************************************************/
void evel_handle_event_response(const MEMORY_CHUNK * const chunk,
                                MEMORY_CHUNK * const post);

/**************************************************************************//**
 * Initialize a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to initialise.
 * @param json          Pointer to the underlying working buffer to use.
 * @param max_size      Size of storage available in the JSON buffer.
 * @param throttle_spec Pointer to throttle specification. Can be NULL.
 *****************************************************************************/
void evel_json_buffer_init(EVEL_JSON_BUFFER * jbuf,
                           char * const json,
                           const int max_size,
                           EVEL_THROTTLE_SPEC * throttle_spec);

/**************************************************************************//**
 * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param option        Pointer to holder of the corresponding value to encode.
 * @return true if the key, value was added, false if it was suppressed.
 *****************************************************************************/
bool evel_enc_kv_opt_string(EVEL_JSON_BUFFER * jbuf,
                            const char * const key,
                            const EVEL_OPTION_STRING * const option);

/**************************************************************************//**
 * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param value         Pointer to the corresponding value to encode.
 *****************************************************************************/
void evel_enc_kv_string(EVEL_JSON_BUFFER * jbuf,
                        const char * const key,
                        const char * const value);

/**************************************************************************//**
 * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param option        Pointer to holder of the corresponding value to encode.
 * @return true if the key, value was added, false if it was suppressed.
 *****************************************************************************/
bool evel_enc_kv_opt_int(EVEL_JSON_BUFFER * jbuf,
                         const char * const key,
                         const EVEL_OPTION_INT * const option);

/**************************************************************************//**
 * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param value         The corresponding value to encode.
 *****************************************************************************/
void evel_enc_kv_int(EVEL_JSON_BUFFER * jbuf,
                     const char * const key,
                     const int value);

/**************************************************************************//**
 * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param option        Pointer to holder of the corresponding value to encode.
 * @return true if the key, value was added, false if it was suppressed.
 *****************************************************************************/
bool evel_enc_kv_opt_double(EVEL_JSON_BUFFER * jbuf,
                            const char * const key,
                            const EVEL_OPTION_DOUBLE * const option);

/**************************************************************************//**
 * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param value         The corresponding value to encode.
 *****************************************************************************/
void evel_enc_kv_double(EVEL_JSON_BUFFER * jbuf,
                        const char * const key,
                        const double value);

/**************************************************************************//**
 * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param option        Pointer to holder of the corresponding value to encode.
 * @return true if the key, value was added, false if it was suppressed.
 *****************************************************************************/
bool evel_enc_kv_opt_ull(EVEL_JSON_BUFFER * jbuf,
                         const char * const key,
                         const EVEL_OPTION_ULL * const option);

/**************************************************************************//**
 * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param value         The corresponding value to encode.
 *****************************************************************************/
void evel_enc_kv_ull(EVEL_JSON_BUFFER * jbuf,
                     const char * const key,
                     const unsigned long long value);

/**************************************************************************//**
 * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param option        Pointer to holder of the corresponding value to encode.
 * @return true if the key, value was added, false if it was suppressed.
 *****************************************************************************/
bool evel_enc_kv_opt_time(EVEL_JSON_BUFFER * jbuf,
                          const char * const key,
                          const EVEL_OPTION_TIME * const option);

/**************************************************************************//**
 * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param time          Pointer to the time to encode.
 *****************************************************************************/
void evel_enc_kv_time(EVEL_JSON_BUFFER * jbuf,
                      const char * const key,
                      const time_t * time);

/**************************************************************************//**
 * Encode a key and version.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @param major_version The major version to encode.
 * @param minor_version The minor version to encode.
 *****************************************************************************/
void evel_enc_version(EVEL_JSON_BUFFER * jbuf,
                      const char * const key,
                      const int major_version,
                      const int minor_version);

/**************************************************************************//**
 * Add the key and opening bracket of an optional named list to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @return true if the list was opened, false if it was suppressed.
 *****************************************************************************/
bool evel_json_open_opt_named_list(EVEL_JSON_BUFFER * jbuf,
                                   const char * const key);

/**************************************************************************//**
 * Add the key and opening bracket of a named list to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 *****************************************************************************/
void evel_json_open_named_list(EVEL_JSON_BUFFER * jbuf,
                               const char * const key);

/**************************************************************************//**
 * Add the closing bracket of a list to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 *****************************************************************************/
void evel_json_close_list(EVEL_JSON_BUFFER * jbuf);

/**************************************************************************//**
 * Encode a list item with format and param list to a ::EVEL_JSON_BUFFER.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param format        Format string in standard printf format.
 * @param ...           Variable parameters for format string.
 *****************************************************************************/
void evel_enc_list_item(EVEL_JSON_BUFFER * jbuf,
                        const char * const format,
                        ...);

/**************************************************************************//**
 * Add the opening bracket of an optional named object to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 *****************************************************************************/
bool evel_json_open_opt_named_object(EVEL_JSON_BUFFER * jbuf,
                                     const char * const key);

/**************************************************************************//**
 * Add the opening bracket of an object to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 * @param key           Pointer to the key to encode.
 * @return true if the object was opened, false if it was suppressed.
 *****************************************************************************/
void evel_json_open_named_object(EVEL_JSON_BUFFER * jbuf,
                                 const char * const key);

/**************************************************************************//**
 * Add the opening bracket of an object to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 *****************************************************************************/
void evel_json_open_object(EVEL_JSON_BUFFER * jbuf);

/**************************************************************************//**
 * Add the closing bracket of an object to a JSON buffer.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 *****************************************************************************/
void evel_json_close_object(EVEL_JSON_BUFFER * jbuf);

/**************************************************************************//**
 * Add a checkpoint - a stake in the ground to which we can rewind.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 *****************************************************************************/
void evel_json_checkpoint(EVEL_JSON_BUFFER * jbuf);

/**************************************************************************//**
 * Rewind to the latest checkoint.
 *
 * @param jbuf          Pointer to working ::EVEL_JSON_BUFFER.
 *****************************************************************************/
void evel_json_rewind(EVEL_JSON_BUFFER * jbuf);

/**************************************************************************//**
 * Free the underlying resources of an ::EVEL_OPTION_STRING.
 *
 * @param option        Pointer to the ::EVEL_OPTION_STRING.
 *****************************************************************************/
void evel_free_option_string(EVEL_OPTION_STRING * const option);

/**************************************************************************//**
 * Initialize an ::EVEL_OPTION_STRING to a not-set state.
 *
 * @param option        Pointer to the ::EVEL_OPTION_STRING.
 *****************************************************************************/
void evel_init_option_string(EVEL_OPTION_STRING * const option);

/**************************************************************************//**
 * Set the value of an ::EVEL_OPTION_STRING.
 *
 * @param option        Pointer to the ::EVEL_OPTION_STRING.
 * @param value         The value to set.
 * @param description   Description to be used in logging.
 *****************************************************************************/
void evel_set_option_string(EVEL_OPTION_STRING * const option,
                            const char * const value,
                            const char * const description);

/**************************************************************************//**
 * Force the value of an ::EVEL_OPTION_STRING.
 *
 * @param option        Pointer to the ::EVEL_OPTION_STRING.
 * @param value         The value to set.
 *****************************************************************************/
void evel_force_option_string(EVEL_OPTION_STRING * const option,
                              const char * const value);

/**************************************************************************//**
 * Initialize an ::EVEL_OPTION_INT to a not-set state.
 *
 * @param option        Pointer to the ::EVEL_OPTION_INT.
 *****************************************************************************/
void evel_init_option_int(EVEL_OPTION_INT * const option);

/**************************************************************************//**
 * Force the value of an ::EVEL_OPTION_INT.
 *
 * @param option        Pointer to the ::EVEL_OPTION_INT.
 * @param value         The value to set.
 *****************************************************************************/
void evel_force_option_int(EVEL_OPTION_INT * const option,
                           const int value);

/**************************************************************************//**
 * Set the value of an ::EVEL_OPTION_INT.
 *
 * @param option        Pointer to the ::EVEL_OPTION_INT.
 * @param value         The value to set.
 * @param description   Description to be used in logging.
 *****************************************************************************/
void evel_set_option_int(EVEL_OPTION_INT * const option,
                         const int value,
                         const char * const description);

/**************************************************************************//**
 * Initialize an ::EVEL_OPTION_DOUBLE to a not-set state.
 *
 * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 *****************************************************************************/
void evel_init_option_double(EVEL_OPTION_DOUBLE * const option);

/**************************************************************************//**
 * Force the value of an ::EVEL_OPTION_DOUBLE.
 *
 * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 * @param value         The value to set.
 *****************************************************************************/
void evel_force_option_double(EVEL_OPTION_DOUBLE * const option,
                              const double value);

/**************************************************************************//**
 * Set the value of an ::EVEL_OPTION_DOUBLE.
 *
 * @param option        Pointer to the ::EVEL_OPTION_DOUBLE.
 * @param value         The value to set.
 * @param description   Description to be used in logging.
 *****************************************************************************/
void evel_set_option_double(EVEL_OPTION_DOUBLE * const option,
                            const double value,
                            const char * const description);

/**************************************************************************//**
 * Initialize an ::EVEL_OPTION_ULL to a not-set state.
 *
 * @param option        Pointer to the ::EVEL_OPTION_ULL.
 *****************************************************************************/
void evel_init_option_ull(EVEL_OPTION_ULL * const option);

/**************************************************************************//**
 * Force the value of an ::EVEL_OPTION_ULL.
 *
 * @param option        Pointer to the ::EVEL_OPTION_ULL.
 * @param value         The value to set.
 *****************************************************************************/
void evel_force_option_ull(EVEL_OPTION_ULL * const option,
                           const unsigned long long value);

/**************************************************************************//**
 * Set the value of an ::EVEL_OPTION_ULL.
 *
 * @param option        Pointer to the ::EVEL_OPTION_ULL.
 * @param value         The value to set.
 * @param description   Description to be used in logging.
 *****************************************************************************/
void evel_set_option_ull(EVEL_OPTION_ULL * const option,
                         const unsigned long long value,
                         const char * const description);

/**************************************************************************//**
 * Initialize an ::EVEL_OPTION_TIME to a not-set state.
 *
 * @param option        Pointer to the ::EVEL_OPTION_TIME.
 *****************************************************************************/
void evel_init_option_time(EVEL_OPTION_TIME * const option);

/**************************************************************************//**
 * Force the value of an ::EVEL_OPTION_TIME.
 *
 * @param option        Pointer to the ::EVEL_OPTION_TIME.
 * @param value         The value to set.
 *****************************************************************************/
void evel_force_option_time(EVEL_OPTION_TIME * const option,
                            const time_t value);

/**************************************************************************//**
 * Set the value of an ::EVEL_OPTION_TIME.
 *
 * @param option        Pointer to the ::EVEL_OPTION_TIME.
 * @param value         The value to set.
 * @param description   Description to be used in logging.
 *****************************************************************************/
void evel_set_option_time(EVEL_OPTION_TIME * const option,
                          const time_t value,
                          const char * const description);

/**************************************************************************//**
 * Map an ::EVEL_COUNTER_CRITICALITIES enum value to the equivalent string.
 *
 * @param criticality   The criticality to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_criticality(const EVEL_COUNTER_CRITICALITIES criticality);

/**************************************************************************//**
 * Map an ::EVEL_SEVERITIES enum value to the equivalent string.
 *
 * @param severity      The severity to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_severity(const EVEL_SEVERITIES severity);

/**************************************************************************//**
 * Map an ::EVEL_ALERT_ACTIONS enum value to the equivalent string.
 *
 * @param alert_action  The alert_action to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_alert_action(const EVEL_ALERT_ACTIONS alert_action);

/**************************************************************************//**
 * Map an ::EVEL_ALERT_TYPES enum value to the equivalent string.
 *
 * @param alert_type    The alert_type to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_alert_type(const EVEL_ALERT_TYPES alert_type);

/**************************************************************************//**
 * Map an ::EVEL_EVENT_DOMAINS enum value to the equivalent string.
 *
 * @param domain        The domain to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_event_domain(const EVEL_EVENT_DOMAINS domain);

/**************************************************************************//**
 * Map an ::EVEL_EVENT_PRIORITIES enum value to the equivalent string.
 *
 * @param priority      The priority to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_event_priority(const EVEL_EVENT_PRIORITIES priority);

/**************************************************************************//**
 * Map an ::EVEL_SOURCE_TYPES enum value to the equivalent string.
 *
 * @param source_type   The source type to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_source_type(const EVEL_SOURCE_TYPES source_type);

/**************************************************************************//**
 * Map an ::EVEL_VF_STATUSES enum value to the equivalent string.
 *
 * @param vf_status     The vf_status to convert.
 * @returns The equivalent string.
 *****************************************************************************/
char * evel_vf_status(const EVEL_VF_STATUSES vf_status);

/**************************************************************************//**
 * Convert a ::EVEL_ENTITY_STATE to it's string form for JSON encoding.
 *
 * @param state         The entity state to encode.
 *
 * @returns the corresponding string
 *****************************************************************************/
char * evel_entity_state(const EVEL_ENTITY_STATE state);

/**************************************************************************//**
 * Convert a ::EVEL_SERVICE_ENDPOINT_DESC to string form for JSON encoding.
 *
 * @param endpoint_desc endpoint description to encode.
 *
 * @returns the corresponding string
 *****************************************************************************/
char * evel_service_endpoint_desc(const EVEL_ENTITY_STATE endpoint_desc);

#endif