1 /** @file 2 Support functions declaration for UEFI HTTP boot driver. 3 4 Copyright (c) 2015, 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. 9 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. 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 **/ 27 EFI_HANDLE 28 HttpBootGetNicByIp4Children ( 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 **/ 41 EFI_HANDLE 42 HttpBootGetNicByIp6Children ( 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 **/ 54 VOID 55 HttpBootUintnToAscDecWithFormat ( 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 **/ 68 VOID 69 HttpBootShowIp4Addr ( 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 **/ 79 VOID 80 HttpBootShowIp6Addr ( 81 IN EFI_IPv6_ADDRESS *Ip 82 ); 83 84 // 85 // A wrapper structure to hold the HTTP headers. 86 // 87 typedef 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 **/ 101 HTTP_IO_HEADER * 102 HttpBootCreateHeader ( 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 **/ 112 VOID 113 HttpBootFreeHeader ( 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 **/ 130 EFI_STATUS 131 HttpBootSetHeader ( 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 // 140 typedef 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 // 153 typedef 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 // 165 typedef 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 // 173 typedef 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 // 193 typedef 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 **/ 212 EFI_STATUS 213 HttpBootDns ( 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 **/ 226 VOID 227 EFIAPI 228 HttpBootCommonNotify ( 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 **/ 251 EFI_STATUS 252 HttpIoCreateIo ( 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 **/ 266 VOID 267 HttpIoDestroyIo ( 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 **/ 288 EFI_STATUS 289 HttpIoSendRequest ( 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 **/ 313 EFI_STATUS 314 HttpIoRecvResponse ( 315 IN HTTP_IO *HttpIo, 316 IN BOOLEAN RecvMsgHeader, 317 OUT HTTP_IO_RESOPNSE_DATA *ResponseData 318 ); 319 320 #endif 321
