RedfishPkg/Library/JsonLib/JsonLib.c

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