vnfs/VESreporting_vFW5.0_DANOS/evel/evel-library/code/evel_library/evel_throttle.h

   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  * EVEL throttle definitions.
  20  *
  21  * These are internal definitions related to throttling specicications, which
  22  * are required within the library but are not intended for external
  23  * consumption.
  24  *
  25  ****************************************************************************/
  26
  27 #ifndef EVEL_THROTTLE_INCLUDED
  28 #define EVEL_THROTTLE_INCLUDED
  29
  30 #include "evel_internal.h"
  31 #include "jsmn.h"
  32
  33 /*****************************************************************************/
  34 /* Maximum depth of JSON response that we can handle.                        */
  35 /*****************************************************************************/
  36 #define EVEL_JSON_STACK_DEPTH           10
  37
  38 /**************************************************************************//**
  39  * Maximum number of tokens that we allow for in a JSON response.
  40  *****************************************************************************/
  41 #define EVEL_MAX_RESPONSE_TOKENS        1024
  42
  43 /**************************************************************************//**
  44  * The nature of the next token that we are iterating through.  Within an
  45  * object, we alternate between collecting keys and values.  Within an array,
  46  * we only collect items.
  47  *****************************************************************************/
  48 typedef enum {
  49   EVEL_JSON_KEY,
  50   EVEL_JSON_VALUE,
  51   EVEL_JSON_ITEM
  52 } EVEL_JSON_STATE;
  53
  54 /**************************************************************************//**
  55  * States which we move through during JSON processing, tracking our way
  56  * through the supported JSON structure.
  57  *****************************************************************************/
  58 typedef enum
  59 {
  60   /***************************************************************************/
  61   /* Initial state.                                                          */
  62   /***************************************************************************/
  63   EVEL_JCS_START,
  64
  65   /***************************************************************************/
  66   /* {"commandList": [                                                       */
  67   /***************************************************************************/
  68   EVEL_JCS_COMMAND_LIST,
  69
  70   /***************************************************************************/
  71   /* {"commandList": [{                                                      */
  72   /***************************************************************************/
  73   EVEL_JCS_COMMAND_LIST_ENTRY,
  74
  75   /***************************************************************************/
  76   /* {"commandList": [{"command": {                                          */
  77   /***************************************************************************/
  78   EVEL_JCS_COMMAND,
  79
  80   /***************************************************************************/
  81   /* ... "eventDomainThrottleSpecification": {                               */
  82   /***************************************************************************/
  83   EVEL_JCS_SPEC,
  84
  85   /***************************************************************************/
  86   /* ... "suppressedFieldNames": [                                           */
  87   /***************************************************************************/
  88   EVEL_JCS_FIELD_NAMES,
  89
  90   /***************************************************************************/
  91   /* ... "suppressedNvPairsList": [                                          */
  92   /***************************************************************************/
  93   EVEL_JCS_PAIRS_LIST,
  94
  95   /***************************************************************************/
  96   /* ... "suppressedNvPairsList": [{                                         */
  97   /***************************************************************************/
  98   EVEL_JCS_PAIRS_LIST_ENTRY,
  99
 100   /***************************************************************************/
 101   /* ... "suppressedNvPairNames": [                                          */
 102   /***************************************************************************/
 103   EVEL_JCS_NV_PAIR_NAMES,
 104
 105   EVEL_JCS_MAX
 106 } EVEL_JSON_COMMAND_STATE;
 107
 108 /**************************************************************************//**
 109  * An entry in the JSON stack.
 110  *****************************************************************************/
 111 typedef struct evel_json_stack_entry {
 112
 113   /***************************************************************************/
 114   /* The number of elements required at this level.                          */
 115   /***************************************************************************/
 116   int num_required;
 117
 118   /***************************************************************************/
 119   /* The number of elements collected at this level.                         */
 120   /***************************************************************************/
 121   int json_count;
 122
 123   /***************************************************************************/
 124   /* The collection state at this level in the JSON stack.                   */
 125   /***************************************************************************/
 126   EVEL_JSON_STATE json_state;
 127
 128   /***************************************************************************/
 129   /* The key being collected (if json_state is EVEL_JSON_VALUE), or NULL.    */
 130   /***************************************************************************/
 131   char * json_key;
 132
 133 } EVEL_JSON_STACK_ENTRY;
 134
 135 /**************************************************************************//**
 136  * The JSON stack.
 137  *****************************************************************************/
 138 typedef struct evel_json_stack {
 139
 140   /***************************************************************************/
 141   /* The current position of the stack - starting at zero.                   */
 142   /***************************************************************************/
 143   int level;
 144
 145   /***************************************************************************/
 146   /* The stack itself.                                                       */
 147   /***************************************************************************/
 148   EVEL_JSON_STACK_ENTRY entry[EVEL_JSON_STACK_DEPTH];
 149
 150   /***************************************************************************/
 151   /* The underlying memory chunk.                                            */
 152   /***************************************************************************/
 153   const MEMORY_CHUNK * chunk;
 154
 155 } EVEL_JSON_STACK;
 156
 157 /**************************************************************************//**
 158  * Initialize event throttling to the default state.
 159  *
 160  * Called from ::evel_initialize.
 161  *****************************************************************************/
 162 void evel_throttle_initialize();
 163
 164 /**************************************************************************//**
 165  * Clean up event throttling.
 166  *
 167  * Called from ::evel_terminate.
 168  *****************************************************************************/
 169 void evel_throttle_terminate();
 170
 171 /**************************************************************************//**
 172  * Handle a JSON response from the listener, as a list of tokens from JSMN.
 173  *
 174  * @param chunk         Memory chunk containing the JSON buffer.
 175  * @param json_tokens   Array of tokens to handle.
 176  * @param num_tokens    The number of tokens to handle.
 177  * @param post          The memory chunk in which to place any resulting POST.
 178  * @return true if the command was handled, false otherwise.
 179  *****************************************************************************/
 180 bool evel_handle_command_list(const MEMORY_CHUNK * const chunk,
 181                               const jsmntok_t * const json_tokens,
 182                               const int num_tokens,
 183                               MEMORY_CHUNK * const post);
 184
 185 /**************************************************************************//**
 186  * Return the ::EVEL_THROTTLE_SPEC for a given domain.
 187  *
 188  * @param domain        The domain for which to return state.
 189  *****************************************************************************/
 190 EVEL_THROTTLE_SPEC * evel_get_throttle_spec(EVEL_EVENT_DOMAINS domain);
 191
 192 /**************************************************************************//**
 193  * Determine whether a field_name should be suppressed.
 194  *
 195  * @param throttle_spec Throttle specification for the domain being encoded.
 196  * @param field_name    The field name to encoded or suppress.
 197  * @return true if the field_name should be suppressed, false otherwise.
 198  *****************************************************************************/
 199 bool evel_throttle_suppress_field(EVEL_THROTTLE_SPEC * throttle_spec,
 200                                   const char * const field_name);
 201
 202 /**************************************************************************//**
 203  * Determine whether a name-value pair should be allowed (not suppressed).
 204  *
 205  * @param throttle_spec Throttle specification for the domain being encoded.
 206  * @param field_name    The field name holding the name-value pairs.
 207  * @param name          The name of the name-value pair to encoded or suppress.
 208  * @return true if the name-value pair should be suppressed, false otherwise.
 209  *****************************************************************************/
 210 bool evel_throttle_suppress_nv_pair(EVEL_THROTTLE_SPEC * throttle_spec,
 211                                     const char * const field_name,
 212                                     const char * const name);
 213
 214 #endif