veslibrary/ves_clibrary/evel/evel-library/code/evel_library/evel_state_change.c

   1 /*************************************************************************//**
   2  *
   3  * Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *        http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  *
  16  ****************************************************************************/
  17 /**************************************************************************//**
  18  * @file
  19  * Implementation of EVEL functions relating to the State Change.
  20  *
  21  ****************************************************************************/
  22
  23 #include <string.h>
  24 #include <assert.h>
  25 #include <stdlib.h>
  26
  27 #include "evel_throttle.h"
  28
  29 /**************************************************************************//**
  30  * Create a new State Change event.
  31  *
  32  * @note    The mandatory fields on the State Change must be supplied to this
  33  *          factory function and are immutable once set.  Optional fields have
  34  *          explicit setter functions, but again values may only be set once
  35  *          so that the State Change has immutable properties.
  36  *
  37  * @param event_name  Unique Event Name confirming Domain AsdcModel Description
  38  * @param event_id    A universal identifier of the event for: troubleshooting correlation, analysis, etc
  39  * @param new_state     The new state of the reporting entity.
  40  * @param old_state     The old state of the reporting entity.
  41  * @param interface     The card or port name of the reporting entity.
  42  *
  43  * @returns pointer to the newly manufactured ::EVENT_STATE_CHANGE.  If the
  44  *          event is not used it must be released using
  45  *          ::evel_free_state_change
  46  * @retval  NULL  Failed to create the event.
  47  *****************************************************************************/
  48 EVENT_STATE_CHANGE * evel_new_state_change(const char* ev_name,
  49                                            const char *ev_id,
  50                                            const EVEL_ENTITY_STATE new_state,
  51                                            const EVEL_ENTITY_STATE old_state,
  52                                            const char * const interface)
  53 {
  54   EVENT_STATE_CHANGE * state_change = NULL;
  55   EVEL_ENTER();
  56
  57   /***************************************************************************/
  58   /* Check preconditions.                                                    */
  59   /***************************************************************************/
  60   assert(new_state < EVEL_MAX_ENTITY_STATES);
  61   assert(old_state < EVEL_MAX_ENTITY_STATES);
  62   assert(interface != NULL);
  63
  64   /***************************************************************************/
  65   /* Allocate the State Change.                                              */
  66   /***************************************************************************/
  67   state_change = malloc(sizeof(EVENT_STATE_CHANGE));
  68   if (state_change == NULL)
  69   {
  70     log_error_state("Out of memory");
  71     goto exit_label;
  72   }
  73   memset(state_change, 0, sizeof(EVENT_STATE_CHANGE));
  74   EVEL_DEBUG("New State Change is at %lp", state_change);
  75
  76   /***************************************************************************/
  77   /* Initialize the header & the State Change fields.  Optional string       */
  78   /* values are uninitialized (NULL).                                        */
  79   /***************************************************************************/
  80   evel_init_header_nameid(&state_change->header,ev_name,ev_id);
  81   state_change->header.event_domain = EVEL_DOMAIN_STATE_CHANGE;
  82   state_change->major_version = EVEL_STATE_CHANGE_MAJOR_VERSION;
  83   state_change->minor_version = EVEL_STATE_CHANGE_MINOR_VERSION;
  84   state_change->new_state = new_state;
  85   state_change->old_state = old_state;
  86   state_change->state_interface = strdup(interface);
  87   dlist_initialize(&state_change->additional_fields);
  88
  89 exit_label:
  90   EVEL_EXIT();
  91   return state_change;
  92 }
  93
  94 /**************************************************************************//**
  95  * Free a State Change.
  96  *
  97  * Free off the State Change supplied.  Will free all the contained allocated
  98  * memory.
  99  *
 100  * @note It does not free the State Change itself, since that may be part of a
 101  * larger structure.
 102  *****************************************************************************/
 103 void evel_free_state_change(EVENT_STATE_CHANGE * const state_change)
 104 {
 105   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 106
 107   EVEL_ENTER();
 108
 109   /***************************************************************************/
 110   /* Check preconditions.  As an internal API we don't allow freeing NULL    */
 111   /* events as we do on the public API.                                      */
 112   /***************************************************************************/
 113   assert(state_change != NULL);
 114   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 115
 116   /***************************************************************************/
 117   /* Free all internal strings then the header itself.                       */
 118   /***************************************************************************/
 119   addl_field = dlist_pop_last(&state_change->additional_fields);
 120   while (addl_field != NULL)
 121   {
 122     EVEL_DEBUG("Freeing Additional Field (%s, %s)",
 123                addl_field->name,
 124                addl_field->value);
 125     free(addl_field->name);
 126     free(addl_field->value);
 127     free(addl_field);
 128     addl_field = dlist_pop_last(&state_change->additional_fields);
 129   }
 130   free(state_change->state_interface);
 131   evel_free_header(&state_change->header);
 132
 133   EVEL_EXIT();
 134 }
 135
 136 /**************************************************************************//**
 137  * Set the Event Type property of the State Change.
 138  *
 139  * @note  The property is treated as immutable: it is only valid to call
 140  *        the setter once.  However, we don't assert if the caller tries to
 141  *        overwrite, just ignoring the update instead.
 142  *
 143  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
 144  * @param type          The Event Type to be set. ASCIIZ string. The caller
 145  *                      does not need to preserve the value once the function
 146  *                      returns.
 147  *****************************************************************************/
 148 void evel_state_change_type_set(EVENT_STATE_CHANGE * const state_change,
 149                                 const char * const type)
 150 {
 151   EVEL_ENTER();
 152
 153   /***************************************************************************/
 154   /* Check preconditions and call evel_header_type_set.                      */
 155   /***************************************************************************/
 156   assert(state_change != NULL);
 157   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 158   evel_header_type_set(&state_change->header, type);
 159
 160   EVEL_EXIT();
 161 }
 162
 163 /**************************************************************************//**
 164  * Add an additional field name/value pair to the State Change.
 165  *
 166  * The name and value are null delimited ASCII strings.  The library takes
 167  * a copy so the caller does not have to preserve values after the function
 168  * returns.
 169  *
 170  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
 171  * @param name          ASCIIZ string with the attribute's name.  The caller
 172  *                      does not need to preserve the value once the function
 173  *                      returns.
 174  * @param value         ASCIIZ string with the attribute's value.  The caller
 175  *                      does not need to preserve the value once the function
 176  *                      returns.
 177  *****************************************************************************/
 178 void evel_state_change_addl_field_add(EVENT_STATE_CHANGE * const state_change,
 179                                       const char * const name,
 180                                       const char * const value)
 181 {
 182   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 183   EVEL_ENTER();
 184
 185   /***************************************************************************/
 186   /* Check preconditions.                                                    */
 187   /***************************************************************************/
 188   assert(state_change != NULL);
 189   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 190   assert(name != NULL);
 191   assert(value != NULL);
 192
 193   EVEL_DEBUG("Adding name=%s value=%s", name, value);
 194   addl_field = malloc(sizeof(STATE_CHANGE_ADDL_FIELD));
 195   assert(addl_field != NULL);
 196   memset(addl_field, 0, sizeof(STATE_CHANGE_ADDL_FIELD));
 197   addl_field->name = strdup(name);
 198   addl_field->value = strdup(value);
 199   assert(addl_field->name != NULL);
 200   assert(addl_field->value != NULL);
 201
 202   dlist_push_last(&state_change->additional_fields, addl_field);
 203
 204   EVEL_EXIT();
 205 }
 206
 207 /**************************************************************************//**
 208  * Encode the state change as a JSON state change.
 209  *
 210  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 211  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 212  *****************************************************************************/
 213 void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
 214                                    EVENT_STATE_CHANGE * state_change)
 215 {
 216   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 217   DLIST_ITEM * addl_field_item = NULL;
 218   char * new_state;
 219   char * old_state;
 220
 221   EVEL_ENTER();
 222
 223   /***************************************************************************/
 224   /* Check preconditions.                                                    */
 225   /***************************************************************************/
 226   assert(state_change != NULL);
 227   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 228
 229   new_state = evel_entity_state(state_change->new_state);
 230   old_state = evel_entity_state(state_change->old_state);
 231
 232   evel_json_encode_header(jbuf, &state_change->header);
 233   evel_json_open_named_object(jbuf, "stateChangeFields");
 234
 235   /***************************************************************************/
 236   /* Mandatory fields.                                                       */
 237   /***************************************************************************/
 238   evel_enc_kv_string(jbuf, "newState", new_state);
 239   evel_enc_kv_string(jbuf, "oldState", old_state);
 240   evel_enc_kv_string(jbuf, "stateInterface", state_change->state_interface);
 241
 242   /***************************************************************************/
 243   /* Optional fields.                                                        */
 244   /***************************************************************************/
 245   evel_json_checkpoint(jbuf);
 246   if (evel_json_open_opt_named_list(jbuf, "additionalFields"))
 247   {
 248     bool item_added = false;
 249
 250     addl_field_item = dlist_get_first(&state_change->additional_fields);
 251     while (addl_field_item != NULL)
 252     {
 253       addl_field = (STATE_CHANGE_ADDL_FIELD *) addl_field_item->item;
 254       assert(addl_field != NULL);
 255
 256       if (!evel_throttle_suppress_nv_pair(jbuf->throttle_spec,
 257                                           "additionalFields",
 258                                           addl_field->name))
 259       {
 260         evel_json_open_object(jbuf);
 261         evel_enc_kv_string(jbuf, "name", addl_field->name);
 262         evel_enc_kv_string(jbuf, "value", addl_field->value);
 263         evel_json_close_object(jbuf);
 264         item_added = true;
 265       }
 266       addl_field_item = dlist_get_next(addl_field_item);
 267     }
 268     evel_json_close_list(jbuf);
 269
 270     /*************************************************************************/
 271     /* If we've not written anything, rewind to before we opened the list.   */
 272     /*************************************************************************/
 273     if (!item_added)
 274     {
 275       evel_json_rewind(jbuf);
 276     }
 277   }
 278
 279   evel_enc_version(jbuf,
 280                    "stateChangeFieldsVersion",
 281                    state_change->major_version,state_change->minor_version);
 282
 283   evel_json_close_object(jbuf);
 284
 285   EVEL_EXIT();
 286 }