summaryrefslogtreecommitdiffstats
path: root/MdePkg/Include/Protocol/RestJsonStructure.h
blob: 29d69d62529b2f9fd2208dc8bf00e621f5e34af1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
/** @file
  This file defines the EFI REST JSON Structure Protocol interface.

  (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>

  SPDX-License-Identifier: BSD-2-Clause-Patent

  @par Revision Reference:
  This Protocol is introduced in UEFI Specification 2.8

**/

#ifndef EFI_REST_JSON_STRUCTURE_PROTOCOL_H_
#define EFI_REST_JSON_STRUCTURE_PROTOCOL_H_

///
/// GUID definitions
///
#define EFI_REST_JSON_STRUCTURE_PROTOCOL_GUID \
  { \
    0xa9a048f6, 0x48a0, 0x4714, {0xb7, 0xda, 0xa9, 0xad,0x87, 0xd4, 0xda, 0xc9 } \
  }

typedef struct _EFI_REST_JSON_STRUCTURE_PROTOCOL  EFI_REST_JSON_STRUCTURE_PROTOCOL;
typedef CHAR8                                     *EFI_REST_JSON_RESOURCE_TYPE_DATATYPE;

///
/// Structure defintions of resource name space.
///
/// The fields declared in this structure define the
/// name and revision of payload delievered throught
/// REST API.
///
typedef struct _EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE {
  CHAR8    *ResourceTypeName; ///< Resource type name
  CHAR8    *MajorVersion;     ///< Resource major version
  CHAR8    *MinorVersion;     ///< Resource minor version
  CHAR8    *ErrataVersion;    ///< Resource errata version
} EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE;

///
/// REST resource type identifier
///
/// REST resource type consists of name space and data type.
///
typedef struct _EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER {
  EFI_REST_JSON_RESOURCE_TYPE_NAMESPACE    NameSpace; ///< Namespace of this resource type.
  EFI_REST_JSON_RESOURCE_TYPE_DATATYPE     DataType;  ///< Name of data type declared in this
                                                      ///< resource type.
} EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER;

///
/// List of JSON to C structure conversions which this convertor supports.
///
typedef struct _EFI_REST_JSON_STRUCTURE_SUPPORTED {
  LIST_ENTRY                                NextSupportedRsrcInterp; ///< Linklist to next supported conversion.
  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER    RestResourceInterp;      ///< JSON resource type this convertor supports.
} EFI_REST_JSON_STRUCTURE_SUPPORTED;

///
/// The header file of JSON C structure
///
typedef struct _EFI_REST_JSON_STRUCTURE_HEADER {
  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER    JsonRsrcIdentifier; ///< Resource identifier which use to
                                                                ///< choice the proper interpreter.
  ///< Follow by a pointer points to JSON structure, the content in the
  ///< JSON structure is implementation-specific according to converter producer.
  VOID                                      *JsonStructurePointer;
} EFI_REST_JSON_STRUCTURE_HEADER;

/**
  JSON-IN C Structure-OUT function. Convert the given REST JSON resource into structure.

  @param[in]    This                This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
  @param[in]    JsonRsrcIdentifier  This indicates the resource type and version is given in
                                    ResourceJsonText.
  @param[in]    ResourceJsonText    REST JSON resource in text format.
  @param[out]   JsonStructure       Pointer to receive the pointer to EFI_REST_JSON_STRUCTURE_HEADER

  @retval EFI_SUCCESS
  @retval Others
--*/
typedef
EFI_STATUS
(EFIAPI *EFI_REST_JSON_STRUCTURE_TO_STRUCTURE)(
  IN  EFI_REST_JSON_STRUCTURE_PROTOCOL        *This,
  IN  EFI_REST_JSON_RESOURCE_TYPE_IDENTIFIER *JsonRsrcIdentifier OPTIONAL,
  IN  CHAR8                                   *ResourceJsonText,
  OUT  EFI_REST_JSON_STRUCTURE_HEADER         **JsonStructure
  );

/**
  Convert the given REST JSON structure into JSON text.

  @param[in]    This                 This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
  @param[in]    JsonStructureHeader  The point to EFI_REST_JSON_STRUCTURE_HEADER  structure.
  @param[out]   ResourceJsonText     Pointer to receive REST JSON resource in text format.

  @retval EFI_SUCCESS
  @retval Others

--*/
typedef
EFI_STATUS
(EFIAPI *EFI_REST_JSON_STRUCTURE_TO_JSON)(
  IN EFI_REST_JSON_STRUCTURE_PROTOCOL     *This,
  IN EFI_REST_JSON_STRUCTURE_HEADER       *JsonStructureHeader,
  OUT CHAR8                               **ResourceJsonText
  );

/**
  This function destroys the REST JSON structure.

  @param[in]    This                 This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
  @param[in]    JsonStructureHeader  JSON structure to destroy.

  @retval EFI_SUCCESS
  @retval Others

--*/
typedef
EFI_STATUS
(EFIAPI *EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE)(
  IN EFI_REST_JSON_STRUCTURE_PROTOCOL   *This,
  IN EFI_REST_JSON_STRUCTURE_HEADER     *JsonStructureHeader
  );

/**
  This function provides REST JSON resource to structure converter registration.

  @param[in]    This                     This is the EFI_REST_JSON_STRUCTURE_PROTOCOL instance.
  @param[in]    JsonStructureSupported   The type and version of REST JSON resource which this converter
                                         supports.
  @param[in]    ToStructure              The function to convert REST JSON resource to structure.
  @param[in]    ToJson                   The function to convert REST JSON structure to JSON in text format.
  @param[in]    DestroyStructure         Destroy REST JSON structure returned in ToStructure() function.

  @retval EFI_SUCCESS             Register successfully.
  @retval Others                  Fail to register.

--*/
typedef
EFI_STATUS
(EFIAPI *EFI_REST_JSON_STRUCTURE_REGISTER)(
  IN EFI_REST_JSON_STRUCTURE_PROTOCOL       *This,
  IN EFI_REST_JSON_STRUCTURE_SUPPORTED      *JsonStructureSupported,
  IN EFI_REST_JSON_STRUCTURE_TO_STRUCTURE   ToStructure,
  IN EFI_REST_JSON_STRUCTURE_TO_JSON        ToJson,
  IN EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE DestroyStructure
  );

///
/// EFI REST JSON to C structure protocol definition.
///
struct _EFI_REST_JSON_STRUCTURE_PROTOCOL {
  EFI_REST_JSON_STRUCTURE_REGISTER             Register;         ///< Register JSON to C structure convertor
  EFI_REST_JSON_STRUCTURE_TO_STRUCTURE         ToStructure;      ///< The function to convert JSON to C structure
  EFI_REST_JSON_STRUCTURE_TO_JSON              ToJson;           ///< The function to convert C structure to JSON
  EFI_REST_JSON_STRUCTURE_DESTORY_STRUCTURE    DestoryStructure; ///< Destory C structure.
};

#endif