1/** @file
2  Support functions declaration for UEFI HTTP boot driver.
3
4Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
5This program and the accompanying materials are licensed and made available under
6the terms and conditions of the BSD License that accompanies this distribution.
7The full text of the license may be found at
8http://opensource.org/licenses/bsd-license.php.
9
10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13**/
14
15#ifndef __EFI_HTTP_BOOT_SUPPORT_H__
16#define __EFI_HTTP_BOOT_SUPPORT_H__
17
18/**
19  Get the Nic handle using any child handle in the IPv4 stack.
20
21  @param[in]  ControllerHandle    Pointer to child handle over IPv4.
22
23  @return NicHandle               The pointer to the Nic handle.
24  @return NULL                    Can't find the Nic handle.
25
26**/
27EFI_HANDLE
28HttpBootGetNicByIp4Children (
29  IN EFI_HANDLE                 ControllerHandle
30  );
31
32/**
33  Get the Nic handle using any child handle in the IPv6 stack.
34
35  @param[in]  ControllerHandle    Pointer to child handle over IPv6.
36
37  @return NicHandle               The pointer to the Nic handle.
38  @return NULL                    Can't find the Nic handle.
39
40**/
41EFI_HANDLE
42HttpBootGetNicByIp6Children (
43  IN EFI_HANDLE                 ControllerHandle
44  );
45
46/**
47  This function is to convert UINTN to ASCII string with the required formatting.
48
49  @param[in]  Number         Numeric value to be converted.
50  @param[in]  Buffer         The pointer to the buffer for ASCII string.
51  @param[in]  Length         The length of the required format.
52
53**/
54VOID
55HttpBootUintnToAscDecWithFormat (
56  IN UINTN                       Number,
57  IN UINT8                       *Buffer,
58  IN INTN                        Length
59  );
60
61
62/**
63  This function is to display the IPv4 address.
64
65  @param[in]  Ip        The pointer to the IPv4 address.
66
67**/
68VOID
69HttpBootShowIp4Addr (
70  IN EFI_IPv4_ADDRESS   *Ip
71  );
72
73/**
74  This function is to display the IPv6 address.
75
76  @param[in]  Ip        The pointer to the IPv6 address.
77
78**/
79VOID
80HttpBootShowIp6Addr (
81  IN EFI_IPv6_ADDRESS   *Ip
82  );
83
84//
85// A wrapper structure to hold the HTTP headers.
86//
87typedef struct {
88  UINTN                       MaxHeaderCount;
89  UINTN                       HeaderCount;
90  EFI_HTTP_HEADER             *Headers;
91} HTTP_IO_HEADER;
92
93/**
94  Create a HTTP_IO_HEADER to hold the HTTP header items.
95
96  @param[in]  MaxHeaderCount         The maximun number of HTTP header in this holder.
97
98  @return    A pointer of the HTTP header holder or NULL if failed.
99
100**/
101HTTP_IO_HEADER *
102HttpBootCreateHeader (
103  IN  UINTN                MaxHeaderCount
104  );
105
106/**
107  Destroy the HTTP_IO_HEADER and release the resouces.
108
109  @param[in]  HttpIoHeader       Point to the HTTP header holder to be destroyed.
110
111**/
112VOID
113HttpBootFreeHeader (
114  IN  HTTP_IO_HEADER       *HttpIoHeader
115  );
116
117/**
118  Set or update a HTTP header with the field name and corresponding value.
119
120  @param[in]  HttpIoHeader       Point to the HTTP header holder.
121  @param[in]  FieldName          Null terminated string which describes a field name.
122  @param[in]  FieldValue         Null terminated string which describes the corresponding field value.
123
124  @retval  EFI_SUCCESS           The HTTP header has been set or updated.
125  @retval  EFI_INVALID_PARAMETER Any input parameter is invalid.
126  @retval  EFI_OUT_OF_RESOURCES  Insufficient resource to complete the operation.
127  @retval  Other                 Unexpected error happened.
128
129**/
130EFI_STATUS
131HttpBootSetHeader (
132  IN  HTTP_IO_HEADER       *HttpIoHeader,
133  IN  CHAR8                *FieldName,
134  IN  CHAR8                *FieldValue
135  );
136
137//
138// HTTP_IO configuration data for IPv4
139//
140typedef struct {
141  EFI_HTTP_VERSION          HttpVersion;
142  UINT32                    RequestTimeOut;  // In milliseconds.
143  UINT32                    ResponseTimeOut; // In milliseconds.
144  BOOLEAN                   UseDefaultAddress;
145  EFI_IPv4_ADDRESS          LocalIp;
146  EFI_IPv4_ADDRESS          SubnetMask;
147  UINT16                    LocalPort;
148} HTTP4_IO_CONFIG_DATA;
149
150//
151// HTTP_IO configuration data for IPv6
152//
153typedef struct {
154  EFI_HTTP_VERSION          HttpVersion;
155  UINT32                    RequestTimeOut;  // In milliseconds.
156  BOOLEAN                   UseDefaultAddress;
157  EFI_IPv6_ADDRESS          LocalIp;
158  UINT16                    LocalPort;
159} HTTP6_IO_CONFIG_DATA;
160
161
162//
163// HTTP_IO configuration
164//
165typedef union {
166  HTTP4_IO_CONFIG_DATA       Config4;
167  HTTP6_IO_CONFIG_DATA       Config6;
168} HTTP_IO_CONFIG_DATA;
169
170//
171// HTTO_IO wrapper of the EFI HTTP service.
172//
173typedef struct {
174  UINT8                     IpVersion;
175  EFI_HANDLE                Image;
176  EFI_HANDLE                Controller;
177  EFI_HANDLE                Handle;
178
179  EFI_HTTP_PROTOCOL         *Http;
180
181  EFI_HTTP_TOKEN            ReqToken;
182  EFI_HTTP_MESSAGE          ReqMessage;
183  EFI_HTTP_TOKEN            RspToken;
184  EFI_HTTP_MESSAGE          RspMessage;
185
186  BOOLEAN                   IsTxDone;
187  BOOLEAN                   IsRxDone;
188} HTTP_IO;
189
190//
191// A wrapper structure to hold the received HTTP response data.
192//
193typedef struct {
194  EFI_HTTP_RESPONSE_DATA      Response;
195  UINTN                       HeaderCount;
196  EFI_HTTP_HEADER             *Headers;
197  UINTN                       BodyLength;
198  CHAR8                       *Body;
199} HTTP_IO_RESOPNSE_DATA;
200
201/**
202  Retrieve the host address using the EFI_DNS6_PROTOCOL.
203
204  @param[in]  Private             The pointer to the driver's private data.
205  @param[in]  HostName            Pointer to buffer containing hostname.
206  @param[out] IpAddress           On output, pointer to buffer containing IPv6 address.
207
208  @retval EFI_SUCCESS             Operation succeeded.
209  @retval EFI_DEVICE_ERROR        An unexpected network error occurred.
210  @retval Others                  Other errors as indicated.
211**/
212EFI_STATUS
213HttpBootDns (
214  IN     HTTP_BOOT_PRIVATE_DATA   *Private,
215  IN     CHAR16                   *HostName,
216     OUT EFI_IPv6_ADDRESS         *IpAddress
217  );
218
219/**
220  Notify the callback function when an event is triggered.
221
222  @param[in]  Event           The triggered event.
223  @param[in]  Context         The opaque parameter to the function.
224
225**/
226VOID
227EFIAPI
228HttpBootCommonNotify (
229  IN EFI_EVENT           Event,
230  IN VOID                *Context
231  );
232
233/**
234  Create a HTTP_IO to access the HTTP service. It will create and configure
235  a HTTP child handle.
236
237  @param[in]  Image          The handle of the driver image.
238  @param[in]  Controller     The handle of the controller.
239  @param[in]  IpVersion      IP_VERSION_4 or IP_VERSION_6.
240  @param[in]  ConfigData     The HTTP_IO configuration data.
241  @param[out] HttpIo         The HTTP_IO.
242
243  @retval EFI_SUCCESS            The HTTP_IO is created and configured.
244  @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
245  @retval EFI_UNSUPPORTED        One or more of the control options are not
246                                 supported in the implementation.
247  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
248  @retval Others                 Failed to create the HTTP_IO or configure it.
249
250**/
251EFI_STATUS
252HttpIoCreateIo (
253  IN EFI_HANDLE             Image,
254  IN EFI_HANDLE             Controller,
255  IN UINT8                  IpVersion,
256  IN HTTP_IO_CONFIG_DATA    *ConfigData,
257  OUT HTTP_IO               *HttpIo
258  );
259
260/**
261  Destroy the HTTP_IO and release the resouces.
262
263  @param[in]  HttpIo          The HTTP_IO which wraps the HTTP service to be destroyed.
264
265**/
266VOID
267HttpIoDestroyIo (
268  IN HTTP_IO                *HttpIo
269  );
270
271/**
272  Synchronously send a HTTP REQUEST message to the server.
273
274  @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
275  @param[in]   Request          A pointer to storage such data as URL and HTTP method.
276  @param[in]   HeaderCount      Number of HTTP header structures in Headers list.
277  @param[in]   Headers          Array containing list of HTTP headers.
278  @param[in]   BodyLength       Length in bytes of the HTTP body.
279  @param[in]   Body             Body associated with the HTTP request.
280
281  @retval EFI_SUCCESS            The HTTP request is trasmitted.
282  @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
283  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
284  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
285  @retval Others                 Other errors as indicated.
286
287**/
288EFI_STATUS
289HttpIoSendRequest (
290  IN  HTTP_IO                *HttpIo,
291  IN  EFI_HTTP_REQUEST_DATA  *Request,      OPTIONAL
292  IN  UINTN                  HeaderCount,
293  IN  EFI_HTTP_HEADER        *Headers,      OPTIONAL
294  IN  UINTN                  BodyLength,
295  IN  VOID                   *Body          OPTIONAL
296  );
297
298/**
299  Synchronously receive a HTTP RESPONSE message from the server.
300
301  @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
302  @param[in]   RecvMsgHeader    TRUE to receive a new HTTP response (from message header).
303                                FALSE to continue receive the previous response message.
304  @param[out]  ResponseData     Point to a wrapper of the received response data.
305
306  @retval EFI_SUCCESS            The HTTP resopnse is received.
307  @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
308  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
309  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
310  @retval Others                 Other errors as indicated.
311
312**/
313EFI_STATUS
314HttpIoRecvResponse (
315  IN      HTTP_IO                  *HttpIo,
316  IN      BOOLEAN                  RecvMsgHeader,
317     OUT  HTTP_IO_RESOPNSE_DATA    *ResponseData
318  );
319
320#endif
321