vnfs/VES5.0/evel/evel-library/code/evel_library/evel_fault.c

   1 /**************************************************************************//**
   2  * @file
   3  * Implementation of EVEL functions relating to the Fault.
   4  *
   5  * License
   6  * -------
   7  *
   8  * Copyright(c) <2016>, AT&T Intellectual Property.  All other rights reserved.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions are met:
  12  *
  13  * 1. Redistributions of source code must retain the above copyright notice,
  14  *    this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright notice,
  16  *    this list of conditions and the following disclaimer in the documentation
  17  *    and/or other materials provided with the distribution.
  18  * 3. All advertising materials mentioning features or use of this software
  19  *    must display the following acknowledgement:  This product includes
  20  *    software developed by the AT&T.
  21  * 4. Neither the name of AT&T nor the names of its contributors may be used to
  22  *    endorse or promote products derived from this software without specific
  23  *    prior written permission.
  24  *
  25  * THIS SOFTWARE IS PROVIDED BY AT&T INTELLECTUAL PROPERTY ''AS IS'' AND ANY
  26  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  27  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  28  * DISCLAIMED. IN NO EVENT SHALL AT&T INTELLECTUAL PROPERTY BE LIABLE FOR ANY
  29  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  30  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  31  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  32  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  33  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  34  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  35  *****************************************************************************/
  36
  37 #include <string.h>
  38 #include <assert.h>
  39 #include <stdlib.h>
  40
  41 #include "evel.h"
  42 #include "evel_internal.h"
  43 #include "evel_throttle.h"
  44
  45 /**************************************************************************//**
  46  * Create a new fault event.
  47  *
  48  * @note    The mandatory fields on the Fault must be supplied to this factory
  49  *          function and are immutable once set.  Optional fields have explicit
  50  *          setter functions, but again values may only be set once so that the
  51  *          Fault has immutable properties.
  52  * @param   condition   The condition indicated by the Fault.
  53  * @param   specific_problem  The specific problem triggering the fault.
  54  * @param   priority    The priority of the event.
  55  * @param   severity    The severity of the Fault.
  56  * @param   ev_source_type    Source of Alarm event
  57  * @param   version     fault version
  58  * @param   status      status of Virtual Function
  59  * @returns pointer to the newly manufactured ::EVENT_FAULT.  If the event is
  60  *          not used (i.e. posted) it must be released using ::evel_free_fault.
  61  * @retval  NULL  Failed to create the event.
  62  *****************************************************************************/
  63 EVENT_FAULT * evel_new_fault(const char * const condition,
  64                              const char * const specific_problem,
  65                              EVEL_EVENT_PRIORITIES priority,
  66                              EVEL_SEVERITIES severity,
  67                              EVEL_SOURCE_TYPES ev_source_type,
  68                              EVEL_VF_STATUSES status)
  69 {
  70   EVENT_FAULT * fault = NULL;
  71   EVEL_ENTER();
  72
  73   /***************************************************************************/
  74   /* Check preconditions.                                                    */
  75   /***************************************************************************/
  76   assert(condition != NULL);
  77   assert(specific_problem != NULL);
  78   assert(priority < EVEL_MAX_PRIORITIES);
  79   assert(severity < EVEL_MAX_SEVERITIES);
  80
  81   /***************************************************************************/
  82   /* Allocate the fault.                                                     */
  83   /***************************************************************************/
  84   fault = malloc(sizeof(EVENT_FAULT));
  85   if (fault == NULL)
  86   {
  87     log_error_state("Out of memory");
  88     goto exit_label;
  89   }
  90   memset(fault, 0, sizeof(EVENT_FAULT));
  91   EVEL_DEBUG("New fault is at %lp", fault);
  92
  93   /***************************************************************************/
  94   /* Initialize the header & the fault fields.  Optional string values are   */
  95   /* uninitialized (NULL).                                                   */
  96   /***************************************************************************/
  97   evel_init_header(&fault->header,"Fault");
  98   fault->header.event_domain = EVEL_DOMAIN_FAULT;
  99   fault->header.priority = priority;
 100   fault->major_version = EVEL_FAULT_MAJOR_VERSION;
 101   fault->minor_version = EVEL_FAULT_MINOR_VERSION;
 102   fault->event_severity = severity;
 103   fault->event_source_type = ev_source_type;
 104   fault->vf_status = status;
 105   fault->alarm_condition = strdup(condition);
 106   fault->specific_problem = strdup(specific_problem);
 107   evel_init_option_string(&fault->category);
 108   evel_init_option_string(&fault->alarm_interface_a);
 109   dlist_initialize(&fault->additional_info);
 110
 111 exit_label:
 112   EVEL_EXIT();
 113   return fault;
 114 }
 115
 116 /**************************************************************************//**
 117  * Add an additional value name/value pair to the Fault.
 118  *
 119  * The name and value are null delimited ASCII strings.  The library takes
 120  * a copy so the caller does not have to preserve values after the function
 121  * returns.
 122  *
 123  * @param fault     Pointer to the fault.
 124  * @param name      ASCIIZ string with the attribute's name.  The caller
 125  *                  does not need to preserve the value once the function
 126  *                  returns.
 127  * @param value     ASCIIZ string with the attribute's value.  The caller
 128  *                  does not need to preserve the value once the function
 129  *                  returns.
 130  *****************************************************************************/
 131 void evel_fault_addl_info_add(EVENT_FAULT * fault, char * name, char * value)
 132 {
 133   FAULT_ADDL_INFO * addl_info = NULL;
 134   EVEL_ENTER();
 135
 136   /***************************************************************************/
 137   /* Check preconditions.                                                    */
 138   /***************************************************************************/
 139   assert(fault != NULL);
 140   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 141   assert(name != NULL);
 142   assert(value != NULL);
 143
 144   EVEL_DEBUG("Adding name=%s value=%s", name, value);
 145   addl_info = malloc(sizeof(FAULT_ADDL_INFO));
 146   assert(addl_info != NULL);
 147   memset(addl_info, 0, sizeof(FAULT_ADDL_INFO));
 148   addl_info->name = strdup(name);
 149   addl_info->value = strdup(value);
 150   assert(addl_info->name != NULL);
 151   assert(addl_info->value != NULL);
 152
 153   dlist_push_last(&fault->additional_info, addl_info);
 154
 155   EVEL_EXIT();
 156 }
 157
 158 /**************************************************************************//**
 159  * Set the Fault Category property of the Fault.
 160  *
 161  * @note  The property is treated as immutable: it is only valid to call
 162  *        the setter once.  However, we don't assert if the caller tries to
 163  *        overwrite, just ignoring the update instead.
 164  *
 165  * @param fault      Pointer to the fault.
 166  * @param category   Category : license, link, routing, security, signaling.
 167  *                       ASCIIZ string. The caller
 168  *                   does not need to preserve the value once the function
 169  *                   returns.
 170  *****************************************************************************/
 171 void evel_fault_category_set(EVENT_FAULT * fault,
 172                               const char * const category)
 173 {
 174   EVEL_ENTER();
 175
 176   /***************************************************************************/
 177   /* Check preconditions.                                                    */
 178   /***************************************************************************/
 179   assert(fault != NULL);
 180   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 181   assert(category != NULL);
 182
 183   evel_set_option_string(&fault->category,
 184                          category,
 185                          "Fault Category set");
 186   EVEL_EXIT();
 187 }
 188
 189 /**************************************************************************//**
 190  * Set the Alarm Interface A property of the Fault.
 191  *
 192  * @note  The property is treated as immutable: it is only valid to call
 193  *        the setter once.  However, we don't assert if the caller tries to
 194  *        overwrite, just ignoring the update instead.
 195  *
 196  * @param fault      Pointer to the fault.
 197  * @param interface  The Alarm Interface A to be set. ASCIIZ string. The caller
 198  *                   does not need to preserve the value once the function
 199  *                   returns.
 200  *****************************************************************************/
 201 void evel_fault_interface_set(EVENT_FAULT * fault,
 202                               const char * const interface)
 203 {
 204   EVEL_ENTER();
 205
 206   /***************************************************************************/
 207   /* Check preconditions.                                                    */
 208   /***************************************************************************/
 209   assert(fault != NULL);
 210   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 211   assert(interface != NULL);
 212
 213   evel_set_option_string(&fault->alarm_interface_a,
 214                          interface,
 215                          "Alarm Interface A");
 216   EVEL_EXIT();
 217 }
 218
 219 /**************************************************************************//**
 220  * Set the Event Type property of the Fault.
 221  *
 222  * @note  The property is treated as immutable: it is only valid to call
 223  *        the setter once.  However, we don't assert if the caller tries to
 224  *        overwrite, just ignoring the update instead.
 225  *
 226  * @param fault      Pointer to the fault.
 227  * @param type       The Event Type to be set. ASCIIZ string. The caller
 228  *                   does not need to preserve the value once the function
 229  *                   returns.
 230  *****************************************************************************/
 231 void evel_fault_type_set(EVENT_FAULT * fault, const char * const type)
 232 {
 233   EVEL_ENTER();
 234
 235   /***************************************************************************/
 236   /* Check preconditions and call evel_header_type_set.                      */
 237   /***************************************************************************/
 238   assert(fault != NULL);
 239   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 240   evel_header_type_set(&fault->header, type);
 241
 242   EVEL_EXIT();
 243 }
 244
 245 /**************************************************************************//**
 246  * Encode the fault in JSON according to AT&T's schema for the fault type.
 247  *
 248  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 249  * @param event         Pointer to the ::EVENT_HEADER to encode.
 250  *****************************************************************************/
 251 void evel_json_encode_fault(EVEL_JSON_BUFFER * jbuf,
 252                             EVENT_FAULT * event)
 253 {
 254   FAULT_ADDL_INFO * addl_info = NULL;
 255   DLIST_ITEM * addl_info_item = NULL;
 256   char * fault_severity;
 257   char * fault_source_type;
 258   char * fault_vf_status;
 259
 260   EVEL_ENTER();
 261
 262   /***************************************************************************/
 263   /* Check preconditions.                                                    */
 264   /***************************************************************************/
 265   assert(event != NULL);
 266   assert(event->header.event_domain == EVEL_DOMAIN_FAULT);
 267
 268   fault_severity = evel_severity(event->event_severity);
 269   fault_source_type = evel_source_type(event->event_source_type);
 270   fault_vf_status = evel_vf_status(event->vf_status);
 271
 272   evel_json_encode_header(jbuf, &event->header);
 273   evel_json_open_named_object(jbuf, "faultFields");
 274
 275   /***************************************************************************/
 276   /* Mandatory fields.                                                       */
 277   /***************************************************************************/
 278   evel_enc_kv_string(jbuf, "alarmCondition", event->alarm_condition);
 279   evel_enc_kv_opt_string(jbuf, "eventCategory", &event->category);
 280   evel_enc_kv_string(jbuf, "eventSeverity", fault_severity);
 281   evel_enc_kv_string(jbuf, "eventSourceType", fault_source_type);
 282   evel_enc_kv_string(jbuf, "specificProblem", event->specific_problem);
 283   evel_enc_kv_string(jbuf, "vfStatus", fault_vf_status);
 284   evel_enc_version(
 285     jbuf, "faultFieldsVersion", event->major_version, event->minor_version);
 286
 287   /***************************************************************************/
 288   /* Optional fields.                                                        */
 289   /***************************************************************************/
 290
 291   /***************************************************************************/
 292   /* Checkpoint, so that we can wind back if all fields are suppressed.      */
 293   /***************************************************************************/
 294   evel_json_checkpoint(jbuf);
 295   if (evel_json_open_opt_named_list(jbuf, "alarmAdditionalInformation"))
 296   {
 297     bool item_added = false;
 298
 299     addl_info_item = dlist_get_first(&event->additional_info);
 300     while (addl_info_item != NULL)
 301     {
 302       addl_info = (FAULT_ADDL_INFO*) addl_info_item->item;
 303       assert(addl_info != NULL);
 304
 305       if (!evel_throttle_suppress_nv_pair(jbuf->throttle_spec,
 306                                           "alarmAdditionalInformation",
 307                                           addl_info->name))
 308       {
 309         evel_json_open_object(jbuf);
 310         evel_enc_kv_string(jbuf, "name", addl_info->name);
 311         evel_enc_kv_string(jbuf, "value", addl_info->value);
 312         evel_json_close_object(jbuf);
 313         item_added = true;
 314       }
 315       addl_info_item = dlist_get_next(addl_info_item);
 316     }
 317     evel_json_close_list(jbuf);
 318
 319     /*************************************************************************/
 320     /* If we've not written anything, rewind to before we opened the list.   */
 321     /*************************************************************************/
 322     if (!item_added)
 323     {
 324       evel_json_rewind(jbuf);
 325     }
 326   }
 327   evel_enc_kv_opt_string(jbuf, "alarmInterfaceA", &event->alarm_interface_a);
 328
 329   evel_json_close_object(jbuf);
 330
 331   EVEL_EXIT();
 332 }
 333
 334 /**************************************************************************//**
 335  * Free a Fault.
 336  *
 337  * Free off the Fault supplied.  Will free all the contained allocated memory.
 338  *
 339  * @note It does not free the Fault itself, since that may be part of a
 340  * larger structure.
 341  *****************************************************************************/
 342 void evel_free_fault(EVENT_FAULT * event)
 343 {
 344   FAULT_ADDL_INFO * addl_info = NULL;
 345
 346   EVEL_ENTER();
 347
 348   /***************************************************************************/
 349   /* Check preconditions.  As an internal API we don't allow freeing NULL    */
 350   /* events as we do on the public API.                                      */
 351   /***************************************************************************/
 352   assert(event != NULL);
 353   assert(event->header.event_domain == EVEL_DOMAIN_FAULT);
 354
 355   /***************************************************************************/
 356   /* Free all internal strings then the header itself.                       */
 357   /***************************************************************************/
 358   addl_info = dlist_pop_last(&event->additional_info);
 359   while (addl_info != NULL)
 360   {
 361     EVEL_DEBUG("Freeing Additional Info (%s, %s)",
 362                addl_info->name,
 363                addl_info->value);
 364     free(addl_info->name);
 365     free(addl_info->value);
 366     free(addl_info);
 367     addl_info = dlist_pop_last(&event->additional_info);
 368   }
 369   free(event->alarm_condition);
 370   free(event->specific_problem);
 371   evel_free_option_string(&event->category);
 372   evel_free_option_string(&event->alarm_interface_a);
 373   evel_free_header(&event->header);
 374
 375   EVEL_EXIT();
 376 }