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