RedfishPkg/Include/Library/JsonLib.h

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