[mirror_edk2.git] / MdePkg / Include / Protocol / RestJsonStructure.h

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