vnfs/VES/code/evel_library/evel_throttle.h

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