1/** @file 2 Support functions declaration for UEFI HTTP boot driver. 3 4Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> 5This program and the accompanying materials are licensed and made available under 6the terms and conditions of the BSD License that accompanies this distribution. 7The full text of the license may be found at 8http://opensource.org/licenses/bsd-license.php. 9 10THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13**/ 14 15#ifndef __EFI_HTTP_BOOT_SUPPORT_H__ 16#define __EFI_HTTP_BOOT_SUPPORT_H__ 17 18/** 19 Get the Nic handle using any child handle in the IPv4 stack. 20 21 @param[in] ControllerHandle Pointer to child handle over IPv4. 22 23 @return NicHandle The pointer to the Nic handle. 24 @return NULL Can't find the Nic handle. 25 26**/ 27EFI_HANDLE 28HttpBootGetNicByIp4Children ( 29 IN EFI_HANDLE ControllerHandle 30 ); 31 32/** 33 Get the Nic handle using any child handle in the IPv6 stack. 34 35 @param[in] ControllerHandle Pointer to child handle over IPv6. 36 37 @return NicHandle The pointer to the Nic handle. 38 @return NULL Can't find the Nic handle. 39 40**/ 41EFI_HANDLE 42HttpBootGetNicByIp6Children ( 43 IN EFI_HANDLE ControllerHandle 44 ); 45 46/** 47 This function is to convert UINTN to ASCII string with the required formatting. 48 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. 52 53**/ 54VOID 55HttpBootUintnToAscDecWithFormat ( 56 IN UINTN Number, 57 IN UINT8 *Buffer, 58 IN INTN Length 59 ); 60 61 62/** 63 This function is to display the IPv4 address. 64 65 @param[in] Ip The pointer to the IPv4 address. 66 67**/ 68VOID 69HttpBootShowIp4Addr ( 70 IN EFI_IPv4_ADDRESS *Ip 71 ); 72 73/** 74 This function is to display the IPv6 address. 75 76 @param[in] Ip The pointer to the IPv6 address. 77 78**/ 79VOID 80HttpBootShowIp6Addr ( 81 IN EFI_IPv6_ADDRESS *Ip 82 ); 83 84// 85// A wrapper structure to hold the HTTP headers. 86// 87typedef struct { 88 UINTN MaxHeaderCount; 89 UINTN HeaderCount; 90 EFI_HTTP_HEADER *Headers; 91} HTTP_IO_HEADER; 92 93/** 94 Create a HTTP_IO_HEADER to hold the HTTP header items. 95 96 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder. 97 98 @return A pointer of the HTTP header holder or NULL if failed. 99 100**/ 101HTTP_IO_HEADER * 102HttpBootCreateHeader ( 103 IN UINTN MaxHeaderCount 104 ); 105 106/** 107 Destroy the HTTP_IO_HEADER and release the resouces. 108 109 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed. 110 111**/ 112VOID 113HttpBootFreeHeader ( 114 IN HTTP_IO_HEADER *HttpIoHeader 115 ); 116 117/** 118 Set or update a HTTP header with the field name and corresponding value. 119 120 @param[in] HttpIoHeader Point to the HTTP header holder. 121 @param[in] FieldName Null terminated string which describes a field name. 122 @param[in] FieldValue Null terminated string which describes the corresponding field value. 123 124 @retval EFI_SUCCESS The HTTP header has been set or updated. 125 @retval EFI_INVALID_PARAMETER Any input parameter is invalid. 126 @retval EFI_OUT_OF_RESOURCES Insufficient resource to complete the operation. 127 @retval Other Unexpected error happened. 128 129**/ 130EFI_STATUS 131HttpBootSetHeader ( 132 IN HTTP_IO_HEADER *HttpIoHeader, 133 IN CHAR8 *FieldName, 134 IN CHAR8 *FieldValue 135 ); 136 137// 138// HTTP_IO configuration data for IPv4 139// 140typedef struct { 141 EFI_HTTP_VERSION HttpVersion; 142 UINT32 RequestTimeOut; // In milliseconds. 143 UINT32 ResponseTimeOut; // In milliseconds. 144 BOOLEAN UseDefaultAddress; 145 EFI_IPv4_ADDRESS LocalIp; 146 EFI_IPv4_ADDRESS SubnetMask; 147 UINT16 LocalPort; 148} HTTP4_IO_CONFIG_DATA; 149 150// 151// HTTP_IO configuration data for IPv6 152// 153typedef struct { 154 EFI_HTTP_VERSION HttpVersion; 155 UINT32 RequestTimeOut; // In milliseconds. 156 BOOLEAN UseDefaultAddress; 157 EFI_IPv6_ADDRESS LocalIp; 158 UINT16 LocalPort; 159} HTTP6_IO_CONFIG_DATA; 160 161 162// 163// HTTP_IO configuration 164// 165typedef union { 166 HTTP4_IO_CONFIG_DATA Config4; 167 HTTP6_IO_CONFIG_DATA Config6; 168} HTTP_IO_CONFIG_DATA; 169 170// 171// HTTO_IO wrapper of the EFI HTTP service. 172// 173typedef struct { 174 UINT8 IpVersion; 175 EFI_HANDLE Image; 176 EFI_HANDLE Controller; 177 EFI_HANDLE Handle; 178 179 EFI_HTTP_PROTOCOL *Http; 180 181 EFI_HTTP_TOKEN ReqToken; 182 EFI_HTTP_MESSAGE ReqMessage; 183 EFI_HTTP_TOKEN RspToken; 184 EFI_HTTP_MESSAGE RspMessage; 185 186 BOOLEAN IsTxDone; 187 BOOLEAN IsRxDone; 188} HTTP_IO; 189 190// 191// A wrapper structure to hold the received HTTP response data. 192// 193typedef struct { 194 EFI_HTTP_RESPONSE_DATA Response; 195 UINTN HeaderCount; 196 EFI_HTTP_HEADER *Headers; 197 UINTN BodyLength; 198 CHAR8 *Body; 199} HTTP_IO_RESOPNSE_DATA; 200 201/** 202 Retrieve the host address using the EFI_DNS6_PROTOCOL. 203 204 @param[in] Private The pointer to the driver's private data. 205 @param[in] HostName Pointer to buffer containing hostname. 206 @param[out] IpAddress On output, pointer to buffer containing IPv6 address. 207 208 @retval EFI_SUCCESS Operation succeeded. 209 @retval EFI_DEVICE_ERROR An unexpected network error occurred. 210 @retval Others Other errors as indicated. 211**/ 212EFI_STATUS 213HttpBootDns ( 214 IN HTTP_BOOT_PRIVATE_DATA *Private, 215 IN CHAR16 *HostName, 216 OUT EFI_IPv6_ADDRESS *IpAddress 217 ); 218 219/** 220 Notify the callback function when an event is triggered. 221 222 @param[in] Event The triggered event. 223 @param[in] Context The opaque parameter to the function. 224 225**/ 226VOID 227EFIAPI 228HttpBootCommonNotify ( 229 IN EFI_EVENT Event, 230 IN VOID *Context 231 ); 232 233/** 234 Create a HTTP_IO to access the HTTP service. It will create and configure 235 a HTTP child handle. 236 237 @param[in] Image The handle of the driver image. 238 @param[in] Controller The handle of the controller. 239 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6. 240 @param[in] ConfigData The HTTP_IO configuration data. 241 @param[out] HttpIo The HTTP_IO. 242 243 @retval EFI_SUCCESS The HTTP_IO is created and configured. 244 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 245 @retval EFI_UNSUPPORTED One or more of the control options are not 246 supported in the implementation. 247 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 248 @retval Others Failed to create the HTTP_IO or configure it. 249 250**/ 251EFI_STATUS 252HttpIoCreateIo ( 253 IN EFI_HANDLE Image, 254 IN EFI_HANDLE Controller, 255 IN UINT8 IpVersion, 256 IN HTTP_IO_CONFIG_DATA *ConfigData, 257 OUT HTTP_IO *HttpIo 258 ); 259 260/** 261 Destroy the HTTP_IO and release the resouces. 262 263 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed. 264 265**/ 266VOID 267HttpIoDestroyIo ( 268 IN HTTP_IO *HttpIo 269 ); 270 271/** 272 Synchronously send a HTTP REQUEST message to the server. 273 274 @param[in] HttpIo The HttpIo wrapping the HTTP service. 275 @param[in] Request A pointer to storage such data as URL and HTTP method. 276 @param[in] HeaderCount Number of HTTP header structures in Headers list. 277 @param[in] Headers Array containing list of HTTP headers. 278 @param[in] BodyLength Length in bytes of the HTTP body. 279 @param[in] Body Body associated with the HTTP request. 280 281 @retval EFI_SUCCESS The HTTP request is trasmitted. 282 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 283 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 284 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 285 @retval Others Other errors as indicated. 286 287**/ 288EFI_STATUS 289HttpIoSendRequest ( 290 IN HTTP_IO *HttpIo, 291 IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL 292 IN UINTN HeaderCount, 293 IN EFI_HTTP_HEADER *Headers, OPTIONAL 294 IN UINTN BodyLength, 295 IN VOID *Body OPTIONAL 296 ); 297 298/** 299 Synchronously receive a HTTP RESPONSE message from the server. 300 301 @param[in] HttpIo The HttpIo wrapping the HTTP service. 302 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header). 303 FALSE to continue receive the previous response message. 304 @param[out] ResponseData Point to a wrapper of the received response data. 305 306 @retval EFI_SUCCESS The HTTP resopnse is received. 307 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 308 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 309 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 310 @retval Others Other errors as indicated. 311 312**/ 313EFI_STATUS 314HttpIoRecvResponse ( 315 IN HTTP_IO *HttpIo, 316 IN BOOLEAN RecvMsgHeader, 317 OUT HTTP_IO_RESOPNSE_DATA *ResponseData 318 ); 319 320#endif 321