JsonLib.h 27 KB

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