2 Support functions declaration for UEFI HTTP boot driver.
4 Copyright (c) 2015 - 2018, 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.
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.
15 #ifndef __EFI_HTTP_BOOT_SUPPORT_H__
16 #define __EFI_HTTP_BOOT_SUPPORT_H__
19 Get the Nic handle using any child handle in the IPv4 stack.
21 @param[in] ControllerHandle Pointer to child handle over IPv4.
23 @return NicHandle The pointer to the Nic handle.
24 @return NULL Can't find the Nic handle.
28 HttpBootGetNicByIp4Children (
29 IN EFI_HANDLE ControllerHandle
33 Get the Nic handle using any child handle in the IPv6 stack.
35 @param[in] ControllerHandle Pointer to child handle over IPv6.
37 @return NicHandle The pointer to the Nic handle.
38 @return NULL Can't find the Nic handle.
42 HttpBootGetNicByIp6Children (
43 IN EFI_HANDLE ControllerHandle
47 This function is to convert UINTN to ASCII string with the required formatting.
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.
55 HttpBootUintnToAscDecWithFormat (
63 This function is to display the IPv4 address.
65 @param[in] Ip The pointer to the IPv4 address.
70 IN EFI_IPv4_ADDRESS
*Ip
74 This function is to display the IPv6 address.
76 @param[in] Ip The pointer to the IPv6 address.
81 IN EFI_IPv6_ADDRESS
*Ip
85 This function is to display the HTTP error status.
87 @param[in] StatusCode The status code value in HTTP message.
91 HttpBootPrintErrorMessage (
92 EFI_HTTP_STATUS_CODE StatusCode
96 // A wrapper structure to hold the HTTP headers.
101 EFI_HTTP_HEADER
*Headers
;
105 Create a HTTP_IO_HEADER to hold the HTTP header items.
107 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder.
109 @return A pointer of the HTTP header holder or NULL if failed.
113 HttpBootCreateHeader (
114 IN UINTN MaxHeaderCount
118 Destroy the HTTP_IO_HEADER and release the resouces.
120 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed.
125 IN HTTP_IO_HEADER
*HttpIoHeader
129 Set or update a HTTP header with the field name and corresponding value.
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.
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.
143 IN HTTP_IO_HEADER
*HttpIoHeader
,
149 /// HTTP_IO_CALLBACK_EVENT
154 } HTTP_IO_CALLBACK_EVENT
;
157 HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
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.
163 @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process.
164 @retval Others Tells the HttpIo to abort the current HTTP process.
168 (EFIAPI
* HTTP_IO_CALLBACK
) (
169 IN HTTP_IO_CALLBACK_EVENT EventType
,
170 IN EFI_HTTP_MESSAGE
*Message
,
175 // HTTP_IO configuration data for IPv4
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
;
185 } HTTP4_IO_CONFIG_DATA
;
188 // HTTP_IO configuration data for IPv6
191 EFI_HTTP_VERSION HttpVersion
;
192 UINT32 RequestTimeOut
; // In milliseconds.
193 BOOLEAN UseDefaultAddress
;
194 EFI_IPv6_ADDRESS LocalIp
;
196 } HTTP6_IO_CONFIG_DATA
;
200 // HTTP_IO configuration
203 HTTP4_IO_CONFIG_DATA Config4
;
204 HTTP6_IO_CONFIG_DATA Config6
;
205 } HTTP_IO_CONFIG_DATA
;
208 // HTTP_IO wrapper of the EFI HTTP service.
213 EFI_HANDLE Controller
;
216 EFI_HTTP_PROTOCOL
*Http
;
218 HTTP_IO_CALLBACK Callback
;
221 EFI_HTTP_TOKEN ReqToken
;
222 EFI_HTTP_MESSAGE ReqMessage
;
223 EFI_HTTP_TOKEN RspToken
;
224 EFI_HTTP_MESSAGE RspMessage
;
229 EFI_EVENT TimeoutEvent
;
233 // A wrapper structure to hold the received HTTP response data.
236 EFI_HTTP_RESPONSE_DATA Response
;
238 EFI_HTTP_HEADER
*Headers
;
242 } HTTP_IO_RESPONSE_DATA
;
245 Retrieve the host address using the EFI_DNS6_PROTOCOL.
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.
251 @retval EFI_SUCCESS Operation succeeded.
252 @retval EFI_DEVICE_ERROR An unexpected network error occurred.
253 @retval Others Other errors as indicated.
257 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
259 OUT EFI_IPv6_ADDRESS
*IpAddress
263 Notify the callback function when an event is triggered.
265 @param[in] Event The triggered event.
266 @param[in] Context The opaque parameter to the function.
271 HttpBootCommonNotify (
277 Create a HTTP_IO to access the HTTP service. It will create and configure
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.
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.
300 IN EFI_HANDLE Controller
,
302 IN HTTP_IO_CONFIG_DATA
*ConfigData
,
303 IN HTTP_IO_CALLBACK Callback
,
309 Destroy the HTTP_IO and release the resouces.
311 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
320 Synchronously send a HTTP REQUEST message to the server.
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.
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.
339 IN EFI_HTTP_REQUEST_DATA
*Request
, OPTIONAL
340 IN UINTN HeaderCount
,
341 IN EFI_HTTP_HEADER
*Headers
, OPTIONAL
343 IN VOID
*Body OPTIONAL
347 Synchronously receive a HTTP RESPONSE message from the server.
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.
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.
364 IN BOOLEAN RecvMsgHeader
,
365 OUT HTTP_IO_RESPONSE_DATA
*ResponseData
369 This function checks the HTTP(S) URI scheme.
371 @param[in] Uri The pointer to the URI string.
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.
379 HttpBootCheckUriScheme (
384 Get the URI address string from the input device path.
386 Caller need to free the buffer in the UriAddress pointer.
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.
391 @retval EFI_SUCCESS The URI string is returned.
392 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
396 HttpBootParseFilePath (
397 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
398 OUT CHAR8
**UriAddress
402 This function returns the image type according to server replied HTTP message
403 and also the image's URI info.
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.
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.
419 HttpBootCheckImageType (
422 IN UINTN HeaderCount
,
423 IN EFI_HTTP_HEADER
*Headers
,
424 OUT HTTP_BOOT_IMAGE_TYPE
*ImageType
428 This function register the RAM disk info to the system.
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.
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.
442 HttpBootRegisterRamDisk (
443 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
446 IN HTTP_BOOT_IMAGE_TYPE ImageType
450 Indicate if the HTTP status code indicates a redirection.
452 @param[in] StatusCode HTTP status code from server.
454 @return TRUE if it's redirection.
458 HttpBootIsHttpRedirectStatusCode (
459 IN EFI_HTTP_STATUS_CODE StatusCode