]>
Commit | Line | Data |
---|---|---|
ea830b96 AC |
1 | /** @file\r |
2 | APIs for JSON operations.\r | |
3 | \r | |
4 | Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>\r | |
5 | (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>\r | |
6 | \r | |
7 | SPDX-License-Identifier: BSD-2-Clause-Patent\r | |
8 | \r | |
9 | **/\r | |
10 | #ifndef JSON_LIB_H_\r | |
11 | #define JSON_LIB_H_\r | |
12 | \r | |
13 | typedef VOID* EDKII_JSON_VALUE;\r | |
14 | typedef VOID* EDKII_JSON_ARRAY;\r | |
15 | typedef VOID* EDKII_JSON_OBJECT;\r | |
16 | \r | |
17 | ///\r | |
18 | /// Map to json_int_t in jansson.h\r | |
19 | ///\r | |
20 | typedef INT64 EDKII_JSON_INT_T; // #JSON_INTEGER_IS_LONG_LONG is set to 1\r | |
21 | // in jansson_Config.h\r | |
22 | \r | |
23 | ///\r | |
24 | /// Map to the definitions in jansson.h\r | |
25 | /// See below URI for the JSON encoding flags reference.\r | |
26 | /// https://jansson.readthedocs.io/en/2.13/apiref.html#encoding\r | |
27 | ///\r | |
28 | #define EDKII_JSON_MAX_INDENT 0x1F\r | |
29 | #define EDKII_JSON_INDENT(n) ((n) & EDKII_JSON_MAX_INDENT)\r | |
30 | \r | |
31 | #define EDKII_JSON_COMPACT 0x20\r | |
32 | #define EDKII_JSON_ENSURE_ASCII 0x40\r | |
33 | #define EDKII_JSON_SORT_KEYS 0x80\r | |
34 | #define EDKII_JSON_PRESERVE_ORDER 0x100\r | |
35 | #define EDKII_JSON_ENCODE_ANY 0x200\r | |
36 | #define EDKII_JSON_ESCAPE_SLASH 0x400\r | |
37 | #define EDKII_JSON_REAL_PRECISION(n) (((n) & 0x1F) << 11)\r | |
38 | #define EDKII_JSON_EMBED 0x10000\r | |
39 | \r | |
40 | ///\r | |
41 | /// Map to the definitions in jansson.h\r | |
42 | /// See below URI for the JSON decoding flags reference.\r | |
43 | /// https://jansson.readthedocs.io/en/2.13/apiref.html?highlight=json_loadb#decoding\r | |
44 | ///\r | |
45 | #define EDKII_JSON_REJECT_DUPLICATES 0x1\r | |
46 | #define EDKII_JSON_DISABLE_EOF_CHECK 0x2\r | |
47 | #define EDKII_JSON_DECODE_ANY 0x4\r | |
48 | #define EDKII_JSON_DECODE_INT_AS_REAL 0x8\r | |
49 | #define EDKII_JSON_ALLOW_NUL 0x10\r | |
50 | \r | |
51 | #define EDKII_JSON_ARRAY_FOREACH(Array, Index, Value) \\r | |
52 | for(Index = 0; \\r | |
53 | Index < JsonArrayCount(Array) && (Value = JsonArrayGetValue(Array, Index)); \\r | |
54 | Index++)\r | |
55 | \r | |
56 | ///\r | |
57 | /// Map to the json_error_t in jansson.h\r | |
58 | ///\r | |
59 | #define EDKII_JSON_ERROR_TEXT_LENGTH 160\r | |
60 | #define EDKII_JSON_ERROR_SOURCE_LENGTH 80\r | |
61 | typedef struct {\r | |
62 | INTN Line;\r | |
63 | INTN Column;\r | |
64 | INTN Position;\r | |
65 | CHAR8 Source [EDKII_JSON_ERROR_SOURCE_LENGTH];\r | |
66 | CHAR8 Text [EDKII_JSON_ERROR_TEXT_LENGTH];\r | |
67 | } EDKII_JSON_ERROR;\r | |
68 | \r | |
69 | ///\r | |
70 | /// Map to the json_type in jansson.h\r | |
71 | ///\r | |
72 | typedef enum {\r | |
73 | EdkiiJsonTypeObject,\r | |
74 | EdkiiJsonTypeArray,\r | |
75 | EdkiiJsonTypeString,\r | |
76 | EdkiiJsonTypeInteger,\r | |
77 | EdkiiJsonTypeReal,\r | |
78 | EdkiiJsonTypeTrue,\r | |
79 | EdkiiJsonTypeFalse,\r | |
80 | EdkiiJsonTypeNull\r | |
81 | } EDKII_JSON_TYPE;\r | |
82 | \r | |
83 | /**\r | |
84 | The function is used to initialize a JSON value which contains a new JSON array,\r | |
85 | or NULL on error. Initially, the array is empty.\r | |
86 | \r | |
87 | The reference count of this value will be set to 1, and caller needs to cleanup the\r | |
88 | value by calling JsonValueFree().\r | |
89 | \r | |
90 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
91 | \r | |
92 | @retval The created JSON value which contains a JSON array or NULL if intial a JSON array\r | |
93 | is failed.\r | |
94 | \r | |
95 | **/\r | |
96 | EDKII_JSON_VALUE\r | |
97 | EFIAPI\r | |
98 | JsonValueInitArray (\r | |
99 | VOID\r | |
100 | );\r | |
101 | \r | |
102 | /**\r | |
103 | The function is used to initialize a JSON value which contains a new JSON object,\r | |
104 | or NULL on error. Initially, the object is empty.\r | |
105 | \r | |
106 | The reference count of this value will be set to 1, and caller needs to cleanup the\r | |
107 | value by calling JsonValueFree().\r | |
108 | \r | |
109 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
110 | \r | |
111 | @retval The created JSON value which contains a JSON object or NULL if intial a JSON object\r | |
112 | is failed.\r | |
113 | \r | |
114 | **/\r | |
115 | EDKII_JSON_VALUE\r | |
116 | EFIAPI\r | |
117 | JsonValueInitObject (\r | |
118 | VOID\r | |
119 | );\r | |
120 | \r | |
121 | /**\r | |
122 | The function is used to initialize a JSON value which contains a new JSON string,\r | |
123 | or NULL on error.\r | |
124 | \r | |
125 | The input string must be NULL terminated Ascii format, non-Ascii characters will\r | |
126 | be processed as an error. Unicode characters can also be represented by Ascii string\r | |
127 | as the format: \u + 4 hexadecimal digits, like \u3E5A, or \u003F.\r | |
128 | \r | |
129 | The reference count of this value will be set to 1, and caller needs to cleanup the\r | |
130 | value by calling JsonValueFree().\r | |
131 | \r | |
132 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
133 | \r | |
134 | @param[in] String The Ascii string to initialize to JSON value\r | |
135 | \r | |
136 | @retval The created JSON value which contains a JSON string or NULL. Select a\r | |
137 | Getter API for a specific encoding format.\r | |
138 | \r | |
139 | **/\r | |
140 | EDKII_JSON_VALUE\r | |
141 | EFIAPI\r | |
142 | JsonValueInitAsciiString (\r | |
143 | IN CONST CHAR8 *String\r | |
144 | );\r | |
145 | \r | |
146 | /**\r | |
147 | The function is used to initialize a JSON value which contains a new JSON string,\r | |
148 | or NULL on error.\r | |
149 | \r | |
150 | The input must be a NULL terminated UCS2 format Unicode string.\r | |
151 | \r | |
152 | The reference count of this value will be set to 1, and caller needs to cleanup the\r | |
153 | value by calling JsonValueFree().\r | |
154 | \r | |
155 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
156 | \r | |
157 | @param[in] String The Unicode string to initialize to JSON value\r | |
158 | \r | |
159 | @retval The created JSON value which contains a JSON string or NULL. Select a\r | |
160 | Getter API for a specific encoding format.\r | |
161 | \r | |
162 | **/\r | |
163 | EDKII_JSON_VALUE\r | |
164 | EFIAPI\r | |
165 | JsonValueInitUnicodeString (\r | |
166 | IN CHAR16 *String\r | |
167 | );\r | |
168 | \r | |
169 | /**\r | |
170 | The function is used to initialize a JSON value which contains a new JSON integer,\r | |
171 | or NULL on error.\r | |
172 | \r | |
173 | The reference count of this value will be set to 1, and caller needs to cleanup the\r | |
174 | value by calling JsonValueFree().\r | |
175 | \r | |
176 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
177 | \r | |
178 | @param[in] Value The integer to initialize to JSON value\r | |
179 | \r | |
180 | @retval The created JSON value which contains a JSON number or NULL.\r | |
181 | \r | |
182 | **/\r | |
183 | EDKII_JSON_VALUE\r | |
184 | EFIAPI\r | |
185 | JsonValueInitNumber (\r | |
186 | IN INT64 Value\r | |
187 | );\r | |
188 | \r | |
189 | /**\r | |
190 | The function is used to initialize a JSON value which contains a new JSON boolean,\r | |
191 | or NULL on error.\r | |
192 | \r | |
193 | Boolean JSON value is kept as static value, and no need to do any cleanup work.\r | |
194 | \r | |
195 | @param[in] Value The boolean value to initialize.\r | |
196 | \r | |
197 | @retval The created JSON value which contains a JSON boolean or NULL.\r | |
198 | \r | |
199 | **/\r | |
200 | EDKII_JSON_VALUE\r | |
201 | EFIAPI\r | |
202 | JsonValueInitBoolean (\r | |
203 | IN BOOLEAN Value\r | |
204 | );\r | |
205 | \r | |
206 | /**\r | |
207 | The function is used to initialize a JSON value which contains a new JSON NULL,\r | |
208 | or NULL on error.\r | |
209 | \r | |
210 | NULL JSON value is kept as static value, and no need to do any cleanup work.\r | |
211 | \r | |
212 | @retval The created NULL JSON value.\r | |
213 | \r | |
214 | **/\r | |
215 | EDKII_JSON_VALUE\r | |
216 | EFIAPI\r | |
217 | JsonValueInitNull (\r | |
218 | VOID\r | |
219 | );\r | |
220 | \r | |
221 | /**\r | |
222 | The function is used to decrease the reference count of a JSON value by one, and once\r | |
223 | this reference count drops to zero, the value is destroyed and it can no longer be used.\r | |
224 | If this destroyed value is object type or array type, reference counts for all containing\r | |
225 | JSON values will be decreased by 1. Boolean JSON value and NULL JSON value won't be destroyed\r | |
226 | since they are static values kept in memory.\r | |
227 | \r | |
228 | Reference Count Strategy: BaseJsonLib uses this strategy to track whether a value is still\r | |
229 | in use or not. When a value is created, it's reference count is set to 1. If a reference to a\r | |
230 | value is kept for use, its reference count is incremented, and when the value is no longer\r | |
231 | needed, the reference count is decremented. When the reference count drops to zero, there are\r | |
232 | no references left, and the value can be destroyed.\r | |
233 | \r | |
234 | The given JSON value maybe NULL and not causing any problem. Just output the debug message\r | |
235 | to inform caller the NULL value is passed in.\r | |
236 | \r | |
237 | @param[in] Json The JSON value to be freed. json_decref may return without any\r | |
238 | changes if Json is NULL.\r | |
239 | \r | |
240 | **/\r | |
241 | VOID\r | |
242 | EFIAPI\r | |
243 | JsonValueFree (\r | |
244 | IN EDKII_JSON_VALUE Json\r | |
245 | );\r | |
246 | \r | |
247 | /**\r | |
248 | The function is used to create a fresh copy of a JSON value, and all child values are deep\r | |
249 | copied in a recursive fashion. It should be called when this JSON value might be modified\r | |
250 | in later use, but the original still wants to be used in somewhere else.\r | |
251 | \r | |
252 | Reference counts of the returned root JSON value and all child values will be set to 1, and\r | |
253 | caller needs to cleanup the root value by calling JsonValueFree().\r | |
254 | \r | |
255 | * Note: Since this function performs a copy from bottom to up, too many calls may cause some\r | |
256 | performance issues, user should avoid unnecessary calls to this function unless it is really\r | |
257 | needed.\r | |
258 | \r | |
259 | @param[in] Json The JSON value to be cloned.\r | |
260 | \r | |
261 | @retval Return the cloned JSON value, or NULL on error.\r | |
262 | \r | |
263 | **/\r | |
264 | EDKII_JSON_VALUE\r | |
265 | EFIAPI\r | |
266 | JsonValueClone (\r | |
267 | IN EDKII_JSON_VALUE Json\r | |
268 | );\r | |
269 | \r | |
270 | /**\r | |
271 | The function is used to return if the provided JSON value contains a JSON array.\r | |
272 | \r | |
273 | @param[in] Json The provided JSON value.\r | |
274 | \r | |
275 | @retval TRUE The JSON value contains a JSON array.\r | |
276 | @retval FALSE The JSON value doesn't contain a JSON array.\r | |
277 | \r | |
278 | **/\r | |
279 | BOOLEAN\r | |
280 | EFIAPI\r | |
281 | JsonValueIsArray (\r | |
282 | IN EDKII_JSON_VALUE Json\r | |
283 | );\r | |
284 | \r | |
285 | /**\r | |
286 | The function is used to return if the provided JSON value contains a JSON object.\r | |
287 | \r | |
288 | @param[in] Json The provided JSON value.\r | |
289 | \r | |
290 | @retval TRUE The JSON value contains a JSON object.\r | |
291 | @retval FALSE The JSON value doesn't contain a JSON object.\r | |
292 | \r | |
293 | **/\r | |
294 | BOOLEAN\r | |
295 | EFIAPI\r | |
296 | JsonValueIsObject (\r | |
297 | IN EDKII_JSON_VALUE Json\r | |
298 | );\r | |
299 | \r | |
300 | /**\r | |
301 | The function is used to return if the provided JSON Value contains a string, Ascii or\r | |
302 | Unicode format is not differentiated.\r | |
303 | \r | |
304 | @param[in] Json The provided JSON value.\r | |
305 | \r | |
306 | @retval TRUE The JSON value contains a JSON string.\r | |
307 | @retval FALSE The JSON value doesn't contain a JSON string.\r | |
308 | \r | |
309 | **/\r | |
310 | BOOLEAN\r | |
311 | EFIAPI\r | |
312 | JsonValueIsString (\r | |
313 | IN EDKII_JSON_VALUE Json\r | |
314 | );\r | |
315 | \r | |
316 | /**\r | |
317 | The function is used to return if the provided JSON value contains a JSON number.\r | |
318 | \r | |
319 | @param[in] Json The provided JSON value.\r | |
320 | \r | |
321 | @retval TRUE The JSON value is contains JSON number.\r | |
322 | @retval FALSE The JSON value doesn't contain a JSON number.\r | |
323 | \r | |
324 | **/\r | |
325 | BOOLEAN\r | |
326 | EFIAPI\r | |
327 | JsonValueIsNumber (\r | |
328 | IN EDKII_JSON_VALUE Json\r | |
329 | );\r | |
330 | \r | |
331 | /**\r | |
332 | The function is used to return if the provided JSON value contains a JSON boolean.\r | |
333 | \r | |
334 | @param[in] Json The provided JSON value.\r | |
335 | \r | |
336 | @retval TRUE The JSON value contains a JSON boolean.\r | |
337 | @retval FALSE The JSON value doesn't contain a JSON boolean.\r | |
338 | \r | |
339 | **/\r | |
340 | BOOLEAN\r | |
341 | EFIAPI\r | |
342 | JsonValueIsBoolean (\r | |
343 | IN EDKII_JSON_VALUE Json\r | |
344 | );\r | |
345 | \r | |
346 | /**\r | |
347 | The function is used to return if the provided JSON value contains a JSON NULL.\r | |
348 | \r | |
349 | @param[in] Json The provided JSON value.\r | |
350 | \r | |
351 | @retval TRUE The JSON value contains a JSON NULL.\r | |
352 | @retval FALSE The JSON value doesn't contain a JSON NULL.\r | |
353 | \r | |
354 | **/\r | |
355 | BOOLEAN\r | |
356 | EFIAPI\r | |
357 | JsonValueIsNull (\r | |
358 | IN EDKII_JSON_VALUE Json\r | |
359 | );\r | |
360 | \r | |
361 | /**\r | |
362 | The function is used to retrieve the associated array in an array type JSON value.\r | |
363 | \r | |
364 | Any changes to the returned array will impact the original JSON value.\r | |
365 | \r | |
366 | @param[in] Json The provided JSON value.\r | |
367 | \r | |
368 | @retval Return the associated array in JSON value or NULL.\r | |
369 | \r | |
370 | **/\r | |
371 | EDKII_JSON_ARRAY\r | |
372 | EFIAPI\r | |
373 | JsonValueGetArray (\r | |
374 | IN EDKII_JSON_VALUE Json\r | |
375 | );\r | |
376 | \r | |
377 | /**\r | |
378 | The function is used to retrieve the associated object in an object type JSON value.\r | |
379 | \r | |
380 | Any changes to the returned object will impact the original JSON value.\r | |
381 | \r | |
382 | @param[in] Json The provided JSON value.\r | |
383 | \r | |
384 | @retval Return the associated object in JSON value or NULL.\r | |
385 | \r | |
386 | **/\r | |
387 | EDKII_JSON_OBJECT\r | |
388 | EFIAPI\r | |
389 | JsonValueGetObject (\r | |
390 | IN EDKII_JSON_VALUE Json\r | |
391 | );\r | |
392 | \r | |
393 | /**\r | |
394 | The function is used to retrieve the associated Ascii string in a string type JSON value.\r | |
395 | \r | |
396 | Any changes to the returned string will impact the original JSON value.\r | |
397 | \r | |
398 | @param[in] Json The provided JSON value.\r | |
399 | \r | |
400 | @retval Return the associated Ascii string in JSON value or NULL.\r | |
401 | \r | |
402 | **/\r | |
403 | CONST CHAR8 *\r | |
404 | EFIAPI\r | |
405 | JsonValueGetAsciiString (\r | |
406 | IN EDKII_JSON_VALUE Json\r | |
407 | );\r | |
408 | \r | |
409 | /**\r | |
410 | The function is used to retrieve the associated Unicode string in a string type JSON value.\r | |
411 | \r | |
412 | Caller can do any changes to the returned string without any impact to the original JSON\r | |
413 | value, and caller needs to free the returned string using FreePool().\r | |
414 | \r | |
415 | @param[in] Json The provided JSON value.\r | |
416 | \r | |
417 | @retval Return the associated Unicode string in JSON value or NULL.\r | |
418 | \r | |
419 | **/\r | |
420 | CHAR16*\r | |
421 | EFIAPI\r | |
422 | JsonValueGetUnicodeString (\r | |
423 | IN EDKII_JSON_VALUE Json\r | |
424 | );\r | |
425 | \r | |
426 | /**\r | |
427 | The function is used to retrieve the associated integer in a number type JSON value.\r | |
428 | \r | |
429 | The input JSON value should not be NULL or contain no JSON number, otherwise it will\r | |
430 | ASSERT() and return 0.\r | |
431 | \r | |
432 | @param[in] Json The provided JSON value.\r | |
433 | \r | |
434 | @retval Return the associated number in JSON value.\r | |
435 | \r | |
436 | **/\r | |
437 | INT64\r | |
438 | EFIAPI\r | |
439 | JsonValueGetNumber (\r | |
440 | IN EDKII_JSON_VALUE Json\r | |
441 | );\r | |
442 | \r | |
443 | /**\r | |
444 | The function is used to retrieve the associated boolean in a boolean type JSON value.\r | |
445 | \r | |
446 | The input JSON value should not be NULL or contain no JSON boolean, otherwise it will\r | |
447 | ASSERT() and return FALSE.\r | |
448 | \r | |
449 | @param[in] Json The provided JSON value.\r | |
450 | \r | |
451 | @retval Return the associated value of JSON boolean.\r | |
452 | \r | |
453 | **/\r | |
454 | BOOLEAN\r | |
455 | EFIAPI\r | |
456 | JsonValueGetBoolean (\r | |
457 | IN EDKII_JSON_VALUE Json\r | |
458 | );\r | |
459 | \r | |
460 | /**\r | |
461 | The function is used to retrieve the associated string in a string type JSON value.\r | |
462 | \r | |
463 | Any changes to the returned string will impact the original JSON value.\r | |
464 | \r | |
465 | @param[in] Json The provided JSON value.\r | |
466 | \r | |
467 | @retval Return the associated Ascii string in JSON value or NULL on errors.\r | |
468 | \r | |
469 | **/\r | |
470 | CONST CHAR8*\r | |
471 | EFIAPI\r | |
472 | JsonValueGetString (\r | |
473 | IN EDKII_JSON_VALUE Json\r | |
474 | );\r | |
475 | \r | |
476 | /**\r | |
477 | The function is used to get the number of elements in a JSON object, or 0 if it is NULL or\r | |
478 | not a JSON object.\r | |
479 | \r | |
480 | @param[in] JsonObject The provided JSON object.\r | |
481 | \r | |
482 | @retval Return the number of elements in this JSON object or 0.\r | |
483 | \r | |
484 | **/\r | |
485 | UINTN\r | |
486 | EFIAPI\r | |
487 | JsonObjectSize (\r | |
488 | IN EDKII_JSON_OBJECT JsonObject\r | |
489 | );\r | |
490 | \r | |
491 | /**\r | |
492 | The function is used to enumerate all keys in a JSON object.\r | |
493 | \r | |
494 | Caller should be responsible to free the returned key array reference using\r | |
495 | FreePool(). But contained keys are read only and must not be modified or freed.\r | |
496 | \r | |
497 | @param[in] JsonObj The provided JSON object for enumeration.\r | |
498 | @param[out] KeyCount The count of keys in this JSON object.\r | |
499 | \r | |
500 | @retval Return an array of the enumerated keys in this JSON object or NULL if\r | |
501 | JsonObj is not an JSON object, key count is zero or on other errors.\r | |
502 | \r | |
503 | **/\r | |
504 | CHAR8**\r | |
505 | JsonObjectGetKeys (\r | |
506 | IN EDKII_JSON_OBJECT JsonObj,\r | |
507 | OUT UINTN *KeyCount\r | |
508 | );\r | |
509 | \r | |
510 | /**\r | |
511 | The function is used to get a JSON value corresponding to the input key from a JSON object.\r | |
512 | \r | |
513 | It only returns a reference to this value and any changes on this value will impact the\r | |
514 | original JSON object. If that is not expected, please call JsonValueClone() to clone it to\r | |
515 | use.\r | |
516 | \r | |
517 | Input key must be a valid NULL terminated UTF8 encoded string. NULL will be returned when\r | |
518 | Key-Value is not found in this JSON object.\r | |
519 | \r | |
520 | @param[in] JsonObj The provided JSON object.\r | |
521 | @param[in] Key The key of the JSON value to be retrieved.\r | |
522 | \r | |
523 | @retval Return the corresponding JSON value to key, or NULL on error.\r | |
524 | \r | |
525 | **/\r | |
526 | EDKII_JSON_VALUE\r | |
527 | EFIAPI\r | |
528 | JsonObjectGetValue (\r | |
529 | IN CONST EDKII_JSON_OBJECT JsonObj,\r | |
530 | IN CONST CHAR8 *Key\r | |
531 | );\r | |
532 | \r | |
533 | /**\r | |
534 | The function is used to set a JSON value corresponding to the input key from a JSON object,\r | |
535 | and the reference count of this value will be increased by 1.\r | |
536 | \r | |
537 | Input key must be a valid NULL terminated UTF8 encoded string. If there already is a value for\r | |
538 | this key, this key will be assigned to the new JSON value. The old JSON value will be removed\r | |
539 | from this object and thus its' reference count will be decreased by 1.\r | |
540 | \r | |
541 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
542 | \r | |
543 | @param[in] JsonObj The provided JSON object.\r | |
544 | @param[in] Key The key of the JSON value to be set.\r | |
545 | @param[in] Json The JSON value to set to this JSON object mapped by key.\r | |
546 | \r | |
547 | @retval EFI_ABORTED Some error occur and operation aborted.\r | |
548 | @retval EFI_SUCCESS The JSON value has been set to this JSON object.\r | |
549 | \r | |
550 | **/\r | |
551 | EFI_STATUS\r | |
552 | EFIAPI\r | |
553 | JsonObjectSetValue (\r | |
554 | IN EDKII_JSON_OBJECT JsonObj,\r | |
555 | IN CONST CHAR8 *Key,\r | |
556 | IN EDKII_JSON_VALUE Json\r | |
557 | );\r | |
558 | \r | |
559 | /**\r | |
560 | The function is used to get the number of elements in a JSON array. Returns or 0 if JsonArray\r | |
561 | is NULL or not a JSON array.\r | |
562 | \r | |
563 | @param[in] JsonArray The provided JSON array.\r | |
564 | \r | |
565 | @retval Return the number of elements in this JSON array or 0.\r | |
566 | \r | |
567 | **/\r | |
568 | UINTN\r | |
569 | EFIAPI\r | |
570 | JsonArrayCount (\r | |
571 | IN EDKII_JSON_ARRAY JsonArray\r | |
572 | );\r | |
573 | \r | |
574 | /**\r | |
575 | The function is used to return the JSON value in the array at position index. The valid range\r | |
576 | for this index is from 0 to the return value of JsonArrayCount() minus 1.\r | |
577 | \r | |
578 | It only returns a reference to this value and any changes on this value will impact the\r | |
579 | original JSON object. If that is not expected, please call JsonValueClone() to clone it to\r | |
580 | use.\r | |
581 | \r | |
582 | If this array is NULL or not a JSON array, or if index is out of range, NULL will be returned.\r | |
583 | \r | |
584 | @param[in] JsonArray The provided JSON Array.\r | |
585 | \r | |
586 | @retval Return the JSON value located in the Index position or\r | |
587 | NULL if JsonArray is not an array or no items in the array.\r | |
588 | \r | |
589 | **/\r | |
590 | EDKII_JSON_VALUE\r | |
591 | EFIAPI\r | |
592 | JsonArrayGetValue (\r | |
593 | IN EDKII_JSON_ARRAY JsonArray,\r | |
594 | IN UINTN Index\r | |
595 | );\r | |
596 | \r | |
597 | /**\r | |
598 | The function is used to append a JSON value to the end of the JSON array, and grow the size of\r | |
599 | array by 1. The reference count of this value will be increased by 1.\r | |
600 | \r | |
601 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
602 | \r | |
603 | @param[in] JsonArray The provided JSON object.\r | |
604 | @param[in] Json The JSON value to append.\r | |
605 | \r | |
606 | @retval EFI_ABORTED Some error occur and operation aborted.\r | |
607 | @retval EFI_SUCCESS JSON value has been appended to the end of the JSON array.\r | |
608 | \r | |
609 | **/\r | |
610 | EFI_STATUS\r | |
611 | EFIAPI\r | |
612 | JsonArrayAppendValue (\r | |
613 | IN EDKII_JSON_ARRAY JsonArray,\r | |
614 | IN EDKII_JSON_VALUE Json\r | |
615 | );\r | |
616 | \r | |
617 | /**\r | |
618 | The function is used to remove a JSON value at position index, shifting the elements after index\r | |
619 | one position towards the start of the array. The reference count of this value will be decreased\r | |
620 | by 1.\r | |
621 | \r | |
622 | More details for reference count strategy can refer to the API description for JsonValueFree().\r | |
623 | \r | |
624 | @param[in] JsonArray The provided JSON array.\r | |
625 | @param[in] Index The Index position before removement.\r | |
626 | \r | |
627 | @retval EFI_ABORTED Some error occur and operation aborted.\r | |
628 | @retval EFI_SUCCESS The JSON array has been removed at position index.\r | |
629 | \r | |
630 | **/\r | |
631 | EFI_STATUS\r | |
632 | EFIAPI\r | |
633 | JsonArrayRemoveValue (\r | |
634 | IN EDKII_JSON_ARRAY JsonArray,\r | |
635 | IN UINTN Index\r | |
636 | );\r | |
637 | \r | |
638 | /**\r | |
639 | Dump JSON to a buffer.\r | |
640 | \r | |
641 | @param[in] JsonValue The provided JSON value.\r | |
642 | @param[in] Flags The Index position before removement. The value\r | |
643 | could be the combination of below flags.\r | |
644 | - EDKII_JSON_INDENT(n)\r | |
645 | - EDKII_JSON_COMPACT\r | |
646 | - EDKII_JSON_ENSURE_ASCII\r | |
647 | - EDKII_JSON_SORT_KEYS\r | |
648 | - EDKII_JSON_PRESERVE_ORDER\r | |
649 | - EDKII_JSON_ENCODE_ANY\r | |
650 | - EDKII_JSON_ESCAPE_SLASH\r | |
651 | - EDKII_JSON_REAL_PRECISION(n)\r | |
652 | - EDKII_JSON_EMBED\r | |
653 | See below URI for the JSON encoding flags reference.\r | |
654 | https://jansson.readthedocs.io/en/2.13/apiref.html#encoding\r | |
655 | \r | |
656 | @retval CHAR8 * Dump fail if NULL returned, otherwise the buffer\r | |
657 | contain JSON paylaod in ASCII string. The return\r | |
658 | value must be freed by the caller FreePool().\r | |
659 | **/\r | |
660 | CHAR8 *\r | |
661 | EFIAPI\r | |
662 | JsonDumpString (\r | |
663 | IN EDKII_JSON_VALUE JsonValue,\r | |
664 | IN UINTN Flags\r | |
665 | );\r | |
666 | \r | |
5d7b5cd1 AC |
667 | /**\r |
668 | Convert a string to JSON object.\r | |
669 | The function is used to convert a NULL terminated CHAR8 string to a JSON\r | |
670 | value. Only object and array represented strings can be converted successfully,\r | |
671 | since they are the only valid root values of a JSON text for UEFI usage.\r | |
672 | \r | |
673 | Real number and number with exponent part are not supportted by UEFI.\r | |
674 | \r | |
675 | Caller needs to cleanup the root value by calling JsonValueFree().\r | |
676 | \r | |
677 | @param[in] String The NULL terminated CHAR8 string to convert.\r | |
678 | \r | |
679 | @retval Array JSON value or object JSON value, or NULL when any error occurs.\r | |
680 | \r | |
681 | **/\r | |
682 | EDKII_JSON_VALUE\r | |
683 | EFIAPI\r | |
684 | JsonLoadString (\r | |
685 | IN CONST CHAR8* String\r | |
686 | );\r | |
687 | \r | |
ea830b96 AC |
688 | /**\r |
689 | Load JSON from a buffer.\r | |
690 | \r | |
691 | @param[in] Buffer Bufffer to the JSON payload\r | |
692 | @param[in] BufferLen Length of the buffer\r | |
693 | @param[in] Flags Flag of loading JSON buffer, the value\r | |
694 | could be the combination of below flags.\r | |
695 | - EDKII_JSON_REJECT_DUPLICATES\r | |
696 | - EDKII_JSON_DISABLE_EOF_CHECK\r | |
697 | - EDKII_JSON_DECODE_ANY\r | |
698 | - EDKII_JSON_DECODE_INT_AS_REAL\r | |
699 | - EDKII_JSON_ALLOW_NUL\r | |
700 | See below URI for the JSON encoding flags reference.\r | |
701 | https://jansson.readthedocs.io/en/2.13/apiref.html?highlight=json_loadb#decoding\r | |
702 | \r | |
703 | @param[in,out] Error Pointer EDKII_JSON_ERROR structure\r | |
704 | \r | |
705 | @retval EDKII_JSON_VALUE NULL means fail to load JSON payload.\r | |
706 | **/\r | |
707 | EDKII_JSON_VALUE\r | |
708 | EFIAPI\r | |
709 | JsonLoadBuffer (\r | |
710 | IN CONST CHAR8 *Buffer,\r | |
711 | IN UINTN BufferLen,\r | |
712 | IN UINTN Flags,\r | |
713 | IN OUT EDKII_JSON_ERROR *Error\r | |
714 | );\r | |
715 | \r | |
716 | /**\r | |
717 | The reference count is used to track whether a value is still in use or not.\r | |
718 | When a value is created, it's reference count is set to 1.\r | |
719 | when the value is no longer needed, the reference count is decremented.\r | |
720 | When the reference count drops to zero, there are no references left and the\r | |
721 | value can be destroyed.\r | |
722 | \r | |
723 | This funciton decrement the reference count of EDKII_JSON_VALUE. As soon as\r | |
724 | a call to json_decref() drops the reference count to zero, the value is\r | |
725 | destroyed and it can no longer be used.\r | |
726 | \r | |
727 | @param[in] JsonValue JSON value\r | |
728 | **/\r | |
729 | VOID\r | |
730 | EFIAPI\r | |
731 | JsonDecreaseReference (\r | |
732 | IN EDKII_JSON_VALUE JsonValue\r | |
733 | );\r | |
734 | \r | |
735 | /**\r | |
736 | The reference count is used to track whether a value is still in use or not.\r | |
737 | When a value is created, it's reference count is set to 1.\r | |
738 | If a reference to a value is kept (e.g. a value is stored somewhere for later use),\r | |
739 | its reference count is incremented.\r | |
740 | \r | |
741 | This function increment the reference count of json if it's not NULL.\r | |
742 | Returns EDKII_JSON_VALUE.\r | |
743 | \r | |
744 | @param[in] JsonValue JSON value\r | |
745 | @retval EDKII_JSON_VALUE of itself\r | |
746 | **/\r | |
747 | EDKII_JSON_VALUE\r | |
748 | EFIAPI\r | |
749 | JsonIncreaseReference (\r | |
750 | IN EDKII_JSON_VALUE JsonValue\r | |
751 | );\r | |
752 | /**\r | |
753 | Returns an opaque iterator which can be used to iterate over all key-value pairs\r | |
754 | in object, or NULL if object is empty\r | |
755 | \r | |
756 | @param[in] JsonValue JSON value\r | |
757 | **/\r | |
758 | VOID *\r | |
759 | EFIAPI\r | |
760 | JsonObjectIterator (\r | |
761 | IN EDKII_JSON_VALUE JsonValue\r | |
762 | );\r | |
763 | \r | |
764 | /**\r | |
765 | Extract the associated value from iterator.\r | |
766 | \r | |
767 | @param[in] Iterator Iterator pointer\r | |
768 | **/\r | |
769 | EDKII_JSON_VALUE\r | |
770 | EFIAPI\r | |
771 | JsonObjectIteratorValue (\r | |
772 | IN VOID *Iterator\r | |
773 | );\r | |
774 | \r | |
775 | /**\r | |
776 | Returns an iterator pointing to the next key-value pair in object after iter,\r | |
777 | or NULL if the whole object has been iterated through.\r | |
778 | \r | |
779 | @param[in] JsonValue JSON value\r | |
780 | @param[in] Iterator Iterator pointer\r | |
781 | @retval Iterator pointer\r | |
782 | **/\r | |
783 | VOID *\r | |
784 | JsonObjectIteratorNext (\r | |
785 | IN EDKII_JSON_VALUE JsonValue,\r | |
786 | IN VOID *Iterator\r | |
787 | );\r | |
788 | \r | |
789 | /**\r | |
790 | Returns the json type of this json value\r | |
791 | \r | |
792 | @param[in] JsonValue JSON value\r | |
793 | @retval JSON type returned\r | |
794 | **/\r | |
795 | EDKII_JSON_TYPE\r | |
796 | EFIAPI\r | |
797 | JsonGetType(\r | |
798 | IN EDKII_JSON_VALUE JsonValue\r | |
799 | );\r | |
800 | #endif\r |