NetworkPkg/HttpBootDxe: Add HTTP Boot Callback protocol support.
[mirror_edk2.git] / NetworkPkg / HttpBootDxe / HttpBootSupport.h
1 /** @file
2 Support functions declaration for UEFI HTTP boot driver.
3
4 Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT 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 **/
27 EFI_HANDLE
28 HttpBootGetNicByIp4Children (
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 **/
41 EFI_HANDLE
42 HttpBootGetNicByIp6Children (
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 **/
54 VOID
55 HttpBootUintnToAscDecWithFormat (
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 **/
68 VOID
69 HttpBootShowIp4Addr (
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 **/
79 VOID
80 HttpBootShowIp6Addr (
81 IN EFI_IPv6_ADDRESS *Ip
82 );
83
84 /**
85 This function is to display the HTTP error status.
86
87 @param[in] StatusCode The status code value in HTTP message.
88
89 **/
90 VOID
91 HttpBootPrintErrorMessage (
92 EFI_HTTP_STATUS_CODE StatusCode
93 );
94
95 //
96 // A wrapper structure to hold the HTTP headers.
97 //
98 typedef struct {
99 UINTN MaxHeaderCount;
100 UINTN HeaderCount;
101 EFI_HTTP_HEADER *Headers;
102 } HTTP_IO_HEADER;
103
104 /**
105 Create a HTTP_IO_HEADER to hold the HTTP header items.
106
107 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder.
108
109 @return A pointer of the HTTP header holder or NULL if failed.
110
111 **/
112 HTTP_IO_HEADER *
113 HttpBootCreateHeader (
114 IN UINTN MaxHeaderCount
115 );
116
117 /**
118 Destroy the HTTP_IO_HEADER and release the resouces.
119
120 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed.
121
122 **/
123 VOID
124 HttpBootFreeHeader (
125 IN HTTP_IO_HEADER *HttpIoHeader
126 );
127
128 /**
129 Set or update a HTTP header with the field name and corresponding value.
130
131 @param[in] HttpIoHeader Point to the HTTP header holder.
132 @param[in] FieldName Null terminated string which describes a field name.
133 @param[in] FieldValue Null terminated string which describes the corresponding field value.
134
135 @retval EFI_SUCCESS The HTTP header has been set or updated.
136 @retval EFI_INVALID_PARAMETER Any input parameter is invalid.
137 @retval EFI_OUT_OF_RESOURCES Insufficient resource to complete the operation.
138 @retval Other Unexpected error happened.
139
140 **/
141 EFI_STATUS
142 HttpBootSetHeader (
143 IN HTTP_IO_HEADER *HttpIoHeader,
144 IN CHAR8 *FieldName,
145 IN CHAR8 *FieldValue
146 );
147
148 ///
149 /// HTTP_IO_CALLBACK_EVENT
150 ///
151 typedef enum {
152 HttpIoRequest,
153 HttpIoResponse
154 } HTTP_IO_CALLBACK_EVENT;
155
156 /**
157 HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
158
159 @param[in] EventType Indicate the Event type that occurs in the current callback.
160 @param[in] Message HTTP message which will be send to, or just received from HTTP server.
161 @param[in] Context The Callback Context pointer.
162
163 @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process.
164 @retval Others Tells the HttpIo to abort the current HTTP process.
165 **/
166 typedef
167 EFI_STATUS
168 (EFIAPI * HTTP_IO_CALLBACK) (
169 IN HTTP_IO_CALLBACK_EVENT EventType,
170 IN EFI_HTTP_MESSAGE *Message,
171 IN VOID *Context
172 );
173
174 //
175 // HTTP_IO configuration data for IPv4
176 //
177 typedef struct {
178 EFI_HTTP_VERSION HttpVersion;
179 UINT32 RequestTimeOut; // In milliseconds.
180 UINT32 ResponseTimeOut; // In milliseconds.
181 BOOLEAN UseDefaultAddress;
182 EFI_IPv4_ADDRESS LocalIp;
183 EFI_IPv4_ADDRESS SubnetMask;
184 UINT16 LocalPort;
185 } HTTP4_IO_CONFIG_DATA;
186
187 //
188 // HTTP_IO configuration data for IPv6
189 //
190 typedef struct {
191 EFI_HTTP_VERSION HttpVersion;
192 UINT32 RequestTimeOut; // In milliseconds.
193 BOOLEAN UseDefaultAddress;
194 EFI_IPv6_ADDRESS LocalIp;
195 UINT16 LocalPort;
196 } HTTP6_IO_CONFIG_DATA;
197
198
199 //
200 // HTTP_IO configuration
201 //
202 typedef union {
203 HTTP4_IO_CONFIG_DATA Config4;
204 HTTP6_IO_CONFIG_DATA Config6;
205 } HTTP_IO_CONFIG_DATA;
206
207 //
208 // HTTP_IO wrapper of the EFI HTTP service.
209 //
210 typedef struct {
211 UINT8 IpVersion;
212 EFI_HANDLE Image;
213 EFI_HANDLE Controller;
214 EFI_HANDLE Handle;
215
216 EFI_HTTP_PROTOCOL *Http;
217
218 HTTP_IO_CALLBACK Callback;
219 VOID *Context;
220
221 EFI_HTTP_TOKEN ReqToken;
222 EFI_HTTP_MESSAGE ReqMessage;
223 EFI_HTTP_TOKEN RspToken;
224 EFI_HTTP_MESSAGE RspMessage;
225
226 BOOLEAN IsTxDone;
227 BOOLEAN IsRxDone;
228
229 EFI_EVENT TimeoutEvent;
230 } HTTP_IO;
231
232 //
233 // A wrapper structure to hold the received HTTP response data.
234 //
235 typedef struct {
236 EFI_HTTP_RESPONSE_DATA Response;
237 UINTN HeaderCount;
238 EFI_HTTP_HEADER *Headers;
239 UINTN BodyLength;
240 CHAR8 *Body;
241 EFI_STATUS Status;
242 } HTTP_IO_RESPONSE_DATA;
243
244 /**
245 Retrieve the host address using the EFI_DNS6_PROTOCOL.
246
247 @param[in] Private The pointer to the driver's private data.
248 @param[in] HostName Pointer to buffer containing hostname.
249 @param[out] IpAddress On output, pointer to buffer containing IPv6 address.
250
251 @retval EFI_SUCCESS Operation succeeded.
252 @retval EFI_DEVICE_ERROR An unexpected network error occurred.
253 @retval Others Other errors as indicated.
254 **/
255 EFI_STATUS
256 HttpBootDns (
257 IN HTTP_BOOT_PRIVATE_DATA *Private,
258 IN CHAR16 *HostName,
259 OUT EFI_IPv6_ADDRESS *IpAddress
260 );
261
262 /**
263 Notify the callback function when an event is triggered.
264
265 @param[in] Event The triggered event.
266 @param[in] Context The opaque parameter to the function.
267
268 **/
269 VOID
270 EFIAPI
271 HttpBootCommonNotify (
272 IN EFI_EVENT Event,
273 IN VOID *Context
274 );
275
276 /**
277 Create a HTTP_IO to access the HTTP service. It will create and configure
278 a HTTP child handle.
279
280 @param[in] Image The handle of the driver image.
281 @param[in] Controller The handle of the controller.
282 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
283 @param[in] ConfigData The HTTP_IO configuration data.
284 @param[in] Callback Callback function which will be invoked when specified
285 HTTP_IO_CALLBACK_EVENT happened.
286 @param[in] Context The Context data which will be passed to the Callback function.
287 @param[out] HttpIo The HTTP_IO.
288
289 @retval EFI_SUCCESS The HTTP_IO is created and configured.
290 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
291 @retval EFI_UNSUPPORTED One or more of the control options are not
292 supported in the implementation.
293 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
294 @retval Others Failed to create the HTTP_IO or configure it.
295
296 **/
297 EFI_STATUS
298 HttpIoCreateIo (
299 IN EFI_HANDLE Image,
300 IN EFI_HANDLE Controller,
301 IN UINT8 IpVersion,
302 IN HTTP_IO_CONFIG_DATA *ConfigData,
303 IN HTTP_IO_CALLBACK Callback,
304 IN VOID *Context,
305 OUT HTTP_IO *HttpIo
306 );
307
308 /**
309 Destroy the HTTP_IO and release the resouces.
310
311 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
312
313 **/
314 VOID
315 HttpIoDestroyIo (
316 IN HTTP_IO *HttpIo
317 );
318
319 /**
320 Synchronously send a HTTP REQUEST message to the server.
321
322 @param[in] HttpIo The HttpIo wrapping the HTTP service.
323 @param[in] Request A pointer to storage such data as URL and HTTP method.
324 @param[in] HeaderCount Number of HTTP header structures in Headers list.
325 @param[in] Headers Array containing list of HTTP headers.
326 @param[in] BodyLength Length in bytes of the HTTP body.
327 @param[in] Body Body associated with the HTTP request.
328
329 @retval EFI_SUCCESS The HTTP request is trasmitted.
330 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
331 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
332 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
333 @retval Others Other errors as indicated.
334
335 **/
336 EFI_STATUS
337 HttpIoSendRequest (
338 IN HTTP_IO *HttpIo,
339 IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL
340 IN UINTN HeaderCount,
341 IN EFI_HTTP_HEADER *Headers, OPTIONAL
342 IN UINTN BodyLength,
343 IN VOID *Body OPTIONAL
344 );
345
346 /**
347 Synchronously receive a HTTP RESPONSE message from the server.
348
349 @param[in] HttpIo The HttpIo wrapping the HTTP service.
350 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
351 FALSE to continue receive the previous response message.
352 @param[out] ResponseData Point to a wrapper of the received response data.
353
354 @retval EFI_SUCCESS The HTTP response is received.
355 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
356 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
357 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
358 @retval Others Other errors as indicated.
359
360 **/
361 EFI_STATUS
362 HttpIoRecvResponse (
363 IN HTTP_IO *HttpIo,
364 IN BOOLEAN RecvMsgHeader,
365 OUT HTTP_IO_RESPONSE_DATA *ResponseData
366 );
367
368 /**
369 This function checks the HTTP(S) URI scheme.
370
371 @param[in] Uri The pointer to the URI string.
372
373 @retval EFI_SUCCESS The URI scheme is valid.
374 @retval EFI_INVALID_PARAMETER The URI scheme is not HTTP or HTTPS.
375 @retval EFI_ACCESS_DENIED HTTP is disabled and the URI is HTTP.
376
377 **/
378 EFI_STATUS
379 HttpBootCheckUriScheme (
380 IN CHAR8 *Uri
381 );
382
383 /**
384 Get the URI address string from the input device path.
385
386 Caller need to free the buffer in the UriAddress pointer.
387
388 @param[in] FilePath Pointer to the device path which contains a URI device path node.
389 @param[out] UriAddress The URI address string extract from the device path.
390
391 @retval EFI_SUCCESS The URI string is returned.
392 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
393
394 **/
395 EFI_STATUS
396 HttpBootParseFilePath (
397 IN EFI_DEVICE_PATH_PROTOCOL *FilePath,
398 OUT CHAR8 **UriAddress
399 );
400
401 /**
402 This function returns the image type according to server replied HTTP message
403 and also the image's URI info.
404
405 @param[in] Uri The pointer to the image's URI string.
406 @param[in] UriParser URI Parse result returned by NetHttpParseUrl().
407 @param[in] HeaderCount Number of HTTP header structures in Headers list.
408 @param[in] Headers Array containing list of HTTP headers.
409 @param[out] ImageType The image type of the downloaded file.
410
411 @retval EFI_SUCCESS The image type is returned in ImageType.
412 @retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL.
413 @retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL.
414 @retval EFI_NOT_FOUND Failed to identify the image type.
415 @retval Others Unexpect error happened.
416
417 **/
418 EFI_STATUS
419 HttpBootCheckImageType (
420 IN CHAR8 *Uri,
421 IN VOID *UriParser,
422 IN UINTN HeaderCount,
423 IN EFI_HTTP_HEADER *Headers,
424 OUT HTTP_BOOT_IMAGE_TYPE *ImageType
425 );
426
427 /**
428 This function register the RAM disk info to the system.
429
430 @param[in] Private The pointer to the driver's private data.
431 @param[in] BufferSize The size of Buffer in bytes.
432 @param[in] Buffer The base address of the RAM disk.
433 @param[in] ImageType The image type of the file in Buffer.
434
435 @retval EFI_SUCCESS The RAM disk has been registered.
436 @retval EFI_NOT_FOUND No RAM disk protocol instances were found.
437 @retval EFI_UNSUPPORTED The ImageType is not supported.
438 @retval Others Unexpected error happened.
439
440 **/
441 EFI_STATUS
442 HttpBootRegisterRamDisk (
443 IN HTTP_BOOT_PRIVATE_DATA *Private,
444 IN UINTN BufferSize,
445 IN VOID *Buffer,
446 IN HTTP_BOOT_IMAGE_TYPE ImageType
447 );
448 #endif