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
;
202 // A wrapper structure to hold the received HTTP response data.
205 EFI_HTTP_RESPONSE_DATA Response
;
207 EFI_HTTP_HEADER
*Headers
;
211 } HTTP_IO_RESPONSE_DATA
;
214 Retrieve the host address using the EFI_DNS6_PROTOCOL.
216 @param[in] Private The pointer to the driver's private data.
217 @param[in] HostName Pointer to buffer containing hostname.
218 @param[out] IpAddress On output, pointer to buffer containing IPv6 address.
220 @retval EFI_SUCCESS Operation succeeded.
221 @retval EFI_DEVICE_ERROR An unexpected network error occurred.
222 @retval Others Other errors as indicated.
226 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
228 OUT EFI_IPv6_ADDRESS
*IpAddress
232 Notify the callback function when an event is triggered.
234 @param[in] Event The triggered event.
235 @param[in] Context The opaque parameter to the function.
240 HttpBootCommonNotify (
246 Create a HTTP_IO to access the HTTP service. It will create and configure
249 @param[in] Image The handle of the driver image.
250 @param[in] Controller The handle of the controller.
251 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
252 @param[in] ConfigData The HTTP_IO configuration data.
253 @param[out] HttpIo The HTTP_IO.
255 @retval EFI_SUCCESS The HTTP_IO is created and configured.
256 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
257 @retval EFI_UNSUPPORTED One or more of the control options are not
258 supported in the implementation.
259 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
260 @retval Others Failed to create the HTTP_IO or configure it.
266 IN EFI_HANDLE Controller
,
268 IN HTTP_IO_CONFIG_DATA
*ConfigData
,
273 Destroy the HTTP_IO and release the resouces.
275 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
284 Synchronously send a HTTP REQUEST message to the server.
286 @param[in] HttpIo The HttpIo wrapping the HTTP service.
287 @param[in] Request A pointer to storage such data as URL and HTTP method.
288 @param[in] HeaderCount Number of HTTP header structures in Headers list.
289 @param[in] Headers Array containing list of HTTP headers.
290 @param[in] BodyLength Length in bytes of the HTTP body.
291 @param[in] Body Body associated with the HTTP request.
293 @retval EFI_SUCCESS The HTTP request is trasmitted.
294 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
295 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
296 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
297 @retval Others Other errors as indicated.
303 IN EFI_HTTP_REQUEST_DATA
*Request
, OPTIONAL
304 IN UINTN HeaderCount
,
305 IN EFI_HTTP_HEADER
*Headers
, OPTIONAL
307 IN VOID
*Body OPTIONAL
311 Synchronously receive a HTTP RESPONSE message from the server.
313 @param[in] HttpIo The HttpIo wrapping the HTTP service.
314 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
315 FALSE to continue receive the previous response message.
316 @param[out] ResponseData Point to a wrapper of the received response data.
318 @retval EFI_SUCCESS The HTTP response is received.
319 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
320 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
321 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
322 @retval Others Other errors as indicated.
328 IN BOOLEAN RecvMsgHeader
,
329 OUT HTTP_IO_RESPONSE_DATA
*ResponseData
333 Get the URI address string from the input device path.
335 Caller need to free the buffer in the UriAddress pointer.
337 @param[in] FilePath Pointer to the device path which contains a URI device path node.
338 @param[in] UriAddress The URI address string extract from the device path.
340 @retval EFI_SUCCESS The URI string is returned.
341 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
345 HttpBootParseFilePath (
346 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
347 OUT CHAR8
**UriAddress