MdePkg/Include: Definitions of EFI REST JSON Structure Protocol

Add definitions of EFI REST JSON Structure according to UEFI spec
2.8 Section 29.7.3 EFI REST JSON Resource to C Structure Converter.

Signed-off-by: Abner Chang <abner.chang@hpe.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Liming Gao <gaoliming@byosoft.com.cn>
Cc: Zhiguang Liu <zhiguang.liu@intel.com>
Cc: Jiaxin Wu <jiaxin.wu@intel.com>
Cc: Siyuan Fu <siyuan.fu@intel.com>
Cc: Fan Wang <fan.wang@intel.com>
Cc: Jiewen Yao <jiewen.yao@intel.com>
Cc: Nickle Wang <nickle.wang@hpe.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>

diff --git a/MdePkg/Include/Protocol/RestJsonStructure.h b/MdePkg/Include/Protocol/RestJsonStructure.h
new file mode 100644 (file)
index 0000000..c9e9a35
--- /dev/null
+++ b/MdePkg/Include/Protocol/RestJsonStructure.h
@@ -0,0 +1,161 @@
+/** @file\r
+  This file defines the EFI REST JSON Structure Protocol interface.\r
+\r
+  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>\r
+\r
+  SPDX-License-Identifier: BSD-2-Clause-Patent\r
+\r
+  @par Revision Reference:\r
+  This Protocol is introduced in UEFI Specification 2.8\r
+\r
+**/\r
+\r
+#ifndef EFI_REST_JSON_STRUCTURE_PROTOCOL_H_\r
+#define EFI_REST_JSON_STRUCTURE_PROTOCOL_H_\r
+\r
+///\r
+/// GUID definitions\r
+///\r
+#define EFI_REST_JSON_STRUCTURE_PROTOCOL_GUID \\r
+  { \\r
+    0xa9a048f6, 0x48a0, 0x4714, {0xb7, 0xda, 0xa9, 0xad,0x87, 0xd4, 0xda, 0xc9 } \\r
+  }\r
+\r
+typedef struct _EFI_REST_JSON_STRUCTURE_PROTOCOL EFI_REST_JSON_STRUCTURE_PROTOCOL;\r
+typedef CHAR8 * EFI_REST_JSON_RESOURCE_TYPE_DATATYPE;\r
+\r
+///\r
+/// Structure defintions of resource name space.\r
+///\r
+/// The fields declared in this structure define the\r
+/// name and revision of payload delievered throught\r
+/// REST API.\r
+///\r
+typedef struct _EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE {\r
+  CHAR8 *ResourceTypeName;   ///< Resource type name\r
+  CHAR8 *MajorVersion;       ///< Resource major version\r
+  CHAR8 *MinorVersion;       ///< Resource minor version\r
+  CHAR8 *ErrataVersion;      ///< Resource errata version\r
+} EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE;\r
+\r
+///\r
+/// REST resource type identifier\r
+///\r
+/// REST resource type consists of name space and data type.\r
+///\r
+typedef struct _EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER {\r
+  EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE NameSpace; ///< Namespace of this resource type.\r
+  EFI_REST_JSON_RESOURCE_TYPE_DATATYPE DataType;   ///< Name of data type declared in this\r
+                                                   ///< resource type.\r
+} EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER;\r
+\r
+///\r
+/// List of JSON to C structure conversions which this convertor supports.\r
+///\r
+typedef struct _EFI_REST_JSON_STRUCTURE_SUPPORTED {\r
+  LIST_ENTRY NextSupportedRsrcInterp;                        ///< Linklist to next supported conversion.\r
+  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER RestResourceInterp; ///< JSON resource type this convertor supports.\r
+} EFI_REST_JSON_STRUCTURE_SUPPORTED;\r
+\r
+///\r
+/// The header file of JSON C structure\r
+///\r
+typedef struct _EFI_REST_JSON_STRUCTURE_HEADER {\r
+  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER    JsonRsrcIdentifier; ///< Resource identifier which use to\r
+                                                                ///< choice the proper interpreter.\r
+  ///< Follow by a pointer points to JSON structure, the content in the\r
+  ///< JSON structure is implementation-specific according to converter producer.\r
+  VOID  *JsonStructurePointer;\r
+} EFI_REST_JSON_STRUCTURE_HEADER;\r
+\r
+/**\r
+  JSON-IN C Structure-OUT function. Convert the given REST JSON resource into structure.\r
+\r
+  @param[in]    This                This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.\r
+  @param[in]    JsonRsrcIdentifier  This indicates the resource type and version is given in\r
+                                    ResourceJsonText.\r
+  @param[in]    ResourceJsonText    REST JSON resource in text format.\r
+  @param[out]   JsonStructure       Pointer to receive the pointer to EFI_REST_JSON_STRUCTURE_HEADER\r
+\r
+  @retval EFI_SUCCESS\r
+  @retval Others\r
+--*/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_REST_JSON_STRUCTURE_TO_STRUCTURE)(\r
+  IN  EFI_REST_JSON_STRUCTURE_PROTOCOL        *This,\r
+  IN  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER *JsonRsrcIdentifier OPTIONAL,\r
+  IN  CHAR8                                   *ResourceJsonText,\r
+  OUT  EFI_REST_JSON_STRUCTURE_HEADER         **JsonStructure\r
+);\r
+\r
+/**\r
+  Convert the given REST JSON structure into JSON text.\r
+\r
+  @param[in]    This                 This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.\r
+  @param[in]    JsonStructureHeader  The point to EFI_REST_JSON_STRUCTURE_HEADER  structure.\r
+  @param[out]   ResourceJsonText     Pointer to receive REST JSON resource in text format.\r
+\r
+  @retval EFI_SUCCESS\r
+  @retval Others\r
+\r
+--*/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_REST_JSON_STRUCTURE_TO_JSON)(\r
+  IN EFI_REST_JSON_STRUCTURE_PROTOCOL     *This,\r
+  IN EFI_REST_JSON_STRUCTURE_HEADER       *JsonStructureHeader,\r
+  OUT CHAR8                               **ResourceJsonText\r
+);\r
+\r
+/**\r
+  This function destroys the REST JSON structure.\r
+\r
+  @param[in]    This                 This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.\r
+  @param[in]    JsonStructureHeader  JSON structure to destroy.\r
+\r
+  @retval EFI_SUCCESS\r
+  @retval Others\r
+\r
+--*/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE)(\r
+  IN EFI_REST_JSON_STRUCTURE_PROTOCOL   *This,\r
+  IN EFI_REST_JSON_STRUCTURE_HEADER     *JsonStructureHeader\r
+);\r
+/**\r
+  This function provides REST JSON resource to structure converter registration.\r
+\r
+  @param[in]    This                     This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.\r
+  @param[in]    JsonStructureSupported   The type and version of REST JSON resource which this converter\r
+                                         supports.\r
+  @param[in]    ToStructure              The function to convert REST JSON resource to structure.\r
+  @param[in]    ToJson                   The function to convert REST JSON structure to JSON in text format.\r
+  @param[out]    DestroyStructure         Destroy REST JSON structure returned in ToStructure() function.\r
+\r
+  @retval EFI_SUCCESS             Register successfully.\r
+  @retval Others                  Fail to register.\r
+\r
+--*/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_REST_JSON_STRUCTURE_REGISTER)(\r
+  IN EFI_REST_JSON_STRUCTURE_PROTOCOL       *This,\r
+  IN EFI_REST_JSON_STRUCTURE_SUPPORTED      *JsonStructureSupported,\r
+  IN EFI_REST_JSON_STRUCTURE_TO_STRUCTURE   ToStructure,\r
+  IN EFI_REST_JSON_STRUCTURE_TO_JSON        ToJson,\r
+  IN EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE DestroyStructure\r
+);\r
+\r
+///\r
+/// EFI REST JSON to C structure protocol definition.\r
+///\r
+struct _EFI_REST_JSON_STRUCTURE_PROTOCOL {\r
+  EFI_REST_JSON_STRUCTURE_REGISTER           Register;          ///< Register JSON to C structure convertor\r
+  EFI_REST_JSON_STRUCTURE_TO_STRUCTURE       ToStructure;       ///< The function to convert JSON to C structure\r
+  EFI_REST_JSON_STRUCTURE_TO_JSON            ToJson;            ///< The function to convert C structure to JSON\r
+  EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE  DestoryStructure;  ///< Destory C structure.\r
+};\r
+\r
+#endif\r

diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec
index 5205374d62415d0cb3baebd5e1d1d3119f73bd84..645f61b80e80d9f0e6f1ca6709e14ff2235aaeef 100644 (file)
--- a/MdePkg/MdePkg.dec
+++ b/MdePkg/MdePkg.dec
@@ -1855,6 +1855,9 @@
   gEfiRestExProtocolGuid               = { 0x55648b91, 0xe7d, 0x40a3, { 0xa9, 0xb3, 0xa8, 0x15, 0xd7, 0xea, 0xdf, 0x97 }}\r
   gEfiRestExServiceBindingProtocolGuid = { 0x456bbe01, 0x99d0, 0x45ea, { 0xbb, 0x5f, 0x16, 0xd8, 0x4b, 0xed, 0xc5, 0x59 }}\r
 \r
+  ## Include/Protocol/RestJsonStructure.h\r
+  gEfiRestJsonStructureProtocolGuid  = { 0xa9a048f6, 0x48a0, 0x4714, {0xb7, 0xda, 0xa9, 0xad,0x87, 0xd4, 0xda, 0xc9 }}\r
+\r
   #\r
   # Protocols defined in Shell2.0\r
   #\r