vnfs/VES/code/evel_library/evel_state_change.c

   1 /**************************************************************************//**
   2  * @file
   3  * Implementation of EVEL functions relating to the State Change.
   4  *
   5  * License
   6  * -------
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright notice,
  12  *    this list of conditions and the following disclaimer.
  13  * 2. Redistributions in binary form must reproduce the above copyright notice,
  14  *    this list of conditions and the following disclaimer in the documentation
  15  *    and/or other materials provided with the distribution.
  16  * 3. All advertising materials mentioning features or use of this software
  17  *    must display the following acknowledgement:  This product includes
  18  *    software developed by the AT&T.
  19  * 4. Neither the name of AT&T nor the names of its contributors may be used to
  20  *    endorse or promote products derived from this software without specific
  21  *    prior written permission.
  22  *
  23  * THIS SOFTWARE IS PROVIDED BY AT&T INTELLECTUAL PROPERTY ''AS IS'' AND ANY
  24  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  26  * DISCLAIMED. IN NO EVENT SHALL AT&T INTELLECTUAL PROPERTY BE LIABLE FOR ANY
  27  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  30  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  32  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  *****************************************************************************/
  34
  35 #include <string.h>
  36 #include <assert.h>
  37 #include <stdlib.h>
  38
  39 #include "evel_throttle.h"
  40
  41 /**************************************************************************//**
  42  * Create a new State Change event.
  43  *
  44  * @note    The mandatory fields on the State Change must be supplied to this
  45  *          factory function and are immutable once set.  Optional fields have
  46  *          explicit setter functions, but again values may only be set once
  47  *          so that the State Change has immutable properties.
  48  *
  49  * @param new_state     The new state of the reporting entity.
  50  * @param old_state     The old state of the reporting entity.
  51  * @param interface     The card or port name of the reporting entity.
  52  *
  53  * @returns pointer to the newly manufactured ::EVENT_STATE_CHANGE.  If the
  54  *          event is not used it must be released using
  55  *          ::evel_free_state_change
  56  * @retval  NULL  Failed to create the event.
  57  *****************************************************************************/
  58 EVENT_STATE_CHANGE * evel_new_state_change(const EVEL_ENTITY_STATE new_state,
  59                                            const EVEL_ENTITY_STATE old_state,
  60                                            const char * const interface)
  61 {
  62   EVENT_STATE_CHANGE * state_change = NULL;
  63   EVEL_ENTER();
  64
  65   /***************************************************************************/
  66   /* Check preconditions.                                                    */
  67   /***************************************************************************/
  68   assert(new_state < EVEL_MAX_ENTITY_STATES);
  69   assert(old_state < EVEL_MAX_ENTITY_STATES);
  70   assert(interface != NULL);
  71
  72   /***************************************************************************/
  73   /* Allocate the State Change.                                              */
  74   /***************************************************************************/
  75   state_change = malloc(sizeof(EVENT_STATE_CHANGE));
  76   if (state_change == NULL)
  77   {
  78     log_error_state("Out of memory");
  79     goto exit_label;
  80   }
  81   memset(state_change, 0, sizeof(EVENT_STATE_CHANGE));
  82   EVEL_DEBUG("New State Change is at %lp", state_change);
  83
  84   /***************************************************************************/
  85   /* Initialize the header & the State Change fields.  Optional string       */
  86   /* values are uninitialized (NULL).                                        */
  87   /***************************************************************************/
  88   evel_init_header(&state_change->header);
  89   state_change->header.event_domain = EVEL_DOMAIN_STATE_CHANGE;
  90   state_change->major_version = EVEL_STATE_CHANGE_MAJOR_VERSION;
  91   state_change->minor_version = EVEL_STATE_CHANGE_MINOR_VERSION;
  92   state_change->new_state = new_state;
  93   state_change->old_state = old_state;
  94   state_change->state_interface = strdup(interface);
  95   dlist_initialize(&state_change->additional_fields);
  96
  97 exit_label:
  98   EVEL_EXIT();
  99   return state_change;
 100 }
 101
 102 /**************************************************************************//**
 103  * Free a State Change.
 104  *
 105  * Free off the State Change supplied.  Will free all the contained allocated
 106  * memory.
 107  *
 108  * @note It does not free the State Change itself, since that may be part of a
 109  * larger structure.
 110  *****************************************************************************/
 111 void evel_free_state_change(EVENT_STATE_CHANGE * const state_change)
 112 {
 113   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 114
 115   EVEL_ENTER();
 116
 117   /***************************************************************************/
 118   /* Check preconditions.  As an internal API we don't allow freeing NULL    */
 119   /* events as we do on the public API.                                      */
 120   /***************************************************************************/
 121   assert(state_change != NULL);
 122   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 123
 124   /***************************************************************************/
 125   /* Free all internal strings then the header itself.                       */
 126   /***************************************************************************/
 127   addl_field = dlist_pop_last(&state_change->additional_fields);
 128   while (addl_field != NULL)
 129   {
 130     EVEL_DEBUG("Freeing Additional Field (%s, %s)",
 131                addl_field->name,
 132                addl_field->value);
 133     free(addl_field->name);
 134     free(addl_field->value);
 135     free(addl_field);
 136     addl_field = dlist_pop_last(&state_change->additional_fields);
 137   }
 138   free(state_change->state_interface);
 139   evel_free_header(&state_change->header);
 140
 141   EVEL_EXIT();
 142 }
 143
 144 /**************************************************************************//**
 145  * Set the Event Type property of the State Change.
 146  *
 147  * @note  The property is treated as immutable: it is only valid to call
 148  *        the setter once.  However, we don't assert if the caller tries to
 149  *        overwrite, just ignoring the update instead.
 150  *
 151  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
 152  * @param type          The Event Type to be set. ASCIIZ string. The caller
 153  *                      does not need to preserve the value once the function
 154  *                      returns.
 155  *****************************************************************************/
 156 void evel_state_change_type_set(EVENT_STATE_CHANGE * const state_change,
 157                                 const char * const type)
 158 {
 159   EVEL_ENTER();
 160
 161   /***************************************************************************/
 162   /* Check preconditions and call evel_header_type_set.                      */
 163   /***************************************************************************/
 164   assert(state_change != NULL);
 165   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 166   evel_header_type_set(&state_change->header, type);
 167
 168   EVEL_EXIT();
 169 }
 170
 171 /**************************************************************************//**
 172  * Add an additional field name/value pair to the State Change.
 173  *
 174  * The name and value are null delimited ASCII strings.  The library takes
 175  * a copy so the caller does not have to preserve values after the function
 176  * returns.
 177  *
 178  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE.
 179  * @param name          ASCIIZ string with the attribute's name.  The caller
 180  *                      does not need to preserve the value once the function
 181  *                      returns.
 182  * @param value         ASCIIZ string with the attribute's value.  The caller
 183  *                      does not need to preserve the value once the function
 184  *                      returns.
 185  *****************************************************************************/
 186 void evel_state_change_addl_field_add(EVENT_STATE_CHANGE * const state_change,
 187                                       const char * const name,
 188                                       const char * const value)
 189 {
 190   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 191   EVEL_ENTER();
 192
 193   /***************************************************************************/
 194   /* Check preconditions.                                                    */
 195   /***************************************************************************/
 196   assert(state_change != NULL);
 197   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 198   assert(name != NULL);
 199   assert(value != NULL);
 200
 201   EVEL_DEBUG("Adding name=%s value=%s", name, value);
 202   addl_field = malloc(sizeof(STATE_CHANGE_ADDL_FIELD));
 203   assert(addl_field != NULL);
 204   memset(addl_field, 0, sizeof(STATE_CHANGE_ADDL_FIELD));
 205   addl_field->name = strdup(name);
 206   addl_field->value = strdup(value);
 207   assert(addl_field->name != NULL);
 208   assert(addl_field->value != NULL);
 209
 210   dlist_push_last(&state_change->additional_fields, addl_field);
 211
 212   EVEL_EXIT();
 213 }
 214
 215 /**************************************************************************//**
 216  * Encode the state change as a JSON state change.
 217  *
 218  * @param jbuf          Pointer to the ::EVEL_JSON_BUFFER to encode into.
 219  * @param state_change  Pointer to the ::EVENT_STATE_CHANGE to encode.
 220  *****************************************************************************/
 221 void evel_json_encode_state_change(EVEL_JSON_BUFFER * jbuf,
 222                                    EVENT_STATE_CHANGE * state_change)
 223 {
 224   STATE_CHANGE_ADDL_FIELD * addl_field = NULL;
 225   DLIST_ITEM * addl_field_item = NULL;
 226   char * new_state;
 227   char * old_state;
 228
 229   EVEL_ENTER();
 230
 231   /***************************************************************************/
 232   /* Check preconditions.                                                    */
 233   /***************************************************************************/
 234   assert(state_change != NULL);
 235   assert(state_change->header.event_domain == EVEL_DOMAIN_STATE_CHANGE);
 236
 237   new_state = evel_entity_state(state_change->new_state);
 238   old_state = evel_entity_state(state_change->old_state);
 239
 240   evel_json_encode_header(jbuf, &state_change->header);
 241   evel_json_open_named_object(jbuf, "stateChangeFields");
 242
 243   /***************************************************************************/
 244   /* Mandatory fields.                                                       */
 245   /***************************************************************************/
 246   evel_enc_kv_string(jbuf, "newState", new_state);
 247   evel_enc_kv_string(jbuf, "oldState", old_state);
 248   evel_enc_kv_string(jbuf, "stateInterface", state_change->state_interface);
 249
 250   /***************************************************************************/
 251   /* Optional fields.                                                        */
 252   /***************************************************************************/
 253   evel_json_checkpoint(jbuf);
 254   if (evel_json_open_opt_named_list(jbuf, "additionalFields"))
 255   {
 256     bool item_added = false;
 257
 258     addl_field_item = dlist_get_first(&state_change->additional_fields);
 259     while (addl_field_item != NULL)
 260     {
 261       addl_field = (STATE_CHANGE_ADDL_FIELD *) addl_field_item->item;
 262       assert(addl_field != NULL);
 263
 264       if (!evel_throttle_suppress_nv_pair(jbuf->throttle_spec,
 265                                           "additionalFields",
 266                                           addl_field->name))
 267       {
 268         evel_json_open_object(jbuf);
 269         evel_enc_kv_string(jbuf, "name", addl_field->name);
 270         evel_enc_kv_string(jbuf, "value", addl_field->value);
 271         evel_json_close_object(jbuf);
 272         item_added = true;
 273       }
 274       addl_field_item = dlist_get_next(addl_field_item);
 275     }
 276     evel_json_close_list(jbuf);
 277
 278     /*************************************************************************/
 279     /* If we've not written anything, rewind to before we opened the list.   */
 280     /*************************************************************************/
 281     if (!item_added)
 282     {
 283       evel_json_rewind(jbuf);
 284     }
 285   }
 286
 287   evel_enc_version(jbuf,
 288                    "stateChangeFieldsVersion",
 289                    state_change->major_version,
 290                    state_change->minor_version);
 291
 292   evel_json_close_object(jbuf);
 293
 294   EVEL_EXIT();
 295 }