[mirror_edk2.git] / NetworkPkg / HttpBootDxe / HttpBootSupport.h

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