1 /*************************************************************************//**
3 * Copyright © 2017 AT&T Intellectual Property. All rights reserved.
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
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.
16 ****************************************************************************/
17 /**************************************************************************//**
19 * EVEL throttle definitions.
21 * These are internal definitions related to throttling specicications, which
22 * are required within the library but are not intended for external
25 ****************************************************************************/
27 #ifndef EVEL_THROTTLE_INCLUDED
28 #define EVEL_THROTTLE_INCLUDED
30 #include "evel_internal.h"
33 /*****************************************************************************/
34 /* Maximum depth of JSON response that we can handle. */
35 /*****************************************************************************/
36 #define EVEL_JSON_STACK_DEPTH 10
38 /**************************************************************************//**
39 * Maximum number of tokens that we allow for in a JSON response.
40 *****************************************************************************/
41 #define EVEL_MAX_RESPONSE_TOKENS 1024
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 *****************************************************************************/
54 /**************************************************************************//**
55 * States which we move through during JSON processing, tracking our way
56 * through the supported JSON structure.
57 *****************************************************************************/
60 /***************************************************************************/
62 /***************************************************************************/
65 /***************************************************************************/
66 /* {"commandList": [ */
67 /***************************************************************************/
68 EVEL_JCS_COMMAND_LIST,
70 /***************************************************************************/
71 /* {"commandList": [{ */
72 /***************************************************************************/
73 EVEL_JCS_COMMAND_LIST_ENTRY,
75 /***************************************************************************/
76 /* {"commandList": [{"command": { */
77 /***************************************************************************/
80 /***************************************************************************/
81 /* ... "eventDomainThrottleSpecification": { */
82 /***************************************************************************/
85 /***************************************************************************/
86 /* ... "suppressedFieldNames": [ */
87 /***************************************************************************/
90 /***************************************************************************/
91 /* ... "suppressedNvPairsList": [ */
92 /***************************************************************************/
95 /***************************************************************************/
96 /* ... "suppressedNvPairsList": [{ */
97 /***************************************************************************/
98 EVEL_JCS_PAIRS_LIST_ENTRY,
100 /***************************************************************************/
101 /* ... "suppressedNvPairNames": [ */
102 /***************************************************************************/
103 EVEL_JCS_NV_PAIR_NAMES,
106 } EVEL_JSON_COMMAND_STATE;
108 /**************************************************************************//**
109 * An entry in the JSON stack.
110 *****************************************************************************/
111 typedef struct evel_json_stack_entry {
113 /***************************************************************************/
114 /* The number of elements required at this level. */
115 /***************************************************************************/
118 /***************************************************************************/
119 /* The number of elements collected at this level. */
120 /***************************************************************************/
123 /***************************************************************************/
124 /* The collection state at this level in the JSON stack. */
125 /***************************************************************************/
126 EVEL_JSON_STATE json_state;
128 /***************************************************************************/
129 /* The key being collected (if json_state is EVEL_JSON_VALUE), or NULL. */
130 /***************************************************************************/
133 } EVEL_JSON_STACK_ENTRY;
135 /**************************************************************************//**
137 *****************************************************************************/
138 typedef struct evel_json_stack {
140 /***************************************************************************/
141 /* The current position of the stack - starting at zero. */
142 /***************************************************************************/
145 /***************************************************************************/
146 /* The stack itself. */
147 /***************************************************************************/
148 EVEL_JSON_STACK_ENTRY entry[EVEL_JSON_STACK_DEPTH];
150 /***************************************************************************/
151 /* The underlying memory chunk. */
152 /***************************************************************************/
153 const MEMORY_CHUNK * chunk;
157 /**************************************************************************//**
158 * Initialize event throttling to the default state.
160 * Called from ::evel_initialize.
161 *****************************************************************************/
162 void evel_throttle_initialize();
164 /**************************************************************************//**
165 * Clean up event throttling.
167 * Called from ::evel_terminate.
168 *****************************************************************************/
169 void evel_throttle_terminate();
171 /**************************************************************************//**
172 * Handle a JSON response from the listener, as a list of tokens from JSMN.
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);
185 /**************************************************************************//**
186 * Return the ::EVEL_THROTTLE_SPEC for a given domain.
188 * @param domain The domain for which to return state.
189 *****************************************************************************/
190 EVEL_THROTTLE_SPEC * evel_get_throttle_spec(EVEL_EVENT_DOMAINS domain);
192 /**************************************************************************//**
193 * Determine whether a field_name should be suppressed.
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);
202 /**************************************************************************//**
203 * Determine whether a name-value pair should be allowed (not suppressed).
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);