vnfs/VES5.0/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 new_state     The new state of the reporting entity.
  38  * @param old_state     The old state of the reporting entity.
  39  * @param interface     The card or port name of the reporting entity.
  40  *
  41  * @returns pointer to the newly manufactured ::EVENT_STATE_CHANGE.  If the
  42  *          event is not used it must be released using
  43  *          ::evel_free_state_change
  44  * @retval  NULL  Failed to create the event.
  45  *****************************************************************************/
  46 EVENT_STATE_CHANGE * evel_new_state_change(const EVEL_ENTITY_STATE new_state,
  47                                            const EVEL_ENTITY_STATE old_state,
  48                                            const char * const interface)
  49 {
  50   EVENT_STATE_CHANGE * state_change = NULL;
  51   EVEL_ENTER();
  52
  53   /***************************************************************************/
  54   /* Check preconditions.                                                    */
  55   /***************************************************************************/
  56   assert(new_state < EVEL_MAX_ENTITY_STATES);
  57   assert(old_state < EVEL_MAX_ENTITY_STATES);
  58   assert(interface != NULL);
  59
  60   /***************************************************************************/
  61   /* Allocate the State Change.                                              */
  62   /***************************************************************************/
  63   state_change = malloc(sizeof(EVENT_STATE_CHANGE));
  64   if (state_change == NULL)
  65   {
  66     log_error_state("Out of memory");
  67     goto exit_label;
  68   }
  69   memset(state_change, 0, sizeof(EVENT_STATE_CHANGE));
  70   EVEL_DEBUG("New State Change is at %lp", state_change);
  71
  72   /***************************************************************************/
  73   /* Initialize the header & the State Change fields.  Optional string       */
  74   /* values are uninitialized (NULL).                                        */
  75   /***************************************************************************/
  76   evel_init_header(&state_change->header,"StateChange");
  77   state_change->header.event_domain = EVEL_DOMAIN_STATE_CHANGE;
  78   state_change->major_version = EVEL_STATE_CHANGE_MAJOR_VERSION;
  79   state_change->minor_version = EVEL_STATE_CHANGE_MINOR_VERSION;
  80   state_change->new_state = new_state;
  81   state_change->old_state = old_state;
  82   state_change->state_interface = strdup(interface);
  83   dlist_initialize(&state_change->additional_fields);
  84
  85 exit_label:
  86   EVEL_EXIT();
  87   return state_change;
  88 }
  89
  90 /**************************************************************************//**
  91  * Free a State Change.
  92  *
  93  * Free off the State Change supplied.  Will free all the contained allocated
  94  * memory.
  95  *
  96  * @note It does not free the State Change itself, since that may be part of a
  97  * larger structure.
  98  *****************************************************************************/
  99 void evel_free_state_change(EVENT_STATE_CHANGE * const state_change)
 100 {
 101   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 102
 103   EVEL_ENTER();
 104
 105   /***************************************************************************/
 106   /* Check preconditions.  As an internal API we don't allow freeing NULL    */
 107   /* events as we do on the public API.                                      */
 108   /***************************************************************************/
 109   assert(state_change != NULL);
 110   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 111
 112   /***************************************************************************/
 113   /* Free all internal strings then the header itself.                       */
 114   /***************************************************************************/
 115   addl_field = dlist_pop_last(&state_change->additional_fields);
 116   while (addl_field != NULL)
 117   {
 118     EVEL_DEBUG("Freeing Additional Field (%s, %s)",
 119                addl_field->name,
 120                addl_field->value);
 121     free(addl_field->name);
 122     free(addl_field->value);
 123     free(addl_field);
 124     addl_field = dlist_pop_last(&state_change->additional_fields);
 125   }
 126   free(state_change->state_interface);
 127   evel_free_header(&state_change->header);
 128
 129   EVEL_EXIT();
 130 }
 131
 132 /**************************************************************************//**
 133  * Set the Event Type property of the State Change.
 134  *
 135  * @note  The property is treated as immutable: it is only valid to call
 136  *        the setter once.  However, we don't assert if the caller tries to
 137  *        overwrite, just ignoring the update instead.
 138  *
 139  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
 140  * @param type          The Event Type to be set. ASCIIZ string. The caller
 141  *                      does not need to preserve the value once the function
 142  *                      returns.
 143  *****************************************************************************/
 144 void evel_state_change_type_set(EVENT_STATE_CHANGE * const state_change,
 145                                 const char * const type)
 146 {
 147   EVEL_ENTER();
 148
 149   /***************************************************************************/
 150   /* Check preconditions and call evel_header_type_set.                      */
 151   /***************************************************************************/
 152   assert(state_change != NULL);
 153   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 154   evel_header_type_set(&state_change->header, type);
 155
 156   EVEL_EXIT();
 157 }
 158
 159 /**************************************************************************//**
 160  * Add an additional field name/value pair to the State Change.
 161  *
 162  * The name and value are null delimited ASCII strings.  The library takes
 163  * a copy so the caller does not have to preserve values after the function
 164  * returns.
 165  *
 166  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
 167  * @param name          ASCIIZ string with the attribute's name.  The caller
 168  *                      does not need to preserve the value once the function
 169  *                      returns.
 170  * @param value         ASCIIZ string with the attribute's value.  The caller
 171  *                      does not need to preserve the value once the function
 172  *                      returns.
 173  *****************************************************************************/
 174 void evel_state_change_addl_field_add(EVENT_STATE_CHANGE * const state_change,
 175                                       const char * const name,
 176                                       const char * const value)
 177 {
 178   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 179   EVEL_ENTER();
 180
 181   /***************************************************************************/
 182   /* Check preconditions.                                                    */
 183   /***************************************************************************/
 184   assert(state_change != NULL);
 185   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 186   assert(name != NULL);
 187   assert(value != NULL);
 188
 189   EVEL_DEBUG("Adding name=%s value=%s", name, value);
 190   addl_field = malloc(sizeof(STATE_CHANGE_ADDL_FIELD));
 191   assert(addl_field != NULL);
 192   memset(addl_field, 0, sizeof(STATE_CHANGE_ADDL_FIELD));
 193   addl_field->name = strdup(name);
 194   addl_field->value = strdup(value);
 195   assert(addl_field->name != NULL);
 196   assert(addl_field->value != NULL);
 197
 198   dlist_push_last(&state_change->additional_fields, addl_field);
 199
 200   EVEL_EXIT();
 201 }
 202
 203 /**************************************************************************//**
 204  * Encode the state change as a JSON state change.
 205  *
 206  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 207  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 208  *****************************************************************************/
 209 void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
 210                                    EVENT_STATE_CHANGE * state_change)
 211 {
 212   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 213   DLIST_ITEM * addl_field_item = NULL;
 214   char * new_state;
 215   char * old_state;
 216
 217   EVEL_ENTER();
 218
 219   /***************************************************************************/
 220   /* Check preconditions.                                                    */
 221   /***************************************************************************/
 222   assert(state_change != NULL);
 223   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 224
 225   new_state = evel_entity_state(state_change->new_state);
 226   old_state = evel_entity_state(state_change->old_state);
 227
 228   evel_json_encode_header(jbuf, &state_change->header);
 229   evel_json_open_named_object(jbuf, "stateChangeFields");
 230
 231   /***************************************************************************/
 232   /* Mandatory fields.                                                       */
 233   /***************************************************************************/
 234   evel_enc_kv_string(jbuf, "newState", new_state);
 235   evel_enc_kv_string(jbuf, "oldState", old_state);
 236   evel_enc_kv_string(jbuf, "stateInterface", state_change->state_interface);
 237
 238   /***************************************************************************/
 239   /* Optional fields.                                                        */
 240   /***************************************************************************/
 241   evel_json_checkpoint(jbuf);
 242   if (evel_json_open_opt_named_list(jbuf, "additionalFields"))
 243   {
 244     bool item_added = false;
 245
 246     addl_field_item = dlist_get_first(&state_change->additional_fields);
 247     while (addl_field_item != NULL)
 248     {
 249       addl_field = (STATE_CHANGE_ADDL_FIELD *) addl_field_item->item;
 250       assert(addl_field != NULL);
 251
 252       if (!evel_throttle_suppress_nv_pair(jbuf->throttle_spec,
 253                                           "additionalFields",
 254                                           addl_field->name))
 255       {
 256         evel_json_open_object(jbuf);
 257         evel_enc_kv_string(jbuf, "name", addl_field->name);
 258         evel_enc_kv_string(jbuf, "value", addl_field->value);
 259         evel_json_close_object(jbuf);
 260         item_added = true;
 261       }
 262       addl_field_item = dlist_get_next(addl_field_item);
 263     }
 264     evel_json_close_list(jbuf);
 265
 266     /*************************************************************************/
 267     /* If we've not written anything, rewind to before we opened the list.   */
 268     /*************************************************************************/
 269     if (!item_added)
 270     {
 271       evel_json_rewind(jbuf);
 272     }
 273   }
 274
 275   evel_enc_version(jbuf,
 276                    "stateChangeFieldsVersion",
 277                    state_change->major_version,state_change->minor_version);
 278
 279   evel_json_close_object(jbuf);
 280
 281   EVEL_EXIT();
 282 }