Signed-off-by: Abner Chang <abner.chang@hpe.com> Cc: Nickle Wang <nickle.wang@hpe.com> Reviewed-by: Nickle Wang <nickle.wang@hpe.com>
		
			
				
	
	
		
			912 lines
		
	
	
		
			27 KiB
		
	
	
	
		
			C
		
	
	
	
	
	
			
		
		
	
	
			912 lines
		
	
	
		
			27 KiB
		
	
	
	
		
			C
		
	
	
	
	
	
/** @file
 | 
						|
  APIs for JSON operations.
 | 
						|
 | 
						|
  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
 | 
						|
 (C) Copyright 2021 Hewlett Packard Enterprise Development LP<BR>
 | 
						|
 | 
						|
    SPDX-License-Identifier: BSD-2-Clause-Patent
 | 
						|
 | 
						|
**/
 | 
						|
#ifndef JSON_LIB_H_
 | 
						|
#define JSON_LIB_H_
 | 
						|
 | 
						|
typedef    VOID*    EDKII_JSON_VALUE;
 | 
						|
typedef    VOID*    EDKII_JSON_ARRAY;
 | 
						|
typedef    VOID*    EDKII_JSON_OBJECT;
 | 
						|
 | 
						|
///
 | 
						|
/// Map to json_int_t in jansson.h
 | 
						|
///
 | 
						|
typedef    INT64   EDKII_JSON_INT_T; // #JSON_INTEGER_IS_LONG_LONG is set to 1
 | 
						|
                                     // in jansson_Config.h
 | 
						|
 | 
						|
///
 | 
						|
/// Map to the definitions in jansson.h
 | 
						|
/// See below URI for the JSON encoding flags reference.
 | 
						|
/// https://jansson.readthedocs.io/en/2.13/apiref.html#encoding
 | 
						|
///
 | 
						|
#define EDKII_JSON_MAX_INDENT        0x1F
 | 
						|
#define EDKII_JSON_INDENT(n)         ((n) & EDKII_JSON_MAX_INDENT)
 | 
						|
 | 
						|
#define EDKII_JSON_COMPACT           0x20
 | 
						|
#define EDKII_JSON_ENSURE_ASCII      0x40
 | 
						|
#define EDKII_JSON_SORT_KEYS         0x80
 | 
						|
#define EDKII_JSON_PRESERVE_ORDER    0x100
 | 
						|
#define EDKII_JSON_ENCODE_ANY        0x200
 | 
						|
#define EDKII_JSON_ESCAPE_SLASH      0x400
 | 
						|
#define EDKII_JSON_REAL_PRECISION(n) (((n) & 0x1F) << 11)
 | 
						|
#define EDKII_JSON_EMBED             0x10000
 | 
						|
 | 
						|
///
 | 
						|
/// Map to the definitions in jansson.h
 | 
						|
/// See below URI for the JSON decoding flags reference.
 | 
						|
/// https://jansson.readthedocs.io/en/2.13/apiref.html?highlight=json_loadb#decoding
 | 
						|
///
 | 
						|
#define EDKII_JSON_REJECT_DUPLICATES  0x1
 | 
						|
#define EDKII_JSON_DISABLE_EOF_CHECK  0x2
 | 
						|
#define EDKII_JSON_DECODE_ANY         0x4
 | 
						|
#define EDKII_JSON_DECODE_INT_AS_REAL 0x8
 | 
						|
#define EDKII_JSON_ALLOW_NUL          0x10
 | 
						|
 | 
						|
#define EDKII_JSON_ARRAY_FOREACH(Array, Index, Value) \
 | 
						|
  for(Index = 0; \
 | 
						|
    Index < JsonArrayCount(Array) && (Value = JsonArrayGetValue(Array, Index)); \
 | 
						|
    Index++)
 | 
						|
 | 
						|
#define EDKII_JSON_OBJECT_FOREACH_SAFE(Object, N, Key, Value)           \
 | 
						|
    for (Key = JsonObjectIteratorKey(JsonObjectIterator(Object)),                \
 | 
						|
        N = JsonObjectIteratorNext(Object, JsonObjectKeyToIterator(Key));        \
 | 
						|
        Key && (Value = JsonObjectIteratorValue(JsonObjectKeyToIterator(Key)));  \
 | 
						|
        Key = JsonObjectIteratorKey(N),                                      \
 | 
						|
        N = JsonObjectIteratorNext(Object, JsonObjectKeyToIterator(Key)))
 | 
						|
 | 
						|
///
 | 
						|
///  Map to the json_error_t in jansson.h
 | 
						|
///
 | 
						|
#define EDKII_JSON_ERROR_TEXT_LENGTH   160
 | 
						|
#define EDKII_JSON_ERROR_SOURCE_LENGTH 80
 | 
						|
typedef struct {
 | 
						|
    INTN    Line;
 | 
						|
    INTN    Column;
 | 
						|
    INTN    Position;
 | 
						|
    CHAR8   Source [EDKII_JSON_ERROR_SOURCE_LENGTH];
 | 
						|
    CHAR8   Text [EDKII_JSON_ERROR_TEXT_LENGTH];
 | 
						|
} EDKII_JSON_ERROR;
 | 
						|
 | 
						|
///
 | 
						|
///  Map to the json_type in jansson.h
 | 
						|
///
 | 
						|
typedef enum {
 | 
						|
    EdkiiJsonTypeObject,
 | 
						|
    EdkiiJsonTypeArray,
 | 
						|
    EdkiiJsonTypeString,
 | 
						|
    EdkiiJsonTypeInteger,
 | 
						|
    EdkiiJsonTypeReal,
 | 
						|
    EdkiiJsonTypeTrue,
 | 
						|
    EdkiiJsonTypeFalse,
 | 
						|
    EdkiiJsonTypeNull
 | 
						|
} EDKII_JSON_TYPE;
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON array,
 | 
						|
  or NULL on error. Initially, the array is empty.
 | 
						|
 | 
						|
  The reference count of this value will be set to 1, and caller needs to cleanup the
 | 
						|
  value by calling JsonValueFree().
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @retval      The created JSON value which contains a JSON array or NULL if intial a JSON array
 | 
						|
               is failed.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitArray (
 | 
						|
  VOID
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON object,
 | 
						|
  or NULL on error. Initially, the object is empty.
 | 
						|
 | 
						|
  The reference count of this value will be set to 1, and caller needs to cleanup the
 | 
						|
  value by calling JsonValueFree().
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @retval      The created JSON value which contains a JSON object or NULL if intial a JSON object
 | 
						|
               is failed.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitObject (
 | 
						|
  VOID
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON string,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  The input string must be NULL terminated Ascii format, non-Ascii characters will
 | 
						|
  be processed as an error. Unicode characters can also be represented by Ascii string
 | 
						|
  as the format: \u + 4 hexadecimal digits, like \u3E5A, or \u003F.
 | 
						|
 | 
						|
  The reference count of this value will be set to 1, and caller needs to cleanup the
 | 
						|
  value by calling JsonValueFree().
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   String      The Ascii string to initialize to JSON value
 | 
						|
 | 
						|
  @retval      The created JSON value which contains a JSON string or NULL. Select a
 | 
						|
               Getter API for a specific encoding format.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitAsciiString (
 | 
						|
  IN    CONST CHAR8    *String
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON string,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  The input must be a NULL terminated UCS2 format Unicode string.
 | 
						|
 | 
						|
  The reference count of this value will be set to 1, and caller needs to cleanup the
 | 
						|
  value by calling JsonValueFree().
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   String      The Unicode string to initialize to JSON value
 | 
						|
 | 
						|
  @retval      The created JSON value which contains a JSON string or NULL. Select a
 | 
						|
               Getter API for a specific encoding format.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitUnicodeString (
 | 
						|
  IN    CHAR16    *String
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON integer,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  The reference count of this value will be set to 1, and caller needs to cleanup the
 | 
						|
  value by calling JsonValueFree().
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   Value       The integer to initialize to JSON value
 | 
						|
 | 
						|
  @retval      The created JSON value which contains a JSON integer or NULL.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitInteger (
 | 
						|
  IN    INT64    Value
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON boolean,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  Boolean JSON value is kept as static value, and no need to do any cleanup work.
 | 
						|
 | 
						|
  @param[in]   Value       The boolean value to initialize.
 | 
						|
 | 
						|
  @retval      The created JSON value which contains a JSON boolean or NULL.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitBoolean (
 | 
						|
  IN    BOOLEAN    Value
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a new JSON NULL,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  NULL JSON value is kept as static value, and no need to do any cleanup work.
 | 
						|
 | 
						|
  @retval      The created NULL JSON value.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitNull (
 | 
						|
  VOID
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a TRUE JSON value,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  NULL JSON value is kept as static value, and no need to do any cleanup work.
 | 
						|
 | 
						|
  @retval      The created JSON TRUE value.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitTrue (
 | 
						|
  VOID
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to initialize a JSON value which contains a FALSE JSON value,
 | 
						|
  or NULL on error.
 | 
						|
 | 
						|
  NULL JSON value is kept as static value, and no need to do any cleanup work.
 | 
						|
 | 
						|
  @retval      The created JSON FALSE value.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueInitFalse (
 | 
						|
  VOID
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to decrease the reference count of a JSON value by one, and once
 | 
						|
  this reference count drops to zero, the value is destroyed and it can no longer be used.
 | 
						|
  If this destroyed value is object type or array type, reference counts for all containing
 | 
						|
  JSON values will be decreased by 1. Boolean JSON value and NULL JSON value won't be destroyed
 | 
						|
  since they are static values kept in memory.
 | 
						|
 | 
						|
  Reference Count Strategy: BaseJsonLib uses this strategy to track whether a value is still
 | 
						|
  in use or not. When a value is created, it's reference count is set to 1. If a reference to a
 | 
						|
  value is kept for use, its reference count is incremented, and when the value is no longer
 | 
						|
  needed, the reference count is decremented. When the reference count drops to zero, there are
 | 
						|
  no references left, and the value can be destroyed.
 | 
						|
 | 
						|
  The given JSON value maybe NULL and not causing any problem. Just output the debug message
 | 
						|
  to inform caller the NULL value is passed in.
 | 
						|
 | 
						|
  @param[in]   Json             The JSON value to be freed. json_decref may return without any
 | 
						|
                                changes if Json is NULL.
 | 
						|
 | 
						|
**/
 | 
						|
VOID
 | 
						|
EFIAPI
 | 
						|
JsonValueFree (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to create a fresh copy of a JSON value, and all child values are deep
 | 
						|
  copied in a recursive fashion. It should be called when this JSON value might be modified
 | 
						|
  in later use, but the original still wants to be used in somewhere else.
 | 
						|
 | 
						|
  Reference counts of the returned root JSON value and all child values will be set to 1, and
 | 
						|
  caller needs to cleanup the root value by calling JsonValueFree().
 | 
						|
 | 
						|
  * Note: Since this function performs a copy from bottom to up, too many calls may cause some
 | 
						|
  performance issues, user should avoid unnecessary calls to this function unless it is really
 | 
						|
  needed.
 | 
						|
 | 
						|
  @param[in]   Json             The JSON value to be cloned.
 | 
						|
 | 
						|
  @retval      Return the cloned JSON value, or NULL on error.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonValueClone (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a JSON array.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a JSON array.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON array.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsArray (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a JSON object.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a JSON object.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON object.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsObject (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON Value contains a string, Ascii or
 | 
						|
  Unicode format is not differentiated.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a JSON string.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON string.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsString (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a JSON integer.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value is contains JSON integer.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON integer.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsInteger (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a JSON number.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value is contains JSON number.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON number.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsNumber (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a JSON boolean.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a JSON boolean.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON boolean.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsBoolean (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a TRUE value.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a TRUE value.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a TRUE value.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsTrue (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a FALSE value.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a FALSE value.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a FALSE value.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsFalse (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return if the provided JSON value contains a JSON NULL.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      TRUE             The JSON value contains a JSON NULL.
 | 
						|
  @retval      FALSE            The JSON value doesn't contain a JSON NULL.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueIsNull (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated array in an array type JSON value.
 | 
						|
 | 
						|
  Any changes to the returned array will impact the original JSON value.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated array in JSON value or NULL.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_ARRAY
 | 
						|
EFIAPI
 | 
						|
JsonValueGetArray (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated object in an object type JSON value.
 | 
						|
 | 
						|
  Any changes to the returned object will impact the original JSON value.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated object in JSON value or NULL.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_OBJECT
 | 
						|
EFIAPI
 | 
						|
JsonValueGetObject (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated Ascii string in a string type JSON value.
 | 
						|
 | 
						|
  Any changes to the returned string will impact the original JSON value.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated Ascii string in JSON value or NULL.
 | 
						|
 | 
						|
**/
 | 
						|
CONST CHAR8 *
 | 
						|
EFIAPI
 | 
						|
JsonValueGetAsciiString (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated Unicode string in a string type JSON value.
 | 
						|
 | 
						|
  Caller can do any changes to the returned string without any impact to the original JSON
 | 
						|
  value, and caller needs to free the returned string using FreePool().
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated Unicode string in JSON value or NULL.
 | 
						|
 | 
						|
**/
 | 
						|
CHAR16*
 | 
						|
EFIAPI
 | 
						|
JsonValueGetUnicodeString (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated integer in a integer type JSON value.
 | 
						|
 | 
						|
  The input JSON value should not be NULL or contain no JSON Integer, otherwise it will
 | 
						|
  ASSERT() and return 0.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated Integer in JSON value.
 | 
						|
 | 
						|
**/
 | 
						|
INT64
 | 
						|
EFIAPI
 | 
						|
JsonValueGetInteger (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated boolean in a boolean type JSON value.
 | 
						|
 | 
						|
  The input JSON value should not be NULL or contain no JSON boolean, otherwise it will
 | 
						|
  ASSERT() and return FALSE.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated value of JSON boolean.
 | 
						|
 | 
						|
**/
 | 
						|
BOOLEAN
 | 
						|
EFIAPI
 | 
						|
JsonValueGetBoolean (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to retrieve the associated string in a string type JSON value.
 | 
						|
 | 
						|
  Any changes to the returned string will impact the original JSON value.
 | 
						|
 | 
						|
  @param[in]   Json             The provided JSON value.
 | 
						|
 | 
						|
  @retval      Return the associated Ascii string in JSON value or NULL on errors.
 | 
						|
 | 
						|
**/
 | 
						|
CONST CHAR8*
 | 
						|
EFIAPI
 | 
						|
JsonValueGetString (
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to get the number of elements in a JSON object, or 0 if it is NULL or
 | 
						|
  not a JSON object.
 | 
						|
 | 
						|
  @param[in]   JsonObject              The provided JSON object.
 | 
						|
 | 
						|
  @retval      Return the number of elements in this JSON object or 0.
 | 
						|
 | 
						|
**/
 | 
						|
UINTN
 | 
						|
EFIAPI
 | 
						|
JsonObjectSize (
 | 
						|
  IN    EDKII_JSON_OBJECT    JsonObject
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to enumerate all keys in a JSON object.
 | 
						|
 | 
						|
  Caller should be responsible to free the returned key array reference using
 | 
						|
  FreePool(). But contained keys are read only and must not be modified or freed.
 | 
						|
 | 
						|
  @param[in]   JsonObj                The provided JSON object for enumeration.
 | 
						|
  @param[out]  KeyCount               The count of keys in this JSON object.
 | 
						|
 | 
						|
  @retval      Return an array of the enumerated keys in this JSON object or NULL if
 | 
						|
               JsonObj is not an JSON object, key count is zero or on other errors.
 | 
						|
 | 
						|
**/
 | 
						|
CHAR8**
 | 
						|
JsonObjectGetKeys (
 | 
						|
  IN    EDKII_JSON_OBJECT    JsonObj,
 | 
						|
  OUT   UINTN                *KeyCount
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to get a JSON value corresponding to the input key from a JSON object.
 | 
						|
 | 
						|
  It only returns a reference to this value and any changes on this value will impact the
 | 
						|
  original JSON object. If that is not expected, please call JsonValueClone() to clone it to
 | 
						|
  use.
 | 
						|
 | 
						|
  Input key must be a valid NULL terminated UTF8 encoded string. NULL will be returned when
 | 
						|
  Key-Value is not found in this JSON object.
 | 
						|
 | 
						|
  @param[in]   JsonObj           The provided JSON object.
 | 
						|
  @param[in]   Key               The key of the JSON value to be retrieved.
 | 
						|
 | 
						|
  @retval      Return the corresponding JSON value to key, or NULL on error.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonObjectGetValue (
 | 
						|
  IN    CONST EDKII_JSON_OBJECT    JsonObj,
 | 
						|
  IN    CONST CHAR8                *Key
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to set a JSON value corresponding to the input key from a JSON object,
 | 
						|
  and the reference count of this value will be increased by 1.
 | 
						|
 | 
						|
  Input key must be a valid NULL terminated UTF8 encoded string. If there already is a value for
 | 
						|
  this key, this key will be assigned to the new JSON value. The old JSON value will be removed
 | 
						|
  from this object and thus its' reference count will be decreased by 1.
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   JsonObj                The provided JSON object.
 | 
						|
  @param[in]   Key                    The key of the JSON value to be set.
 | 
						|
  @param[in]   Json                   The JSON value to set to this JSON object mapped by key.
 | 
						|
 | 
						|
  @retval      EFI_ABORTED            Some error occur and operation aborted.
 | 
						|
  @retval      EFI_SUCCESS            The JSON value has been set to this JSON object.
 | 
						|
 | 
						|
**/
 | 
						|
EFI_STATUS
 | 
						|
EFIAPI
 | 
						|
JsonObjectSetValue (
 | 
						|
  IN    EDKII_JSON_OBJECT    JsonObj,
 | 
						|
  IN    CONST CHAR8          *Key,
 | 
						|
  IN    EDKII_JSON_VALUE     Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to get the number of elements in a JSON array. Returns or 0 if JsonArray
 | 
						|
  is NULL or not a JSON array.
 | 
						|
 | 
						|
  @param[in]   JsonArray              The provided JSON array.
 | 
						|
 | 
						|
  @retval      Return the number of elements in this JSON array or 0.
 | 
						|
 | 
						|
**/
 | 
						|
UINTN
 | 
						|
EFIAPI
 | 
						|
JsonArrayCount (
 | 
						|
  IN    EDKII_JSON_ARRAY    JsonArray
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to return the JSON value in the array at position index. The valid range
 | 
						|
  for this index is from 0 to the return value of JsonArrayCount() minus 1.
 | 
						|
 | 
						|
  It only returns a reference to this value and any changes on this value will impact the
 | 
						|
  original JSON object. If that is not expected, please call JsonValueClone() to clone it to
 | 
						|
  use.
 | 
						|
 | 
						|
  If this array is NULL or not a JSON array, or if index is out of range, NULL will be returned.
 | 
						|
 | 
						|
  @param[in]   JsonArray         The provided JSON Array.
 | 
						|
 | 
						|
  @retval      Return the JSON value located in the Index position or
 | 
						|
               NULL if JsonArray is not an array or no items in the array.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonArrayGetValue (
 | 
						|
  IN    EDKII_JSON_ARRAY    JsonArray,
 | 
						|
  IN    UINTN               Index
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to append a JSON value to the end of the JSON array, and grow the size of
 | 
						|
  array by 1. The reference count of this value will be increased by 1.
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   JsonArray              The provided JSON object.
 | 
						|
  @param[in]   Json                   The JSON value to append.
 | 
						|
 | 
						|
  @retval      EFI_ABORTED            Some error occur and operation aborted.
 | 
						|
  @retval      EFI_SUCCESS            JSON value has been appended to the end of the JSON array.
 | 
						|
 | 
						|
**/
 | 
						|
EFI_STATUS
 | 
						|
EFIAPI
 | 
						|
JsonArrayAppendValue (
 | 
						|
  IN    EDKII_JSON_ARRAY    JsonArray,
 | 
						|
  IN    EDKII_JSON_VALUE    Json
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The function is used to remove a JSON value at position index, shifting the elements after index
 | 
						|
  one position towards the start of the array. The reference count of this value will be decreased
 | 
						|
  by 1.
 | 
						|
 | 
						|
  More details for reference count strategy can refer to the API description for JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   JsonArray              The provided JSON array.
 | 
						|
  @param[in]   Index                  The Index position before removement.
 | 
						|
 | 
						|
  @retval      EFI_ABORTED            Some error occur and operation aborted.
 | 
						|
  @retval      EFI_SUCCESS            The JSON array has been removed at position index.
 | 
						|
 | 
						|
**/
 | 
						|
EFI_STATUS
 | 
						|
EFIAPI
 | 
						|
JsonArrayRemoveValue (
 | 
						|
  IN    EDKII_JSON_ARRAY    JsonArray,
 | 
						|
  IN    UINTN               Index
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  Dump JSON to a buffer.
 | 
						|
 | 
						|
  @param[in]   JsonValue       The provided JSON value.
 | 
						|
  @param[in]   Flags           The Index position before removement. The value
 | 
						|
                               could be the combination of below flags.
 | 
						|
                                 - EDKII_JSON_INDENT(n)
 | 
						|
                                 - EDKII_JSON_COMPACT
 | 
						|
                                 - EDKII_JSON_ENSURE_ASCII
 | 
						|
                                 - EDKII_JSON_SORT_KEYS
 | 
						|
                                 - EDKII_JSON_PRESERVE_ORDER
 | 
						|
                                 - EDKII_JSON_ENCODE_ANY
 | 
						|
                                 - EDKII_JSON_ESCAPE_SLASH
 | 
						|
                                 - EDKII_JSON_REAL_PRECISION(n)
 | 
						|
                                 - EDKII_JSON_EMBED
 | 
						|
                               See below URI for the JSON encoding flags reference.
 | 
						|
                               https://jansson.readthedocs.io/en/2.13/apiref.html#encoding
 | 
						|
 | 
						|
  @retval      CHAR8 *         Dump fail if NULL returned, otherwise the buffer
 | 
						|
                               contain JSON paylaod in ASCII string. The return
 | 
						|
                               value must be freed by the caller FreePool().
 | 
						|
**/
 | 
						|
CHAR8 *
 | 
						|
EFIAPI
 | 
						|
JsonDumpString (
 | 
						|
  IN    EDKII_JSON_VALUE    JsonValue,
 | 
						|
  IN    UINTN               Flags
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  Convert a string to JSON object.
 | 
						|
  The function is used to convert a NULL terminated CHAR8 string to a JSON
 | 
						|
  value. Only object and array represented strings can be converted successfully,
 | 
						|
  since they are the only valid root values of a JSON text for UEFI usage.
 | 
						|
 | 
						|
  Real number and number with exponent part are not supportted by UEFI.
 | 
						|
 | 
						|
  Caller needs to cleanup the root value by calling JsonValueFree().
 | 
						|
 | 
						|
  @param[in]   String        The NULL terminated CHAR8 string to convert.
 | 
						|
  @param[in]   Flags         Flags for loading JSON string.
 | 
						|
  @param[in]   Error         Returned error status.
 | 
						|
 | 
						|
  @retval      Array JSON value or object JSON value, or NULL when any error occurs.
 | 
						|
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonLoadString (
 | 
						|
  IN    CONST CHAR8*     String,
 | 
						|
  IN    UINT64           Flags,
 | 
						|
  IN    EDKII_JSON_ERROR *Error
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  Load JSON from a buffer.
 | 
						|
 | 
						|
  @param[in]   Buffer        Bufffer to the JSON payload
 | 
						|
  @param[in]   BufferLen     Length of the buffer
 | 
						|
  @param[in]   Flags         Flag of loading JSON buffer, the value
 | 
						|
                             could be the combination of below flags.
 | 
						|
                               - EDKII_JSON_REJECT_DUPLICATES
 | 
						|
                               - EDKII_JSON_DISABLE_EOF_CHECK
 | 
						|
                               - EDKII_JSON_DECODE_ANY
 | 
						|
                               - EDKII_JSON_DECODE_INT_AS_REAL
 | 
						|
                               - EDKII_JSON_ALLOW_NUL
 | 
						|
                             See below URI for the JSON encoding flags reference.
 | 
						|
                             https://jansson.readthedocs.io/en/2.13/apiref.html?highlight=json_loadb#decoding
 | 
						|
 | 
						|
  @param[in,out]   Error     Pointer EDKII_JSON_ERROR structure
 | 
						|
 | 
						|
  @retval      EDKII_JSON_VALUE  NULL means fail to load JSON payload.
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonLoadBuffer (
 | 
						|
  IN    CONST CHAR8       *Buffer,
 | 
						|
  IN    UINTN              BufferLen,
 | 
						|
  IN    UINTN              Flags,
 | 
						|
  IN OUT EDKII_JSON_ERROR  *Error
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The reference count is used to track whether a value is still in use or not.
 | 
						|
  When a value is created, it's reference count is set to 1.
 | 
						|
  when the value is no longer needed, the reference count is decremented.
 | 
						|
  When the reference count drops to zero, there are no references left and the
 | 
						|
  value can be destroyed.
 | 
						|
 | 
						|
  This funciton decrement the reference count of EDKII_JSON_VALUE. As soon as
 | 
						|
  a call to json_decref() drops the reference count to zero, the value is
 | 
						|
  destroyed and it can no longer be used.
 | 
						|
 | 
						|
  @param[in]   JsonValue      JSON value
 | 
						|
**/
 | 
						|
VOID
 | 
						|
EFIAPI
 | 
						|
JsonDecreaseReference (
 | 
						|
  IN EDKII_JSON_VALUE JsonValue
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  The reference count is used to track whether a value is still in use or not.
 | 
						|
  When a value is created, it's reference count is set to 1.
 | 
						|
  If a reference to a value is kept (e.g. a value is stored somewhere for later use),
 | 
						|
  its reference count is incremented.
 | 
						|
 | 
						|
  This function increment the reference count of json if it's not NULL.
 | 
						|
  Returns EDKII_JSON_VALUE.
 | 
						|
 | 
						|
  @param[in]   JsonValue      JSON value
 | 
						|
  @retval      EDKII_JSON_VALUE of itself
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonIncreaseReference (
 | 
						|
  IN EDKII_JSON_VALUE JsonValue
 | 
						|
  );
 | 
						|
/**
 | 
						|
  Returns an opaque iterator which can be used to iterate over all key-value pairs
 | 
						|
  in object, or NULL if object is empty
 | 
						|
 | 
						|
  @param[in]   JsonValue      JSON value
 | 
						|
**/
 | 
						|
VOID *
 | 
						|
EFIAPI
 | 
						|
JsonObjectIterator (
 | 
						|
  IN EDKII_JSON_VALUE JsonValue
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  Extract the associated value from iterator.
 | 
						|
 | 
						|
  @param[in]   Iterator   Iterator pointer
 | 
						|
**/
 | 
						|
EDKII_JSON_VALUE
 | 
						|
EFIAPI
 | 
						|
JsonObjectIteratorValue (
 | 
						|
  IN VOID *Iterator
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  Returns an iterator pointing to the next key-value pair in object after iter,
 | 
						|
  or NULL if the whole object has been iterated through.
 | 
						|
 | 
						|
  @param[in]   JsonValue  JSON value
 | 
						|
  @param[in]   Iterator   Iterator pointer
 | 
						|
  @retval      Iterator pointer
 | 
						|
**/
 | 
						|
VOID *
 | 
						|
EFIAPI
 | 
						|
JsonObjectIteratorNext (
 | 
						|
  IN EDKII_JSON_VALUE JsonValue,
 | 
						|
  IN VOID             *Iterator
 | 
						|
  );
 | 
						|
 | 
						|
/**
 | 
						|
  Returns the key of iterator pointing
 | 
						|
 | 
						|
  @param[in]   Iterator   Iterator pointer
 | 
						|
  @retval      Key
 | 
						|
**/
 | 
						|
CHAR8 *
 | 
						|
EFIAPI
 | 
						|
JsonObjectIteratorKey (
 | 
						|
  IN VOID *Iterator
 | 
						|
);
 | 
						|
 | 
						|
/**
 | 
						|
  Returns the pointer of iterator by key.
 | 
						|
 | 
						|
  @param[in]   Key   The key of interator pointer.
 | 
						|
  @retval      Pointer to interator
 | 
						|
**/
 | 
						|
VOID *
 | 
						|
EFIAPI
 | 
						|
JsonObjectKeyToIterator (
 | 
						|
  IN CHAR8 *Key
 | 
						|
);
 | 
						|
 | 
						|
/**
 | 
						|
  Returns the json type of this json value
 | 
						|
 | 
						|
  @param[in]   JsonValue  JSON value
 | 
						|
  @retval      JSON type returned
 | 
						|
**/
 | 
						|
EDKII_JSON_TYPE
 | 
						|
EFIAPI
 | 
						|
JsonGetType(
 | 
						|
  IN EDKII_JSON_VALUE JsonValue
 | 
						|
  );
 | 
						|
#endif
 |