2 Support functions declaration for UEFI HTTP boot driver.
4 Copyright (c) 2015 - 2016, 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 configuration data for IPv4
152 EFI_HTTP_VERSION HttpVersion
;
153 UINT32 RequestTimeOut
; // In milliseconds.
154 UINT32 ResponseTimeOut
; // In milliseconds.
155 BOOLEAN UseDefaultAddress
;
156 EFI_IPv4_ADDRESS LocalIp
;
157 EFI_IPv4_ADDRESS SubnetMask
;
159 } HTTP4_IO_CONFIG_DATA
;
162 // HTTP_IO configuration data for IPv6
165 EFI_HTTP_VERSION HttpVersion
;
166 UINT32 RequestTimeOut
; // In milliseconds.
167 BOOLEAN UseDefaultAddress
;
168 EFI_IPv6_ADDRESS LocalIp
;
170 } HTTP6_IO_CONFIG_DATA
;
174 // HTTP_IO configuration
177 HTTP4_IO_CONFIG_DATA Config4
;
178 HTTP6_IO_CONFIG_DATA Config6
;
179 } HTTP_IO_CONFIG_DATA
;
182 // HTTP_IO wrapper of the EFI HTTP service.
187 EFI_HANDLE Controller
;
190 EFI_HTTP_PROTOCOL
*Http
;
192 EFI_HTTP_TOKEN ReqToken
;
193 EFI_HTTP_MESSAGE ReqMessage
;
194 EFI_HTTP_TOKEN RspToken
;
195 EFI_HTTP_MESSAGE RspMessage
;
200 EFI_EVENT TimeoutEvent
;
204 // A wrapper structure to hold the received HTTP response data.
207 EFI_HTTP_RESPONSE_DATA Response
;
209 EFI_HTTP_HEADER
*Headers
;
213 } HTTP_IO_RESPONSE_DATA
;
216 Retrieve the host address using the EFI_DNS6_PROTOCOL.
218 @param[in] Private The pointer to the driver's private data.
219 @param[in] HostName Pointer to buffer containing hostname.
220 @param[out] IpAddress On output, pointer to buffer containing IPv6 address.
222 @retval EFI_SUCCESS Operation succeeded.
223 @retval EFI_DEVICE_ERROR An unexpected network error occurred.
224 @retval Others Other errors as indicated.
228 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
230 OUT EFI_IPv6_ADDRESS
*IpAddress
234 Notify the callback function when an event is triggered.
236 @param[in] Event The triggered event.
237 @param[in] Context The opaque parameter to the function.
242 HttpBootCommonNotify (
248 Create a HTTP_IO to access the HTTP service. It will create and configure
251 @param[in] Image The handle of the driver image.
252 @param[in] Controller The handle of the controller.
253 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
254 @param[in] ConfigData The HTTP_IO configuration data.
255 @param[out] HttpIo The HTTP_IO.
257 @retval EFI_SUCCESS The HTTP_IO is created and configured.
258 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
259 @retval EFI_UNSUPPORTED One or more of the control options are not
260 supported in the implementation.
261 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
262 @retval Others Failed to create the HTTP_IO or configure it.
268 IN EFI_HANDLE Controller
,
270 IN HTTP_IO_CONFIG_DATA
*ConfigData
,
275 Destroy the HTTP_IO and release the resouces.
277 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
286 Synchronously send a HTTP REQUEST message to the server.
288 @param[in] HttpIo The HttpIo wrapping the HTTP service.
289 @param[in] Request A pointer to storage such data as URL and HTTP method.
290 @param[in] HeaderCount Number of HTTP header structures in Headers list.
291 @param[in] Headers Array containing list of HTTP headers.
292 @param[in] BodyLength Length in bytes of the HTTP body.
293 @param[in] Body Body associated with the HTTP request.
295 @retval EFI_SUCCESS The HTTP request is trasmitted.
296 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
297 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
298 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
299 @retval Others Other errors as indicated.
305 IN EFI_HTTP_REQUEST_DATA
*Request
, OPTIONAL
306 IN UINTN HeaderCount
,
307 IN EFI_HTTP_HEADER
*Headers
, OPTIONAL
309 IN VOID
*Body OPTIONAL
313 Synchronously receive a HTTP RESPONSE message from the server.
315 @param[in] HttpIo The HttpIo wrapping the HTTP service.
316 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
317 FALSE to continue receive the previous response message.
318 @param[out] ResponseData Point to a wrapper of the received response data.
320 @retval EFI_SUCCESS The HTTP response is received.
321 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
322 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
323 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
324 @retval Others Other errors as indicated.
330 IN BOOLEAN RecvMsgHeader
,
331 OUT HTTP_IO_RESPONSE_DATA
*ResponseData
335 Get the URI address string from the input device path.
337 Caller need to free the buffer in the UriAddress pointer.
339 @param[in] FilePath Pointer to the device path which contains a URI device path node.
340 @param[out] UriAddress The URI address string extract from the device path.
342 @retval EFI_SUCCESS The URI string is returned.
343 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
347 HttpBootParseFilePath (
348 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
349 OUT CHAR8
**UriAddress
353 This function returns the image type according to server replied HTTP message
354 and also the image's URI info.
356 @param[in] Uri The pointer to the image's URI string.
357 @param[in] UriParser URI Parse result returned by NetHttpParseUrl().
358 @param[in] HeaderCount Number of HTTP header structures in Headers list.
359 @param[in] Headers Array containing list of HTTP headers.
360 @param[out] ImageType The image type of the downloaded file.
362 @retval EFI_SUCCESS The image type is returned in ImageType.
363 @retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL.
364 @retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL.
365 @retval EFI_NOT_FOUND Failed to identify the image type.
366 @retval Others Unexpect error happened.
370 HttpBootCheckImageType (
373 IN UINTN HeaderCount
,
374 IN EFI_HTTP_HEADER
*Headers
,
375 OUT HTTP_BOOT_IMAGE_TYPE
*ImageType
379 This function register the RAM disk info to the system.
381 @param[in] Private The pointer to the driver's private data.
382 @param[in] BufferSize The size of Buffer in bytes.
383 @param[in] Buffer The base address of the RAM disk.
384 @param[in] ImageType The image type of the file in Buffer.
386 @retval EFI_SUCCESS The RAM disk has been registered.
387 @retval EFI_NOT_FOUND No RAM disk protocol instances were found.
388 @retval EFI_UNSUPPORTED The ImageType is not supported.
389 @retval Others Unexpected error happened.
393 HttpBootRegisterRamDisk (
394 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
397 IN HTTP_BOOT_IMAGE_TYPE ImageType