vnfs/VES/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  * @returns pointer to the newly manufactured ::EVENT_FAULT.  If the event is
  57  *          not used (i.e. posted) it must be released using ::evel_free_fault.
  58  * @retval  NULL  Failed to create the event.
  59  *****************************************************************************/
  60 EVENT_FAULT * evel_new_fault(const char * const condition,
  61                              const char * const specific_problem,
  62                              EVEL_EVENT_PRIORITIES priority,
  63                              EVEL_SEVERITIES severity)
  64 {
  65   EVENT_FAULT * fault = NULL;
  66   EVEL_ENTER();
  67
  68   /***************************************************************************/
  69   /* Check preconditions.                                                    */
  70   /***************************************************************************/
  71   assert(condition != NULL);
  72   assert(specific_problem != NULL);
  73   assert(priority < EVEL_MAX_PRIORITIES);
  74   assert(severity < EVEL_MAX_SEVERITIES);
  75
  76   /***************************************************************************/
  77   /* Allocate the fault.                                                     */
  78   /***************************************************************************/
  79   fault = malloc(sizeof(EVENT_FAULT));
  80   if (fault == NULL)
  81   {
  82     log_error_state("Out of memory");
  83     goto exit_label;
  84   }
  85   memset(fault, 0, sizeof(EVENT_FAULT));
  86   EVEL_DEBUG("New fault is at %lp", fault);
  87
  88   /***************************************************************************/
  89   /* Initialize the header & the fault fields.  Optional string values are   */
  90   /* uninitialized (NULL).                                                   */
  91   /***************************************************************************/
  92   evel_init_header(&fault->header);
  93   fault->header.event_domain = EVEL_DOMAIN_FAULT;
  94   fault->header.priority = priority;
  95   fault->major_version = EVEL_FAULT_MAJOR_VERSION;
  96   fault->minor_version = EVEL_FAULT_MINOR_VERSION;
  97   fault->event_severity = severity;
  98   fault->event_source_type = event_source_type;
  99   fault->vf_status = EVEL_VF_STATUS_ACTIVE;
 100   fault->alarm_condition = strdup(condition);
 101   fault->specific_problem = strdup(specific_problem);
 102   evel_init_option_string(&fault->alarm_interface_a);
 103   dlist_initialize(&fault->additional_info);
 104
 105 exit_label:
 106   EVEL_EXIT();
 107   return fault;
 108 }
 109
 110 /**************************************************************************//**
 111  * Add an additional value name/value pair to the Fault.
 112  *
 113  * The name and value are null delimited ASCII strings.  The library takes
 114  * a copy so the caller does not have to preserve values after the function
 115  * returns.
 116  *
 117  * @param fault     Pointer to the fault.
 118  * @param name      ASCIIZ string with the attribute's name.  The caller
 119  *                  does not need to preserve the value once the function
 120  *                  returns.
 121  * @param value     ASCIIZ string with the attribute's value.  The caller
 122  *                  does not need to preserve the value once the function
 123  *                  returns.
 124  *****************************************************************************/
 125 void evel_fault_addl_info_add(EVENT_FAULT * fault, char * name, char * value)
 126 {
 127   FAULT_ADDL_INFO * addl_info = NULL;
 128   EVEL_ENTER();
 129
 130   /***************************************************************************/
 131   /* Check preconditions.                                                    */
 132   /***************************************************************************/
 133   assert(fault != NULL);
 134   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 135   assert(name != NULL);
 136   assert(value != NULL);
 137
 138   EVEL_DEBUG("Adding name=%s value=%s", name, value);
 139   addl_info = malloc(sizeof(FAULT_ADDL_INFO));
 140   assert(addl_info != NULL);
 141   memset(addl_info, 0, sizeof(FAULT_ADDL_INFO));
 142   addl_info->name = strdup(name);
 143   addl_info->value = strdup(value);
 144   assert(addl_info->name != NULL);
 145   assert(addl_info->value != NULL);
 146
 147   dlist_push_last(&fault->additional_info, addl_info);
 148
 149   EVEL_EXIT();
 150 }
 151
 152 /**************************************************************************//**
 153  * Set the Alarm Interface A property of the Fault.
 154  *
 155  * @note  The property is treated as immutable: it is only valid to call
 156  *        the setter once.  However, we don't assert if the caller tries to
 157  *        overwrite, just ignoring the update instead.
 158  *
 159  * @param fault      Pointer to the fault.
 160  * @param interface  The Alarm Interface A to be set. ASCIIZ string. The caller
 161  *                   does not need to preserve the value once the function
 162  *                   returns.
 163  *****************************************************************************/
 164 void evel_fault_interface_set(EVENT_FAULT * fault,
 165                               const char * const interface)
 166 {
 167   EVEL_ENTER();
 168
 169   /***************************************************************************/
 170   /* Check preconditions.                                                    */
 171   /***************************************************************************/
 172   assert(fault != NULL);
 173   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 174   assert(interface != NULL);
 175
 176   evel_set_option_string(&fault->alarm_interface_a,
 177                          interface,
 178                          "Alarm Interface A");
 179   EVEL_EXIT();
 180 }
 181
 182 /**************************************************************************//**
 183  * Set the Event Type property of the Fault.
 184  *
 185  * @note  The property is treated as immutable: it is only valid to call
 186  *        the setter once.  However, we don't assert if the caller tries to
 187  *        overwrite, just ignoring the update instead.
 188  *
 189  * @param fault      Pointer to the fault.
 190  * @param type       The Event Type to be set. ASCIIZ string. The caller
 191  *                   does not need to preserve the value once the function
 192  *                   returns.
 193  *****************************************************************************/
 194 void evel_fault_type_set(EVENT_FAULT * fault, const char * const type)
 195 {
 196   EVEL_ENTER();
 197
 198   /***************************************************************************/
 199   /* Check preconditions and call evel_header_type_set.                      */
 200   /***************************************************************************/
 201   assert(fault != NULL);
 202   assert(fault->header.event_domain == EVEL_DOMAIN_FAULT);
 203   evel_header_type_set(&fault->header, type);
 204
 205   EVEL_EXIT();
 206 }
 207
 208 /**************************************************************************//**
 209  * Encode the fault in JSON according to AT&T's schema for the fault type.
 210  *
 211  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 212  * @param event         Pointer to the ::EVENT_HEADER to encode.
 213  *****************************************************************************/
 214 void evel_json_encode_fault(EVEL_JSON_BUFFER * jbuf,
 215                             EVENT_FAULT * event)
 216 {
 217   FAULT_ADDL_INFO * addl_info = NULL;
 218   DLIST_ITEM * addl_info_item = NULL;
 219   char * fault_severity;
 220   char * fault_source_type;
 221   char * fault_vf_status;
 222
 223   EVEL_ENTER();
 224
 225   /***************************************************************************/
 226   /* Check preconditions.                                                    */
 227   /***************************************************************************/
 228   assert(event != NULL);
 229   assert(event->header.event_domain == EVEL_DOMAIN_FAULT);
 230
 231   fault_severity = evel_severity(event->event_severity);
 232   fault_source_type = evel_source_type(event->event_source_type);
 233   fault_vf_status = evel_vf_status(event->vf_status);
 234
 235   evel_json_encode_header(jbuf, &event->header);
 236   evel_json_open_named_object(jbuf, "faultFields");
 237
 238   /***************************************************************************/
 239   /* Mandatory fields.                                                       */
 240   /***************************************************************************/
 241   evel_enc_kv_string(jbuf, "alarmCondition", event->alarm_condition);
 242   evel_enc_kv_string(jbuf, "eventSeverity", fault_severity);
 243   evel_enc_kv_string(jbuf, "eventSourceType", fault_source_type);
 244   evel_enc_kv_string(jbuf, "specificProblem", event->specific_problem);
 245   evel_enc_kv_string(jbuf, "vfStatus", fault_vf_status);
 246   evel_enc_version(
 247     jbuf, "faultFieldsVersion", event->major_version, event->minor_version);
 248
 249   /***************************************************************************/
 250   /* Optional fields.                                                        */
 251   /***************************************************************************/
 252
 253   /***************************************************************************/
 254   /* Checkpoint, so that we can wind back if all fields are suppressed.      */
 255   /***************************************************************************/
 256   evel_json_checkpoint(jbuf);
 257   if (evel_json_open_opt_named_list(jbuf, "alarmAdditionalInformation"))
 258   {
 259     bool item_added = false;
 260
 261     addl_info_item = dlist_get_first(&event->additional_info);
 262     while (addl_info_item != NULL)
 263     {
 264       addl_info = (FAULT_ADDL_INFO*) addl_info_item->item;
 265       assert(addl_info != NULL);
 266
 267       if (!evel_throttle_suppress_nv_pair(jbuf->throttle_spec,
 268                                           "alarmAdditionalInformation",
 269                                           addl_info->name))
 270       {
 271         evel_json_open_object(jbuf);
 272         evel_enc_kv_string(jbuf, "name", addl_info->name);
 273         evel_enc_kv_string(jbuf, "value", addl_info->value);
 274         evel_json_close_object(jbuf);
 275         item_added = true;
 276       }
 277       addl_info_item = dlist_get_next(addl_info_item);
 278     }
 279     evel_json_close_list(jbuf);
 280
 281     /*************************************************************************/
 282     /* If we've not written anything, rewind to before we opened the list.   */
 283     /*************************************************************************/
 284     if (!item_added)
 285     {
 286       evel_json_rewind(jbuf);
 287     }
 288   }
 289   evel_enc_kv_opt_string(jbuf, "alarmInterfaceA", &event->alarm_interface_a);
 290
 291   evel_json_close_object(jbuf);
 292
 293   EVEL_EXIT();
 294 }
 295
 296 /**************************************************************************//**
 297  * Free a Fault.
 298  *
 299  * Free off the Fault supplied.  Will free all the contained allocated memory.
 300  *
 301  * @note It does not free the Fault itself, since that may be part of a
 302  * larger structure.
 303  *****************************************************************************/
 304 void evel_free_fault(EVENT_FAULT * event)
 305 {
 306   FAULT_ADDL_INFO * addl_info = NULL;
 307
 308   EVEL_ENTER();
 309
 310   /***************************************************************************/
 311   /* Check preconditions.  As an internal API we don't allow freeing NULL    */
 312   /* events as we do on the public API.                                      */
 313   /***************************************************************************/
 314   assert(event != NULL);
 315   assert(event->header.event_domain == EVEL_DOMAIN_FAULT);
 316
 317   /***************************************************************************/
 318   /* Free all internal strings then the header itself.                       */
 319   /***************************************************************************/
 320   addl_info = dlist_pop_last(&event->additional_info);
 321   while (addl_info != NULL)
 322   {
 323     EVEL_DEBUG("Freeing Additional Info (%s, %s)",
 324                addl_info->name,
 325                addl_info->value);
 326     free(addl_info->name);
 327     free(addl_info->value);
 328     free(addl_info);
 329     addl_info = dlist_pop_last(&event->additional_info);
 330   }
 331   free(event->alarm_condition);
 332   evel_free_option_string(&event->alarm_interface_a);
 333   free(event->specific_problem);
 334   evel_free_header(&event->header);
 335
 336   EVEL_EXIT();
 337 }