[mirror_edk2.git] / RedfishPkg / Library / JsonLib / JsonLib.c

/** @file\r
  APIs for JSON operations. The fuctions provided by this library are the\r
  wrapper to native open source jansson library. See below document for\r
  the API reference.\r
  https://jansson.readthedocs.io/en/2.13/apiref.html\r
\r
  Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
 (C) Copyright 2021 Hewlett Packard Enterprise Development LP<BR>\r
\r
    SPDX-License-Identifier: BSD-2-Clause-Patent\r
**/\r
\r
#include <Uefi.h>\r
#include <Library/JsonLib.h>\r
#include <Library/BaseUcs2Utf8Lib.h>\r
#include <Library/MemoryAllocationLib.h>\r
\r
#include "jansson.h"\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON array,\r
  or NULL on error. Initially, the array is empty.\r
\r
  The reference count of this value will be set to 1, and caller needs to cleanup the\r
  value by calling JsonValueFree().\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @retval      The created JSON value which contains a JSON array or NULL if intial a JSON array\r
               is failed.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitArray (\r
  VOID\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_array();\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON object,\r
  or NULL on error. Initially, the object is empty.\r
\r
  The reference count of this value will be set to 1, and caller needs to cleanup the\r
  value by calling JsonValueFree().\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @retval      The created JSON value which contains a JSON object or NULL if intial a JSON object\r
               is failed.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitObject (\r
  VOID\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_object();\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON string,\r
  or NULL on error.\r
\r
  The input string must be NULL terminated Ascii format, non-Ascii characters will\r
  be processed as an error. Unicode characters can also be represented by Ascii string\r
  as the format: \u + 4 hexadecimal digits, like \u3E5A, or \u003F.\r
\r
  The reference count of this value will be set to 1, and caller needs to cleanup the\r
  value by calling JsonValueFree().\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @param[in]   String      The Ascii string to initialize to JSON value\r
\r
  @retval      The created JSON value which contains a JSON string or NULL. Select a\r
               Getter API for a specific encoding format.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitAsciiString (\r
  IN    CONST CHAR8    *String\r
  )\r
{\r
  UINTN    Index;\r
\r
  if (String == NULL) {\r
    return NULL;\r
  }\r
\r
  Index = 0;\r
  while (*(String + Index) != '\0') {\r
    if (((*(String + Index)) & 0x80) != 0x00) {\r
      return NULL;\r
    }\r
\r
    Index++;\r
  }\r
\r
  return (EDKII_JSON_VALUE)json_string (String);\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON string,\r
  or NULL on error.\r
\r
  The input must be a NULL terminated UCS2 format Unicode string.\r
\r
  The reference count of this value will be set to 1, and caller needs to cleanup the\r
  value by calling JsonValueFree().\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @param[in]   String      The Unicode string to initialize to JSON value\r
\r
  @retval      The created JSON value which contains a JSON string or NULL. Select a\r
               Getter API for a specific encoding format.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitUnicodeString (\r
  IN    CHAR16    *String\r
  )\r
{\r
  EFI_STATUS    Status;\r
  CHAR8         *Utf8Str;\r
\r
  if (String == NULL) {\r
    return NULL;\r
  }\r
\r
  Utf8Str = NULL;\r
  Status  = UCS2StrToUTF8 (String, &Utf8Str);\r
  if (EFI_ERROR (Status)) {\r
    return NULL;\r
  }\r
\r
  return (EDKII_JSON_VALUE)json_string (Utf8Str);\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON integer,\r
  or NULL on error.\r
\r
  The reference count of this value will be set to 1, and caller needs to cleanup the\r
  value by calling JsonValueFree().\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @param[in]   Value       The integer to initialize to JSON value\r
\r
  @retval      The created JSON value which contains a JSON integer or NULL.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitInteger (\r
  IN    INT64    Value\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_integer (Value);\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON boolean,\r
  or NULL on error.\r
\r
  Boolean JSON value is kept as static value, and no need to do any cleanup work.\r
\r
  @param[in]   Value       The boolean value to initialize.\r
\r
  @retval      The created JSON value which contains a JSON boolean or NULL.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitBoolean (\r
  IN    BOOLEAN    Value\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_boolean (Value);\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a TRUE JSON value,\r
  or NULL on error.\r
\r
  NULL JSON value is kept as static value, and no need to do any cleanup work.\r
\r
  @retval      The created JSON TRUE value.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitTrue (\r
  VOID\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_true();\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a FALSE JSON value,\r
  or NULL on error.\r
\r
  NULL JSON value is kept as static value, and no need to do any cleanup work.\r
\r
  @retval      The created JSON FALSE value.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitFalse (\r
  VOID\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_false();\r
}\r
\r
/**\r
  The function is used to initialize a JSON value which contains a new JSON NULL,\r
  or NULL on error.\r
\r
  NULL JSON value is kept as static value, and no need to do any cleanup work.\r
\r
  @retval      The created NULL JSON value.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueInitNull (\r
  VOID\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_null();\r
}\r
\r
/**\r
  The function is used to decrease the reference count of a JSON value by one, and once\r
  this reference count drops to zero, the value is destroyed and it can no longer be used.\r
  If this destroyed value is object type or array type, reference counts for all containing\r
  JSON values will be decreased by 1. Boolean JSON value and NULL JSON value won't be destroyed\r
  since they are static values kept in memory.\r
\r
  Reference Count Strategy: BaseJsonLib uses this strategy to track whether a value is still\r
  in use or not. When a value is created, it's reference count is set to 1. If a reference to a\r
  value is kept for use, its reference count is incremented, and when the value is no longer\r
  needed, the reference count is decremented. When the reference count drops to zero, there are\r
  no references left, and the value can be destroyed.\r
\r
  The given JSON value maybe NULL and not causing any problem. Just output the debug message\r
  to inform caller the NULL value is passed in.\r
\r
  @param[in]   Json             The JSON value to be freed. json_decref may return without any\r
                                changes if Json is NULL.\r
\r
**/\r
VOID\r
EFIAPI\r
JsonValueFree (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  json_decref((json_t *)Json);\r
}\r
\r
/**\r
  The function is used to create a fresh copy of a JSON value, and all child values are deep\r
  copied in a recursive fashion. It should be called when this JSON value might be modified\r
  in later use, but the original still wants to be used in somewhere else.\r
\r
  Reference counts of the returned root JSON value and all child values will be set to 1, and\r
  caller needs to cleanup the root value by calling JsonValueFree().\r
\r
  * Note: Since this function performs a copy from bottom to up, too many calls may cause some\r
  performance issues, user should avoid unnecessary calls to this function unless it is really\r
  needed.\r
\r
  @param[in]   Json             The JSON value to be cloned.\r
\r
  @retval      Return the cloned JSON value, or NULL on error.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonValueClone (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_deep_copy ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a JSON array.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a JSON array.\r
  @retval      FALSE            The JSON value doesn't contain a JSON array.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsArray (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_array ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a JSON object.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a JSON object.\r
  @retval      FALSE            The JSON value doesn't contain a JSON object.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsObject (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_object ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON Value contains a string, Ascii or\r
  Unicode format is not differentiated.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a JSON string.\r
  @retval      FALSE            The JSON value doesn't contain a JSON string.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsString (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_string ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a JSON integer.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value is contains JSON integer.\r
  @retval      FALSE            The JSON value doesn't contain a JSON integer.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsInteger (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_integer ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a JSON number.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value is contains JSON number.\r
  @retval      FALSE            The JSON value doesn't contain a JSON number.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsNumber (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_number ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a JSON boolean.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a JSON boolean.\r
  @retval      FALSE            The JSON value doesn't contain a JSON boolean.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsBoolean (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_boolean ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a TRUE value.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a TRUE value.\r
  @retval      FALSE            The JSON value doesn't contain a TRUE value.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsTrue (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  if (json_is_true ((json_t *)Json)) {\r
    return TRUE;\r
  }\r
  return FALSE;\r
}\r
\r
/**\r
  The function is used to return if the provided JSON value contains a FALSE value.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a FALSE value.\r
  @retval      FALSE            The JSON value doesn't contain a FALSE value.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsFalse (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  if (json_is_false ((json_t *)Json)) {\r
    return TRUE;\r
  }\r
  return FALSE;\r
}\r
/**\r
  The function is used to return if the provided JSON value contains a JSON NULL.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      TRUE             The JSON value contains a JSON NULL.\r
  @retval      FALSE            The JSON value doesn't contain a JSON NULL.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueIsNull (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_is_null ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to retrieve the associated array in an array type JSON value.\r
\r
  Any changes to the returned array will impact the original JSON value.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      Return the associated array in JSON value or NULL.\r
\r
**/\r
EDKII_JSON_ARRAY\r
EFIAPI\r
JsonValueGetArray (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  if (Json == NULL || !JsonValueIsArray (Json)) {\r
    return NULL;\r
  }\r
\r
  return (EDKII_JSON_ARRAY)Json;\r
}\r
\r
/**\r
  The function is used to retrieve the associated object in an object type JSON value.\r
\r
  Any changes to the returned object will impact the original JSON value.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      Return the associated object in JSON value or NULL.\r
\r
**/\r
EDKII_JSON_OBJECT\r
EFIAPI\r
JsonValueGetObject (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  if (Json == NULL || !JsonValueIsObject (Json)) {\r
    return NULL;\r
  }\r
\r
  return (EDKII_JSON_OBJECT)Json;\r
}\r
\r
/**\r
  The function is used to retrieve the associated Ascii string in a string type JSON value.\r
\r
  Any changes to the returned string will impact the original JSON value.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      Return the associated Ascii string in JSON value or NULL.\r
\r
**/\r
CONST CHAR8 *\r
EFIAPI\r
JsonValueGetAsciiString (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  CONST CHAR8    *AsciiStr;\r
  UINTN          Index;\r
\r
  AsciiStr = json_string_value ((json_t *) Json);\r
  if (AsciiStr == NULL) {\r
    return NULL;\r
  }\r
\r
  Index = 0;\r
  while (*(AsciiStr + Index) != '\0') {\r
    if (((*(AsciiStr + Index)) & 0x80) != 0x00) {\r
      return NULL;\r
    }\r
\r
    Index++;\r
  }\r
\r
  return AsciiStr;\r
}\r
\r
/**\r
  The function is used to retrieve the associated Unicode string in a string type JSON value.\r
\r
  Caller can do any changes to the returned string without any impact to the original JSON\r
  value, and caller needs to free the returned string using FreePool().\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      Return the associated Unicode string in JSON value or NULL.\r
\r
**/\r
CHAR16*\r
EFIAPI\r
JsonValueGetUnicodeString (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  EFI_STATUS     Status;\r
  CONST CHAR8    *Utf8Str;\r
  CHAR16         *Ucs2Str;\r
\r
  Utf8Str = json_string_value ((json_t *) Json);\r
  if (Utf8Str == NULL) {\r
    return NULL;\r
  }\r
\r
  Status = UTF8StrToUCS2 ((CHAR8*)Utf8Str, &Ucs2Str);\r
  if (EFI_ERROR (Status)) {\r
    return NULL;\r
  }\r
\r
  return Ucs2Str;\r
}\r
\r
/**\r
  The function is used to retrieve the associated integer in a integer type JSON value.\r
\r
  The input JSON value should not be NULL or contain no JSON integer, otherwise it will\r
  ASSERT() and return 0.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      Return the associated integer in JSON value.\r
\r
**/\r
INT64\r
EFIAPI\r
JsonValueGetInteger (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  ASSERT (Json != NULL && JsonValueIsInteger (Json));\r
  if (Json == NULL || !JsonValueIsInteger (Json)) {\r
    return 0;\r
  }\r
\r
  return json_integer_value ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to retrieve the associated boolean in a boolean type JSON value.\r
\r
  The input JSON value should not be NULL or contain no JSON boolean, otherwise it will\r
  ASSERT() and return FALSE.\r
\r
  @param[in]   Json             The provided JSON value.\r
\r
  @retval      Return the associated value of JSON boolean.\r
\r
**/\r
BOOLEAN\r
EFIAPI\r
JsonValueGetBoolean (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  ASSERT (Json != NULL && JsonValueIsBoolean (Json));\r
  if (Json == NULL || !JsonValueIsBoolean (Json)) {\r
    return FALSE;\r
  }\r
\r
  return json_is_true ((json_t *) Json);\r
}\r
\r
/**\r
  The function is used to retrieve the associated string in a string type JSON value.\r
\r
  Any changes to the returned string will impact the original JSON value.\r
\r
  @param[in]   Json The provided JSON value.\r
\r
  @retval      Return the associated Ascii string in JSON value or NULL on errors.\r
\r
**/\r
CONST CHAR8*\r
EFIAPI\r
JsonValueGetString (\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  return json_string_value ((const json_t *)Json);\r
}\r
\r
/**\r
  The function is used to get the number of elements in a JSON object, or 0 if it is NULL or\r
  not a JSON object.\r
\r
  @param[in]   JsonObject              The provided JSON object.\r
\r
  @retval      Return the number of elements in this JSON object or 0.\r
\r
**/\r
UINTN\r
EFIAPI\r
JsonObjectSize (\r
  IN    EDKII_JSON_OBJECT    JsonObject\r
  )\r
{\r
  return json_object_size ((json_t *) JsonObject);\r
}\r
\r
/**\r
  The function is used to enumerate all keys in a JSON object.\r
\r
  Caller should be responsible to free the returned key array reference using\r
  FreePool(). But contained keys are read only and must not be modified or freed.\r
\r
  @param[in]   JsonObj                The provided JSON object for enumeration.\r
  @param[out]  KeyCount               The count of keys in this JSON object.\r
\r
  @retval      Return an array of the enumerated keys in this JSON object or NULL if\r
               JsonObj is not an JSON object, key count is zero or on other errors.\r
\r
**/\r
CHAR8**\r
JsonObjectGetKeys (\r
  IN    EDKII_JSON_OBJECT    JsonObj,\r
  OUT   UINTN                *KeyCount\r
  )\r
{\r
\r
  UINTN               Index;\r
  CONST CHAR8         **KeyArray;\r
  CONST CHAR8         *Key;\r
  EDKII_JSON_VALUE    Value;\r
\r
  if (JsonObj == NULL || KeyCount == NULL) {\r
    return NULL;\r
  }\r
\r
  Index = 0;\r
  json_object_foreach(JsonObj, Key, Value) {\r
    Index++;\r
  }\r
  if (Index == 0) {\r
    *KeyCount = 0;\r
    return NULL;\r
  }\r
\r
  *KeyCount = Index;\r
  KeyArray = (CONST CHAR8 **) AllocateZeroPool (*KeyCount * sizeof (CHAR8 *));\r
  if (KeyArray == NULL) {\r
    return NULL;\r
  }\r
\r
  Key   = NULL;\r
  Value = NULL;\r
  Index = 0;\r
  json_object_foreach((json_t *) JsonObj, Key, Value) {\r
    KeyArray[Index] = Key;\r
    Index++;\r
  }\r
\r
  return (CHAR8 **)KeyArray;\r
}\r
\r
/**\r
  The function is used to get a JSON value corresponding to the input key from a JSON object.\r
\r
  It only returns a reference to this value and any changes on this value will impact the\r
  original JSON object. If that is not expected, please call JsonValueClone() to clone it to\r
  use.\r
\r
  Input key must be a valid NULL terminated UTF8 encoded string. NULL will be returned when\r
  Key-Value is not found in this JSON object.\r
\r
  @param[in]   JsonObj           The provided JSON object.\r
  @param[in]   Key               The key of the JSON value to be retrieved.\r
\r
  @retval      Return the corresponding JSON value to key, or NULL on error.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonObjectGetValue (\r
  IN    CONST EDKII_JSON_OBJECT    JsonObj,\r
  IN    CONST CHAR8                *Key\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_object_get ((const json_t *)JsonObj, (const char *)Key);\r
}\r
\r
/**\r
  The function is used to set a JSON value corresponding to the input key from a JSON object,\r
  and the reference count of this value will be increased by 1.\r
\r
  Input key must be a valid NULL terminated UTF8 encoded string. If there already is a value for\r
  this key, this key will be assigned to the new JSON value. The old JSON value will be removed\r
  from this object and thus its' reference count will be decreased by 1.\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @param[in]   JsonObj                The provided JSON object.\r
  @param[in]   Key                    The key of the JSON value to be set.\r
  @param[in]   Json                   The JSON value to set to this JSON object mapped by key.\r
\r
  @retval      EFI_ABORTED            Some error occur and operation aborted.\r
  @retval      EFI_SUCCESS            The JSON value has been set to this JSON object.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
JsonObjectSetValue (\r
  IN    EDKII_JSON_OBJECT    JsonObj,\r
  IN    CONST CHAR8          *Key,\r
  IN    EDKII_JSON_VALUE     Json\r
  )\r
{\r
  if (json_object_set ((json_t *) JsonObj, Key, (json_t *) Json) != 0) {\r
    return EFI_ABORTED;\r
  } else {\r
    return EFI_SUCCESS;\r
  }\r
}\r
\r
/**\r
  The function is used to get the number of elements in a JSON array. Returns or 0 if JsonArray\r
  is NULL or not a JSON array.\r
\r
  @param[in]   JsonArray              The provided JSON array.\r
\r
  @retval      Return the number of elements in this JSON array or 0.\r
\r
**/\r
UINTN\r
EFIAPI\r
JsonArrayCount (\r
  IN    EDKII_JSON_ARRAY    JsonArray\r
  )\r
{\r
  return json_array_size ((json_t *) JsonArray);\r
}\r
\r
/**\r
  The function is used to return the JSON value in the array at position index. The valid range\r
  for this index is from 0 to the return value of JsonArrayCount() minus 1.\r
\r
  It only returns a reference to this value and any changes on this value will impact the\r
  original JSON object. If that is not expected, please call JsonValueClone() to clone it to\r
  use.\r
\r
  If this array is NULL or not a JSON array, or if index is out of range, NULL will be returned.\r
\r
  @param[in]   JsonArray         The provided JSON Array.\r
\r
  @retval      Return the JSON value located in the Index position or\r
               NULL if JsonArray is not an array or no items in the array.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonArrayGetValue (\r
  IN    EDKII_JSON_ARRAY    JsonArray,\r
  IN    UINTN               Index\r
  )\r
{\r
  return (EDKII_JSON_VALUE)json_array_get ((json_t *) JsonArray, Index);\r
}\r
\r
/**\r
  The function is used to append a JSON value to the end of the JSON array, and grow the size of\r
  array by 1. The reference count of this value will be increased by 1.\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @param[in]   JsonArray              The provided JSON object.\r
  @param[in]   Json                   The JSON value to append.\r
\r
  @retval      EFI_ABORTED            Some error occur and operation aborted.\r
  @retval      EFI_SUCCESS            JSON value has been appended to the end of the JSON array.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
JsonArrayAppendValue (\r
  IN    EDKII_JSON_ARRAY    JsonArray,\r
  IN    EDKII_JSON_VALUE    Json\r
  )\r
{\r
  if (json_array_append ((json_t *) JsonArray, (json_t *) Json) != 0) {\r
    return EFI_ABORTED;\r
  } else {\r
    return EFI_SUCCESS;\r
  }\r
}\r
\r
/**\r
  The function is used to remove a JSON value at position index, shifting the elements after index\r
  one position towards the start of the array. The reference count of this value will be decreased\r
  by 1.\r
\r
  More details for reference count strategy can refer to the API description for JsonValueFree().\r
\r
  @param[in]   JsonArray              The provided JSON array.\r
  @param[in]   Index                  The Index position before removement.\r
\r
  @retval      EFI_ABORTED            Some error occur and operation aborted.\r
  @retval      EFI_SUCCESS            The JSON array has been removed at position index.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
JsonArrayRemoveValue (\r
  IN    EDKII_JSON_ARRAY    JsonArray,\r
  IN    UINTN               Index\r
  )\r
{\r
  if (json_array_remove ((json_t *) JsonArray, Index) != 0) {\r
    return EFI_ABORTED;\r
  } else {\r
    return EFI_SUCCESS;\r
  }\r
}\r
\r
/**\r
  Dump JSON to a buffer.\r
\r
  @param[in]   JsonValue       The provided JSON value.\r
  @param[in]   Flags           The Index position before removement. The value\r
                               could be the combination of below flags.\r
                                 - EDKII_JSON_INDENT(n)\r
                                 - EDKII_JSON_COMPACT\r
                                 - EDKII_JSON_ENSURE_ASCII\r
                                 - EDKII_JSON_SORT_KEYS\r
                                 - EDKII_JSON_PRESERVE_ORDER\r
                                 - EDKII_JSON_ENCODE_ANY\r
                                 - EDKII_JSON_ESCAPE_SLASH\r
                                 - EDKII_JSON_REAL_PRECISION(n)\r
                                 - EDKII_JSON_EMBED\r
                               See below URI for the JSON encoding flags reference.\r
                               https://jansson.readthedocs.io/en/2.13/apiref.html#encoding\r
\r
  @retval      CHAR8 *         Dump fail if NULL returned, otherwise the buffer\r
                               contain JSON paylaod in ASCII string. The return\r
                               value must be freed by the caller using FreePool().\r
**/\r
CHAR8 *\r
EFIAPI\r
JsonDumpString (\r
  IN    EDKII_JSON_VALUE    JsonValue,\r
  IN    UINTN               Flags\r
  )\r
{\r
    if (JsonValue == NULL) {\r
      return NULL;\r
    }\r
    return json_dumps((json_t *)JsonValue, Flags);\r
}\r
\r
/**\r
  Convert a string to JSON object.\r
  The function is used to convert a NULL terminated CHAR8 string to a JSON\r
  value. Only object and array represented strings can be converted successfully,\r
  since they are the only valid root values of a JSON text for UEFI usage.\r
\r
  Real number and number with exponent part are not supportted by UEFI.\r
\r
  Caller needs to cleanup the root value by calling JsonValueFree().\r
\r
  @param[in]   String        The NULL terminated CHAR8 string to convert.\r
  @param[in]   Flags         Flags for loading JSON string.\r
  @param[in]   Error         Returned error status.\r
\r
  @retval      Array JSON value or object JSON value, or NULL when any error occurs.\r
\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonLoadString (\r
  IN    CONST CHAR8*     String,\r
  IN    UINT64           Flags,\r
  IN    EDKII_JSON_ERROR *Error\r
  )\r
{\r
  return (EDKII_JSON_VALUE) json_loads ((const char *)String, Flags, (json_error_t *)Error);\r
}\r
\r
/**\r
  Load JSON from a buffer.\r
\r
  @param[in]   Buffer        Bufffer to the JSON payload\r
  @param[in]   BufferLen     Length of the buffer\r
  @param[in]   Flags         Flag of loading JSON buffer, the value\r
                             could be the combination of below flags.\r
                               - EDKII_JSON_REJECT_DUPLICATES\r
                               - EDKII_JSON_DISABLE_EOF_CHECK\r
                               - EDKII_JSON_DECODE_ANY\r
                               - EDKII_JSON_DECODE_INT_AS_REAL\r
                               - EDKII_JSON_ALLOW_NUL\r
                             See below URI for the JSON encoding flags reference.\r
                             https://jansson.readthedocs.io/en/2.13/apiref.html?highlight=json_loadb#decoding\r
\r
  @param[in,out]   Error     Pointer EDKII_JSON_ERROR structure\r
\r
  @retval      EDKII_JSON_VALUE  NULL means fail to load JSON payload.\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonLoadBuffer (\r
  IN    CONST CHAR8       *Buffer,\r
  IN    UINTN              BufferLen,\r
  IN    UINTN              Flags,\r
  IN OUT EDKII_JSON_ERROR  *Error\r
  )\r
{\r
  return json_loadb(Buffer, BufferLen, Flags, (json_error_t *)Error);\r
}\r
\r
/**\r
  The reference count is used to track whether a value is still in use or not.\r
  When a value is created, it's reference count is set to 1.\r
  when the value is no longer needed, the reference count is decremented.\r
  When the reference count drops to zero, there are no references left and the\r
  value can be destroyed.\r
\r
  This funciton decrement the reference count of EDKII_JSON_VALUE. As soon as\r
  a call to json_decref() drops the reference count to zero, the value is\r
  destroyed and it can no longer be used.\r
\r
  @param[in]   JsonValue      JSON value\r
**/\r
VOID\r
EFIAPI\r
JsonDecreaseReference (\r
  IN EDKII_JSON_VALUE JsonValue\r
  )\r
{\r
  json_decref (JsonValue);\r
}\r
\r
/**\r
  The reference count is used to track whether a value is still in use or not.\r
  When a value is created, it's reference count is set to 1.\r
  If a reference to a value is kept (e.g. a value is stored somewhere for later use),\r
  its reference count is incremented.\r
\r
  This function increment the reference count of json if it's not NULL.\r
  Returns EDKII_JSON_VALUE.\r
\r
  @param[in]   JsonValue      JSON value\r
  @retval      EDKII_JSON_VALUE of itself\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonIncreaseReference (\r
  IN EDKII_JSON_VALUE JsonValue\r
  )\r
{\r
  return json_incref (JsonValue);\r
}\r
\r
/**\r
  Returns an opaque iterator which can be used to iterate over all key-value pairs\r
  in object, or NULL if object is empty.\r
\r
  @param[in]   JsonValue      JSON value\r
  @retval      Iterator pointer\r
**/\r
VOID *\r
EFIAPI\r
JsonObjectIterator (\r
  IN EDKII_JSON_VALUE JsonValue\r
  )\r
{\r
  return json_object_iter (JsonValue);\r
}\r
\r
/**\r
  Extract the associated value from iterator.\r
\r
  @param[in]   Iterator   Iterator pointer\r
  @retval      EDKII_JSON_VALUE\r
**/\r
EDKII_JSON_VALUE\r
EFIAPI\r
JsonObjectIteratorValue (\r
  IN VOID *Iterator\r
  )\r
{\r
  return json_object_iter_value(Iterator);\r
}\r
\r
/**\r
  Returns an iterator pointing to the next key-value pair in object after iter,\r
  or NULL if the whole object has been iterated through.\r
\r
  @param[in]   JsonValue  JSON value\r
  @param[in]   Iterator   Iterator pointer\r
  @retval      Iterator pointer\r
**/\r
VOID *\r
EFIAPI\r
JsonObjectIteratorNext (\r
  IN EDKII_JSON_VALUE JsonValue,\r
  IN VOID             *Iterator\r
  )\r
{\r
  return json_object_iter_next(JsonValue, Iterator);\r
}\r
\r
/**\r
  Returns the key of iterator pointing.\r
\r
  @param[in]   Iterator   Iterator pointer\r
  @retval      Key\r
**/\r
CHAR8 *\r
EFIAPI\r
JsonObjectIteratorKey (\r
  IN VOID *Iterator\r
)\r
{\r
  return (CHAR8 *)json_object_iter_key(Iterator);\r
}\r
\r
/**\r
  Returns the pointer of iterator by key.\r
\r
  @param[in]   Key   The key of interator pointer.\r
  @retval      Pointer to interator\r
**/\r
VOID *\r
EFIAPI\r
JsonObjectKeyToIterator (\r
  IN CHAR8 *Key\r
)\r
{\r
  return json_object_key_to_iter(Key);\r
}\r
\r
/**\r
  Returns the json type of this json value.\r
\r
  @param[in]   JsonValue  JSON value\r
  @retval      JSON type returned\r
**/\r
EDKII_JSON_TYPE\r
EFIAPI\r
JsonGetType (\r
  IN EDKII_JSON_VALUE JsonValue\r
  )\r
{\r
  return ((json_t *)JsonValue)->type;\r
}\r