2 Support functions declaration for UEFI HTTP boot driver.
4 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
5 SPDX-License-Identifier: BSD-2-Clause-Patent
9 #ifndef __EFI_HTTP_BOOT_SUPPORT_H__
10 #define __EFI_HTTP_BOOT_SUPPORT_H__
13 Get the Nic handle using any child handle in the IPv4 stack.
15 @param[in] ControllerHandle Pointer to child handle over IPv4.
17 @return NicHandle The pointer to the Nic handle.
18 @return NULL Can't find the Nic handle.
22 HttpBootGetNicByIp4Children (
23 IN EFI_HANDLE ControllerHandle
27 Get the Nic handle using any child handle in the IPv6 stack.
29 @param[in] ControllerHandle Pointer to child handle over IPv6.
31 @return NicHandle The pointer to the Nic handle.
32 @return NULL Can't find the Nic handle.
36 HttpBootGetNicByIp6Children (
37 IN EFI_HANDLE ControllerHandle
41 This function is to convert UINTN to ASCII string with the required formatting.
43 @param[in] Number Numeric value to be converted.
44 @param[in] Buffer The pointer to the buffer for ASCII string.
45 @param[in] Length The length of the required format.
49 HttpBootUintnToAscDecWithFormat (
57 This function is to display the IPv4 address.
59 @param[in] Ip The pointer to the IPv4 address.
64 IN EFI_IPv4_ADDRESS
*Ip
68 This function is to display the IPv6 address.
70 @param[in] Ip The pointer to the IPv6 address.
75 IN EFI_IPv6_ADDRESS
*Ip
79 This function is to display the HTTP error status.
81 @param[in] StatusCode The status code value in HTTP message.
85 HttpBootPrintErrorMessage (
86 EFI_HTTP_STATUS_CODE StatusCode
90 // A wrapper structure to hold the HTTP headers.
95 EFI_HTTP_HEADER
*Headers
;
99 Create a HTTP_IO_HEADER to hold the HTTP header items.
101 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder.
103 @return A pointer of the HTTP header holder or NULL if failed.
107 HttpBootCreateHeader (
108 IN UINTN MaxHeaderCount
112 Destroy the HTTP_IO_HEADER and release the resouces.
114 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed.
119 IN HTTP_IO_HEADER
*HttpIoHeader
123 Set or update a HTTP header with the field name and corresponding value.
125 @param[in] HttpIoHeader Point to the HTTP header holder.
126 @param[in] FieldName Null terminated string which describes a field name.
127 @param[in] FieldValue Null terminated string which describes the corresponding field value.
129 @retval EFI_SUCCESS The HTTP header has been set or updated.
130 @retval EFI_INVALID_PARAMETER Any input parameter is invalid.
131 @retval EFI_OUT_OF_RESOURCES Insufficient resource to complete the operation.
132 @retval Other Unexpected error happened.
137 IN HTTP_IO_HEADER
*HttpIoHeader
,
143 /// HTTP_IO_CALLBACK_EVENT
148 } HTTP_IO_CALLBACK_EVENT
;
151 HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
153 @param[in] EventType Indicate the Event type that occurs in the current callback.
154 @param[in] Message HTTP message which will be send to, or just received from HTTP server.
155 @param[in] Context The Callback Context pointer.
157 @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process.
158 @retval Others Tells the HttpIo to abort the current HTTP process.
162 (EFIAPI
* HTTP_IO_CALLBACK
) (
163 IN HTTP_IO_CALLBACK_EVENT EventType
,
164 IN EFI_HTTP_MESSAGE
*Message
,
169 // HTTP_IO configuration data for IPv4
172 EFI_HTTP_VERSION HttpVersion
;
173 UINT32 RequestTimeOut
; // In milliseconds.
174 UINT32 ResponseTimeOut
; // In milliseconds.
175 BOOLEAN UseDefaultAddress
;
176 EFI_IPv4_ADDRESS LocalIp
;
177 EFI_IPv4_ADDRESS SubnetMask
;
179 } HTTP4_IO_CONFIG_DATA
;
182 // HTTP_IO configuration data for IPv6
185 EFI_HTTP_VERSION HttpVersion
;
186 UINT32 RequestTimeOut
; // In milliseconds.
187 BOOLEAN UseDefaultAddress
;
188 EFI_IPv6_ADDRESS LocalIp
;
190 } HTTP6_IO_CONFIG_DATA
;
194 // HTTP_IO configuration
197 HTTP4_IO_CONFIG_DATA Config4
;
198 HTTP6_IO_CONFIG_DATA Config6
;
199 } HTTP_IO_CONFIG_DATA
;
202 // HTTP_IO wrapper of the EFI HTTP service.
207 EFI_HANDLE Controller
;
210 EFI_HTTP_PROTOCOL
*Http
;
212 HTTP_IO_CALLBACK Callback
;
215 EFI_HTTP_TOKEN ReqToken
;
216 EFI_HTTP_MESSAGE ReqMessage
;
217 EFI_HTTP_TOKEN RspToken
;
218 EFI_HTTP_MESSAGE RspMessage
;
223 EFI_EVENT TimeoutEvent
;
227 // A wrapper structure to hold the received HTTP response data.
230 EFI_HTTP_RESPONSE_DATA Response
;
232 EFI_HTTP_HEADER
*Headers
;
236 } HTTP_IO_RESPONSE_DATA
;
239 Retrieve the host address using the EFI_DNS6_PROTOCOL.
241 @param[in] Private The pointer to the driver's private data.
242 @param[in] HostName Pointer to buffer containing hostname.
243 @param[out] IpAddress On output, pointer to buffer containing IPv6 address.
245 @retval EFI_SUCCESS Operation succeeded.
246 @retval EFI_DEVICE_ERROR An unexpected network error occurred.
247 @retval Others Other errors as indicated.
251 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
253 OUT EFI_IPv6_ADDRESS
*IpAddress
257 Notify the callback function when an event is triggered.
259 @param[in] Event The triggered event.
260 @param[in] Context The opaque parameter to the function.
265 HttpBootCommonNotify (
271 Create a HTTP_IO to access the HTTP service. It will create and configure
274 @param[in] Image The handle of the driver image.
275 @param[in] Controller The handle of the controller.
276 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
277 @param[in] ConfigData The HTTP_IO configuration data.
278 @param[in] Callback Callback function which will be invoked when specified
279 HTTP_IO_CALLBACK_EVENT happened.
280 @param[in] Context The Context data which will be passed to the Callback function.
281 @param[out] HttpIo The HTTP_IO.
283 @retval EFI_SUCCESS The HTTP_IO is created and configured.
284 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
285 @retval EFI_UNSUPPORTED One or more of the control options are not
286 supported in the implementation.
287 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
288 @retval Others Failed to create the HTTP_IO or configure it.
294 IN EFI_HANDLE Controller
,
296 IN HTTP_IO_CONFIG_DATA
*ConfigData
,
297 IN HTTP_IO_CALLBACK Callback
,
303 Destroy the HTTP_IO and release the resouces.
305 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
314 Synchronously send a HTTP REQUEST message to the server.
316 @param[in] HttpIo The HttpIo wrapping the HTTP service.
317 @param[in] Request A pointer to storage such data as URL and HTTP method.
318 @param[in] HeaderCount Number of HTTP header structures in Headers list.
319 @param[in] Headers Array containing list of HTTP headers.
320 @param[in] BodyLength Length in bytes of the HTTP body.
321 @param[in] Body Body associated with the HTTP request.
323 @retval EFI_SUCCESS The HTTP request is trasmitted.
324 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
325 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
326 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
327 @retval Others Other errors as indicated.
333 IN EFI_HTTP_REQUEST_DATA
*Request
, OPTIONAL
334 IN UINTN HeaderCount
,
335 IN EFI_HTTP_HEADER
*Headers
, OPTIONAL
337 IN VOID
*Body OPTIONAL
341 Synchronously receive a HTTP RESPONSE message from the server.
343 @param[in] HttpIo The HttpIo wrapping the HTTP service.
344 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
345 FALSE to continue receive the previous response message.
346 @param[out] ResponseData Point to a wrapper of the received response data.
348 @retval EFI_SUCCESS The HTTP response is received.
349 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
350 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
351 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
352 @retval Others Other errors as indicated.
358 IN BOOLEAN RecvMsgHeader
,
359 OUT HTTP_IO_RESPONSE_DATA
*ResponseData
363 This function checks the HTTP(S) URI scheme.
365 @param[in] Uri The pointer to the URI string.
367 @retval EFI_SUCCESS The URI scheme is valid.
368 @retval EFI_INVALID_PARAMETER The URI scheme is not HTTP or HTTPS.
369 @retval EFI_ACCESS_DENIED HTTP is disabled and the URI is HTTP.
373 HttpBootCheckUriScheme (
378 Get the URI address string from the input device path.
380 Caller need to free the buffer in the UriAddress pointer.
382 @param[in] FilePath Pointer to the device path which contains a URI device path node.
383 @param[out] UriAddress The URI address string extract from the device path.
385 @retval EFI_SUCCESS The URI string is returned.
386 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
390 HttpBootParseFilePath (
391 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
392 OUT CHAR8
**UriAddress
396 This function returns the image type according to server replied HTTP message
397 and also the image's URI info.
399 @param[in] Uri The pointer to the image's URI string.
400 @param[in] UriParser URI Parse result returned by NetHttpParseUrl().
401 @param[in] HeaderCount Number of HTTP header structures in Headers list.
402 @param[in] Headers Array containing list of HTTP headers.
403 @param[out] ImageType The image type of the downloaded file.
405 @retval EFI_SUCCESS The image type is returned in ImageType.
406 @retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL.
407 @retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL.
408 @retval EFI_NOT_FOUND Failed to identify the image type.
409 @retval Others Unexpect error happened.
413 HttpBootCheckImageType (
416 IN UINTN HeaderCount
,
417 IN EFI_HTTP_HEADER
*Headers
,
418 OUT HTTP_BOOT_IMAGE_TYPE
*ImageType
422 This function register the RAM disk info to the system.
424 @param[in] Private The pointer to the driver's private data.
425 @param[in] BufferSize The size of Buffer in bytes.
426 @param[in] Buffer The base address of the RAM disk.
427 @param[in] ImageType The image type of the file in Buffer.
429 @retval EFI_SUCCESS The RAM disk has been registered.
430 @retval EFI_NOT_FOUND No RAM disk protocol instances were found.
431 @retval EFI_UNSUPPORTED The ImageType is not supported.
432 @retval Others Unexpected error happened.
436 HttpBootRegisterRamDisk (
437 IN HTTP_BOOT_PRIVATE_DATA
*Private
,
440 IN HTTP_BOOT_IMAGE_TYPE ImageType
444 Indicate if the HTTP status code indicates a redirection.
446 @param[in] StatusCode HTTP status code from server.
448 @return TRUE if it's redirection.
452 HttpBootIsHttpRedirectStatusCode (
453 IN EFI_HTTP_STATUS_CODE StatusCode