1 #ifndef EVEL_INTERNAL_INCLUDED
2 #define EVEL_INTERNAL_INCLUDED
4 /**************************************************************************//**
6 * EVEL internal definitions.
8 * These are internal definitions which need to be shared between modules
9 * within the library but are not intended for external consumption.
14 * Copyright(c) <2016>, AT&T Intellectual Property. All other rights reserved.
16 * Redistribution and use in source and binary forms, with or without
17 * modification, are permitted provided that the following conditions are met:
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.
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 *****************************************************************************/
45 /*****************************************************************************/
46 /* Define some type-safe min/max macros. */
47 /*****************************************************************************/
49 ({ __typeof__ (a) _a = (a); \
50 __typeof__ (b) _b = (b); \
54 ({ __typeof__ (a) _a = (a); \
55 __typeof__ (b) _b = (b); \
59 /**************************************************************************//**
60 * Compile-time assertion.
61 *****************************************************************************/
62 #define EVEL_CT_ASSERT(X) switch (0) {case 0: case (X):;}
64 /**************************************************************************//**
65 * The Functional Role of the equipment represented by this VNF.
66 *****************************************************************************/
67 extern char * functional_role;
69 /**************************************************************************//**
70 * The type of equipment represented by this VNF.
71 *****************************************************************************/
72 extern EVEL_SOURCE_TYPES event_source_type;
74 /**************************************************************************//**
75 * A chunk of memory used in the cURL functions.
76 *****************************************************************************/
77 typedef struct memory_chunk {
82 /**************************************************************************//**
83 * Global commands that may be sent to the Event Handler thread.
84 *****************************************************************************/
88 } EVT_HANDLER_COMMAND;
90 /**************************************************************************//**
91 * State of the Event Handler thread.
92 *****************************************************************************/
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. */
103 /**************************************************************************//**
105 * Pseudo-event used for routing internal commands.
106 *****************************************************************************/
107 typedef struct event_internal {
109 EVT_HANDLER_COMMAND command;
112 /**************************************************************************//**
113 * Suppressed NV pairs list entry.
114 * JSON equivalent field: suppressedNvPairs
115 *****************************************************************************/
116 typedef struct evel_suppressed_nv_pairs {
118 /***************************************************************************/
119 /* Mandatory fields */
120 /* JSON equivalent field: nvPairFieldName */
121 /***************************************************************************/
122 char * nv_pair_field_name;
124 /***************************************************************************/
125 /* Optional fields */
126 /* JSON equivalent field: suppressedNvPairNames */
127 /* Type of each list entry: char * */
128 /***************************************************************************/
129 DLIST suppressed_nv_pair_names;
131 /***************************************************************************/
132 /* Hash table containing suppressed_nv_pair_names as keys. */
133 /***************************************************************************/
134 struct hsearch_data * hash_nv_pair_names;
136 } EVEL_SUPPRESSED_NV_PAIRS;
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 {
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;
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;
158 /***************************************************************************/
159 /* Hash table containing suppressed_nv_pair_names as keys. */
160 /***************************************************************************/
161 struct hsearch_data * hash_field_names;
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;
169 } EVEL_THROTTLE_SPEC;
171 /*****************************************************************************/
172 /* RFC2822 format string for strftime. */
173 /*****************************************************************************/
174 #define EVEL_RFC2822_STRFTIME_FORMAT "%a, %d %b %Y %T %z"
176 /*****************************************************************************/
177 /* EVEL_JSON_BUFFER depth at which we throttle fields. */
178 /*****************************************************************************/
179 #define EVEL_THROTTLE_FIELD_DEPTH 3
181 /**************************************************************************//**
182 * Initialize the event handler.
184 * Primarily responsible for getting cURL ready for use.
186 * @param[in] event_api_url
187 * The URL where the Vendor Event Listener API is expected
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
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,
202 /**************************************************************************//**
203 * Terminate the event handler.
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.
209 * Having achieved an orderly shutdown of the event handler thread, clean up
210 * the cURL library's resources cleanly.
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();
218 /**************************************************************************//**
219 * Run the event handler.
221 * Spawns the thread responsible for handling events and sending them to the
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();
230 /**************************************************************************//**
231 * Create a new internal event.
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
241 * @retval NULL Failed to create the event.
242 *****************************************************************************/
243 EVENT_INTERNAL * evel_new_internal_event(EVT_HANDLER_COMMAND command);
245 /**************************************************************************//**
246 * Free an internal event.
248 * Free off the event supplied. Will free all the contained* allocated memory.
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);
255 /**************************************************************************//**
256 * Initialize an event instance id, typically embedded in an event.
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);
266 /**************************************************************************//**
267 * Free an event instance id.
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);
273 /*****************************************************************************/
274 /* Structure to hold JSON buffer and associated tracking, as it is written. */
275 /*****************************************************************************/
276 typedef struct evel_json_buffer
282 /***************************************************************************/
283 /* The working throttle specification, which can be NULL. */
284 /***************************************************************************/
285 EVEL_THROTTLE_SPEC * throttle_spec;
287 /***************************************************************************/
288 /* Current object/list nesting depth. */
289 /***************************************************************************/
292 /***************************************************************************/
293 /* The checkpoint. */
294 /***************************************************************************/
299 /**************************************************************************//**
300 * Encode the event as a JSON event object according to AT&T's schema.
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);
308 /**************************************************************************//**
309 * Encode the instance id as a JSON object according to AT&T's schema.
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);
317 /**************************************************************************//**
318 * Encode the fault in JSON according to AT&T's schema for the fault type.
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);
326 /**************************************************************************//**
327 * Encode the measurement as a JSON measurement.
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);
335 /**************************************************************************//**
336 * Encode the Mobile Flow in JSON according to AT&T's schema for the event
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);
345 /**************************************************************************//**
346 * Encode the report as a JSON report.
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);
354 /**************************************************************************//**
355 * Encode the Service Event in JSON according to AT&T's schema for the event
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);
364 /**************************************************************************//**
365 * Encode the Signaling in JSON according to AT&T's schema for the event type.
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);
373 /**************************************************************************//**
374 * Encode the state change as a JSON state change.
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);
382 /**************************************************************************//**
383 * Encode the Syslog in JSON according to AT&T's schema for the event type.
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);
391 /**************************************************************************//**
392 * Encode the Other in JSON according to AT&T's schema for the event type.
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);
400 /**************************************************************************//**
401 * Set the next event_sequence to use.
403 * @param sequence The next sequence number to use.
404 *****************************************************************************/
405 void evel_set_next_event_sequence(const int sequence);
407 /**************************************************************************//**
408 * Handle a JSON response from the listener, contained in a ::MEMORY_CHUNK.
410 * Tokenize the response, and decode any tokens found.
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);
418 /**************************************************************************//**
419 * Initialize a ::EVEL_JSON_BUFFER.
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,
429 EVEL_THROTTLE_SPEC * throttle_spec);
431 /**************************************************************************//**
432 * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
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);
443 /**************************************************************************//**
444 * Encode a string key and string value to a ::EVEL_JSON_BUFFER.
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);
454 /**************************************************************************//**
455 * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
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);
466 /**************************************************************************//**
467 * Encode a string key and integer value to a ::EVEL_JSON_BUFFER.
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,
477 /**************************************************************************//**
478 * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
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);
489 /**************************************************************************//**
490 * Encode a string key and double value to a ::EVEL_JSON_BUFFER.
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,
500 /**************************************************************************//**
501 * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
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);
512 /**************************************************************************//**
513 * Encode a string key and unsigned long long value to a ::EVEL_JSON_BUFFER.
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);
523 /**************************************************************************//**
524 * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
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);
535 /**************************************************************************//**
536 * Encode a string key and time value to a ::EVEL_JSON_BUFFER.
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);
546 /**************************************************************************//**
547 * Encode a key and version.
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);
559 /**************************************************************************//**
560 * Add the key and opening bracket of an optional named list to a JSON buffer.
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);
569 /**************************************************************************//**
570 * Add the key and opening bracket of a named list to a JSON buffer.
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);
578 /**************************************************************************//**
579 * Add the closing bracket of a list to a JSON buffer.
581 * @param jbuf Pointer to working ::EVEL_JSON_BUFFER.
582 *****************************************************************************/
583 void evel_json_close_list(EVEL_JSON_BUFFER * jbuf);
585 /**************************************************************************//**
586 * Encode a list item with format and param list to a ::EVEL_JSON_BUFFER.
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,
596 /**************************************************************************//**
597 * Add the opening bracket of an optional named object to a JSON buffer.
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);
605 /**************************************************************************//**
606 * Add the opening bracket of an object to a JSON buffer.
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);
615 /**************************************************************************//**
616 * Add the opening bracket of an object to a JSON buffer.
618 * @param jbuf Pointer to working ::EVEL_JSON_BUFFER.
619 *****************************************************************************/
620 void evel_json_open_object(EVEL_JSON_BUFFER * jbuf);
622 /**************************************************************************//**
623 * Add the closing bracket of an object to a JSON buffer.
625 * @param jbuf Pointer to working ::EVEL_JSON_BUFFER.
626 *****************************************************************************/
627 void evel_json_close_object(EVEL_JSON_BUFFER * jbuf);
629 /**************************************************************************//**
630 * Add a checkpoint - a stake in the ground to which we can rewind.
632 * @param jbuf Pointer to working ::EVEL_JSON_BUFFER.
633 *****************************************************************************/
634 void evel_json_checkpoint(EVEL_JSON_BUFFER * jbuf);
636 /**************************************************************************//**
637 * Rewind to the latest checkoint.
639 * @param jbuf Pointer to working ::EVEL_JSON_BUFFER.
640 *****************************************************************************/
641 void evel_json_rewind(EVEL_JSON_BUFFER * jbuf);
643 /**************************************************************************//**
644 * Free the underlying resources of an ::EVEL_OPTION_STRING.
646 * @param option Pointer to the ::EVEL_OPTION_STRING.
647 *****************************************************************************/
648 void evel_free_option_string(EVEL_OPTION_STRING * const option);
650 /**************************************************************************//**
651 * Initialize an ::EVEL_OPTION_STRING to a not-set state.
653 * @param option Pointer to the ::EVEL_OPTION_STRING.
654 *****************************************************************************/
655 void evel_init_option_string(EVEL_OPTION_STRING * const option);
657 /**************************************************************************//**
658 * Set the value of an ::EVEL_OPTION_STRING.
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);
668 /**************************************************************************//**
669 * Force the value of an ::EVEL_OPTION_STRING.
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);
677 /**************************************************************************//**
678 * Initialize an ::EVEL_OPTION_INT to a not-set state.
680 * @param option Pointer to the ::EVEL_OPTION_INT.
681 *****************************************************************************/
682 void evel_init_option_int(EVEL_OPTION_INT * const option);
684 /**************************************************************************//**
685 * Force the value of an ::EVEL_OPTION_INT.
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,
693 /**************************************************************************//**
694 * Set the value of an ::EVEL_OPTION_INT.
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,
702 const char * const description);
704 /**************************************************************************//**
705 * Initialize an ::EVEL_OPTION_DOUBLE to a not-set state.
707 * @param option Pointer to the ::EVEL_OPTION_DOUBLE.
708 *****************************************************************************/
709 void evel_init_option_double(EVEL_OPTION_DOUBLE * const option);
711 /**************************************************************************//**
712 * Force the value of an ::EVEL_OPTION_DOUBLE.
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,
720 /**************************************************************************//**
721 * Set the value of an ::EVEL_OPTION_DOUBLE.
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,
729 const char * const description);
731 /**************************************************************************//**
732 * Initialize an ::EVEL_OPTION_ULL to a not-set state.
734 * @param option Pointer to the ::EVEL_OPTION_ULL.
735 *****************************************************************************/
736 void evel_init_option_ull(EVEL_OPTION_ULL * const option);
738 /**************************************************************************//**
739 * Force the value of an ::EVEL_OPTION_ULL.
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);
747 /**************************************************************************//**
748 * Set the value of an ::EVEL_OPTION_ULL.
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);
758 /**************************************************************************//**
759 * Initialize an ::EVEL_OPTION_TIME to a not-set state.
761 * @param option Pointer to the ::EVEL_OPTION_TIME.
762 *****************************************************************************/
763 void evel_init_option_time(EVEL_OPTION_TIME * const option);
765 /**************************************************************************//**
766 * Force the value of an ::EVEL_OPTION_TIME.
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,
774 /**************************************************************************//**
775 * Set the value of an ::EVEL_OPTION_TIME.
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,
783 const char * const description);
785 /**************************************************************************//**
786 * Map an ::EVEL_COUNTER_CRITICALITIES enum value to the equivalent string.
788 * @param criticality The criticality to convert.
789 * @returns The equivalent string.
790 *****************************************************************************/
791 char * evel_criticality(const EVEL_COUNTER_CRITICALITIES criticality);
793 /**************************************************************************//**
794 * Map an ::EVEL_SEVERITIES enum value to the equivalent string.
796 * @param severity The severity to convert.
797 * @returns The equivalent string.
798 *****************************************************************************/
799 char * evel_severity(const EVEL_SEVERITIES severity);
801 /**************************************************************************//**
802 * Map an ::EVEL_ALERT_ACTIONS enum value to the equivalent string.
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);
809 /**************************************************************************//**
810 * Map an ::EVEL_ALERT_TYPES enum value to the equivalent string.
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);
817 /**************************************************************************//**
818 * Map an ::EVEL_EVENT_DOMAINS enum value to the equivalent string.
820 * @param domain The domain to convert.
821 * @returns The equivalent string.
822 *****************************************************************************/
823 char * evel_event_domain(const EVEL_EVENT_DOMAINS domain);
825 /**************************************************************************//**
826 * Map an ::EVEL_EVENT_PRIORITIES enum value to the equivalent string.
828 * @param priority The priority to convert.
829 * @returns The equivalent string.
830 *****************************************************************************/
831 char * evel_event_priority(const EVEL_EVENT_PRIORITIES priority);
833 /**************************************************************************//**
834 * Map an ::EVEL_SOURCE_TYPES enum value to the equivalent string.
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);
841 /**************************************************************************//**
842 * Map an ::EVEL_VF_STATUSES enum value to the equivalent string.
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);
849 /**************************************************************************//**
850 * Convert a ::EVEL_ENTITY_STATE to it's string form for JSON encoding.
852 * @param state The entity state to encode.
854 * @returns the corresponding string
855 *****************************************************************************/
856 char * evel_entity_state(const EVEL_ENTITY_STATE state);
858 /**************************************************************************//**
859 * Convert a ::EVEL_SERVICE_ENDPOINT_DESC to string form for JSON encoding.
861 * @param endpoint_desc endpoint description to encode.
863 * @returns the corresponding string
864 *****************************************************************************/
865 char * evel_service_endpoint_desc(const EVEL_ENTITY_STATE endpoint_desc);