MdePkg/Include/Protocol/RestJsonStructure.h

   1 /** @file
   2   This file defines the EFI REST JSON Structure Protocol interface.
   3
   4   (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8   @par Revision Reference:
   9   This Protocol is introduced in UEFI Specification 2.8
  10
  11 **/
  12
  13 #ifndef EFI_REST_JSON_STRUCTURE_PROTOCOL_H_
  14 #define EFI_REST_JSON_STRUCTURE_PROTOCOL_H_
  15
  16 ///
  17 /// GUID definitions
  18 ///
  19 #define EFI_REST_JSON_STRUCTURE_PROTOCOL_GUID \
  20   { \
  21     0xa9a048f6, 0x48a0, 0x4714, {0xb7, 0xda, 0xa9, 0xad,0x87, 0xd4, 0xda, 0xc9 } \
  22   }
  23
  24 typedef struct _EFI_REST_JSON_STRUCTURE_PROTOCOL EFI_REST_JSON_STRUCTURE_PROTOCOL;
  25 typedef CHAR8 * EFI_REST_JSON_RESOURCE_TYPE_DATATYPE;
  26
  27 ///
  28 /// Structure defintions of resource name space.
  29 ///
  30 /// The fields declared in this structure define the
  31 /// name and revision of payload delievered throught
  32 /// REST API.
  33 ///
  34 typedef struct _EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE {
  35   CHAR8 *ResourceTypeName;   ///< Resource type name
  36   CHAR8 *MajorVersion;       ///< Resource major version
  37   CHAR8 *MinorVersion;       ///< Resource minor version
  38   CHAR8 *ErrataVersion;      ///< Resource errata version
  39 } EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE;
  40
  41 ///
  42 /// REST resource type identifier
  43 ///
  44 /// REST resource type consists of name space and data type.
  45 ///
  46 typedef struct _EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER {
  47   EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE NameSpace; ///< Namespace of this resource type.
  48   EFI_REST_JSON_RESOURCE_TYPE_DATATYPE DataType;   ///< Name of data type declared in this
  49                                                    ///< resource type.
  50 } EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER;
  51
  52 ///
  53 /// List of JSON to C structure conversions which this convertor supports.
  54 ///
  55 typedef struct _EFI_REST_JSON_STRUCTURE_SUPPORTED {
  56   LIST_ENTRY NextSupportedRsrcInterp;                        ///< Linklist to next supported conversion.
  57   EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER RestResourceInterp; ///< JSON resource type this convertor supports.
  58 } EFI_REST_JSON_STRUCTURE_SUPPORTED;
  59
  60 ///
  61 /// The header file of JSON C structure
  62 ///
  63 typedef struct _EFI_REST_JSON_STRUCTURE_HEADER {
  64   EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER    JsonRsrcIdentifier; ///< Resource identifier which use to
  65                                                                 ///< choice the proper interpreter.
  66   ///< Follow by a pointer points to JSON structure, the content in the
  67   ///< JSON structure is implementation-specific according to converter producer.
  68   VOID  *JsonStructurePointer;
  69 } EFI_REST_JSON_STRUCTURE_HEADER;
  70
  71 /**
  72   JSON-IN C Structure-OUT function. Convert the given REST JSON resource into structure.
  73
  74   @param[in]    This                This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
  75   @param[in]    JsonRsrcIdentifier  This indicates the resource type and version is given in
  76                                     ResourceJsonText.
  77   @param[in]    ResourceJsonText    REST JSON resource in text format.
  78   @param[out]   JsonStructure       Pointer to receive the pointer to EFI_REST_JSON_STRUCTURE_HEADER
  79
  80   @retval EFI_SUCCESS
  81   @retval Others
  82 --*/
  83 typedef
  84 EFI_STATUS
  85 (EFIAPI *EFI_REST_JSON_STRUCTURE_TO_STRUCTURE)(
  86   IN  EFI_REST_JSON_STRUCTURE_PROTOCOL        *This,
  87   IN  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER *JsonRsrcIdentifier OPTIONAL,
  88   IN  CHAR8                                   *ResourceJsonText,
  89   OUT  EFI_REST_JSON_STRUCTURE_HEADER         **JsonStructure
  90 );
  91
  92 /**
  93   Convert the given REST JSON structure into JSON text.
  94
  95   @param[in]    This                 This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
  96   @param[in]    JsonStructureHeader  The point to EFI_REST_JSON_STRUCTURE_HEADER  structure.
  97   @param[out]   ResourceJsonText     Pointer to receive REST JSON resource in text format.
  98
  99   @retval EFI_SUCCESS
 100   @retval Others
 101
 102 --*/
 103 typedef
 104 EFI_STATUS
 105 (EFIAPI *EFI_REST_JSON_STRUCTURE_TO_JSON)(
 106   IN EFI_REST_JSON_STRUCTURE_PROTOCOL     *This,
 107   IN EFI_REST_JSON_STRUCTURE_HEADER       *JsonStructureHeader,
 108   OUT CHAR8                               **ResourceJsonText
 109 );
 110
 111 /**
 112   This function destroys the REST JSON structure.
 113
 114   @param[in]    This                 This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
 115   @param[in]    JsonStructureHeader  JSON structure to destroy.
 116
 117   @retval EFI_SUCCESS
 118   @retval Others
 119
 120 --*/
 121 typedef
 122 EFI_STATUS
 123 (EFIAPI *EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE)(
 124   IN EFI_REST_JSON_STRUCTURE_PROTOCOL   *This,
 125   IN EFI_REST_JSON_STRUCTURE_HEADER     *JsonStructureHeader
 126 );
 127 /**
 128   This function provides REST JSON resource to structure converter registration.
 129
 130   @param[in]    This                     This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
 131   @param[in]    JsonStructureSupported   The type and version of REST JSON resource which this converter
 132                                          supports.
 133   @param[in]    ToStructure              The function to convert REST JSON resource to structure.
 134   @param[in]    ToJson                   The function to convert REST JSON structure to JSON in text format.
 135   @param[in]    DestroyStructure         Destroy REST JSON structure returned in ToStructure() function.
 136
 137   @retval EFI_SUCCESS             Register successfully.
 138   @retval Others                  Fail to register.
 139
 140 --*/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_REST_JSON_STRUCTURE_REGISTER)(
 144   IN EFI_REST_JSON_STRUCTURE_PROTOCOL       *This,
 145   IN EFI_REST_JSON_STRUCTURE_SUPPORTED      *JsonStructureSupported,
 146   IN EFI_REST_JSON_STRUCTURE_TO_STRUCTURE   ToStructure,
 147   IN EFI_REST_JSON_STRUCTURE_TO_JSON        ToJson,
 148   IN EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE DestroyStructure
 149 );
 150
 151 ///
 152 /// EFI REST JSON to C structure protocol definition.
 153 ///
 154 struct _EFI_REST_JSON_STRUCTURE_PROTOCOL {
 155   EFI_REST_JSON_STRUCTURE_REGISTER           Register;          ///< Register JSON to C structure convertor
 156   EFI_REST_JSON_STRUCTURE_TO_STRUCTURE       ToStructure;       ///< The function to convert JSON to C structure
 157   EFI_REST_JSON_STRUCTURE_TO_JSON            ToJson;            ///< The function to convert C structure to JSON
 158   EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE  DestoryStructure;  ///< Destory C structure.
 159 };
 160
 161 #endif