1 /** @file 2 Support functions declaration for UEFI HTTP boot driver. 3 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. 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 This function is to display the HTTP error status. 86 87 @param[in] StatusCode The status code value in HTTP message. 88 89 **/ 90 VOID 91 HttpBootPrintErrorMessage ( 92 EFI_HTTP_STATUS_CODE StatusCode 93 ); 94 95 // 96 // A wrapper structure to hold the HTTP headers. 97 // 98 typedef struct { 99 UINTN MaxHeaderCount; 100 UINTN HeaderCount; 101 EFI_HTTP_HEADER *Headers; 102 } HTTP_IO_HEADER; 103 104 /** 105 Create a HTTP_IO_HEADER to hold the HTTP header items. 106 107 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder. 108 109 @return A pointer of the HTTP header holder or NULL if failed. 110 111 **/ 112 HTTP_IO_HEADER * 113 HttpBootCreateHeader ( 114 IN UINTN MaxHeaderCount 115 ); 116 117 /** 118 Destroy the HTTP_IO_HEADER and release the resouces. 119 120 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed. 121 122 **/ 123 VOID 124 HttpBootFreeHeader ( 125 IN HTTP_IO_HEADER *HttpIoHeader 126 ); 127 128 /** 129 Set or update a HTTP header with the field name and corresponding value. 130 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. 134 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. 139 140 **/ 141 EFI_STATUS 142 HttpBootSetHeader ( 143 IN HTTP_IO_HEADER *HttpIoHeader, 144 IN CHAR8 *FieldName, 145 IN CHAR8 *FieldValue 146 ); 147 148 // 149 // HTTP_IO configuration data for IPv4 150 // 151 typedef struct { 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; 158 UINT16 LocalPort; 159 } HTTP4_IO_CONFIG_DATA; 160 161 // 162 // HTTP_IO configuration data for IPv6 163 // 164 typedef struct { 165 EFI_HTTP_VERSION HttpVersion; 166 UINT32 RequestTimeOut; // In milliseconds. 167 BOOLEAN UseDefaultAddress; 168 EFI_IPv6_ADDRESS LocalIp; 169 UINT16 LocalPort; 170 } HTTP6_IO_CONFIG_DATA; 171 172 173 // 174 // HTTP_IO configuration 175 // 176 typedef union { 177 HTTP4_IO_CONFIG_DATA Config4; 178 HTTP6_IO_CONFIG_DATA Config6; 179 } HTTP_IO_CONFIG_DATA; 180 181 // 182 // HTTP_IO wrapper of the EFI HTTP service. 183 // 184 typedef struct { 185 UINT8 IpVersion; 186 EFI_HANDLE Image; 187 EFI_HANDLE Controller; 188 EFI_HANDLE Handle; 189 190 EFI_HTTP_PROTOCOL *Http; 191 192 EFI_HTTP_TOKEN ReqToken; 193 EFI_HTTP_MESSAGE ReqMessage; 194 EFI_HTTP_TOKEN RspToken; 195 EFI_HTTP_MESSAGE RspMessage; 196 197 BOOLEAN IsTxDone; 198 BOOLEAN IsRxDone; 199 200 EFI_EVENT TimeoutEvent; 201 } HTTP_IO; 202 203 // 204 // A wrapper structure to hold the received HTTP response data. 205 // 206 typedef struct { 207 EFI_HTTP_RESPONSE_DATA Response; 208 UINTN HeaderCount; 209 EFI_HTTP_HEADER *Headers; 210 UINTN BodyLength; 211 CHAR8 *Body; 212 EFI_STATUS Status; 213 } HTTP_IO_RESPONSE_DATA; 214 215 /** 216 Retrieve the host address using the EFI_DNS6_PROTOCOL. 217 218 @param[in] Private The pointer to the driver's private data. 219 @param[in] HostName Pointer to buffer containing hostname. 220 @param[out] IpAddress On output, pointer to buffer containing IPv6 address. 221 222 @retval EFI_SUCCESS Operation succeeded. 223 @retval EFI_DEVICE_ERROR An unexpected network error occurred. 224 @retval Others Other errors as indicated. 225 **/ 226 EFI_STATUS 227 HttpBootDns ( 228 IN HTTP_BOOT_PRIVATE_DATA *Private, 229 IN CHAR16 *HostName, 230 OUT EFI_IPv6_ADDRESS *IpAddress 231 ); 232 233 /** 234 Notify the callback function when an event is triggered. 235 236 @param[in] Event The triggered event. 237 @param[in] Context The opaque parameter to the function. 238 239 **/ 240 VOID 241 EFIAPI 242 HttpBootCommonNotify ( 243 IN EFI_EVENT Event, 244 IN VOID *Context 245 ); 246 247 /** 248 Create a HTTP_IO to access the HTTP service. It will create and configure 249 a HTTP child handle. 250 251 @param[in] Image The handle of the driver image. 252 @param[in] Controller The handle of the controller. 253 @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6. 254 @param[in] ConfigData The HTTP_IO configuration data. 255 @param[out] HttpIo The HTTP_IO. 256 257 @retval EFI_SUCCESS The HTTP_IO is created and configured. 258 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 259 @retval EFI_UNSUPPORTED One or more of the control options are not 260 supported in the implementation. 261 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 262 @retval Others Failed to create the HTTP_IO or configure it. 263 264 **/ 265 EFI_STATUS 266 HttpIoCreateIo ( 267 IN EFI_HANDLE Image, 268 IN EFI_HANDLE Controller, 269 IN UINT8 IpVersion, 270 IN HTTP_IO_CONFIG_DATA *ConfigData, 271 OUT HTTP_IO *HttpIo 272 ); 273 274 /** 275 Destroy the HTTP_IO and release the resouces. 276 277 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed. 278 279 **/ 280 VOID 281 HttpIoDestroyIo ( 282 IN HTTP_IO *HttpIo 283 ); 284 285 /** 286 Synchronously send a HTTP REQUEST message to the server. 287 288 @param[in] HttpIo The HttpIo wrapping the HTTP service. 289 @param[in] Request A pointer to storage such data as URL and HTTP method. 290 @param[in] HeaderCount Number of HTTP header structures in Headers list. 291 @param[in] Headers Array containing list of HTTP headers. 292 @param[in] BodyLength Length in bytes of the HTTP body. 293 @param[in] Body Body associated with the HTTP request. 294 295 @retval EFI_SUCCESS The HTTP request is trasmitted. 296 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 297 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 298 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 299 @retval Others Other errors as indicated. 300 301 **/ 302 EFI_STATUS 303 HttpIoSendRequest ( 304 IN HTTP_IO *HttpIo, 305 IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL 306 IN UINTN HeaderCount, 307 IN EFI_HTTP_HEADER *Headers, OPTIONAL 308 IN UINTN BodyLength, 309 IN VOID *Body OPTIONAL 310 ); 311 312 /** 313 Synchronously receive a HTTP RESPONSE message from the server. 314 315 @param[in] HttpIo The HttpIo wrapping the HTTP service. 316 @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header). 317 FALSE to continue receive the previous response message. 318 @param[out] ResponseData Point to a wrapper of the received response data. 319 320 @retval EFI_SUCCESS The HTTP response is received. 321 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 322 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 323 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 324 @retval Others Other errors as indicated. 325 326 **/ 327 EFI_STATUS 328 HttpIoRecvResponse ( 329 IN HTTP_IO *HttpIo, 330 IN BOOLEAN RecvMsgHeader, 331 OUT HTTP_IO_RESPONSE_DATA *ResponseData 332 ); 333 334 /** 335 Get the URI address string from the input device path. 336 337 Caller need to free the buffer in the UriAddress pointer. 338 339 @param[in] FilePath Pointer to the device path which contains a URI device path node. 340 @param[out] UriAddress The URI address string extract from the device path. 341 342 @retval EFI_SUCCESS The URI string is returned. 343 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 344 345 **/ 346 EFI_STATUS 347 HttpBootParseFilePath ( 348 IN EFI_DEVICE_PATH_PROTOCOL *FilePath, 349 OUT CHAR8 **UriAddress 350 ); 351 352 /** 353 This function returns the image type according to server replied HTTP message 354 and also the image's URI info. 355 356 @param[in] Uri The pointer to the image's URI string. 357 @param[in] UriParser URI Parse result returned by NetHttpParseUrl(). 358 @param[in] HeaderCount Number of HTTP header structures in Headers list. 359 @param[in] Headers Array containing list of HTTP headers. 360 @param[out] ImageType The image type of the downloaded file. 361 362 @retval EFI_SUCCESS The image type is returned in ImageType. 363 @retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL. 364 @retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL. 365 @retval EFI_NOT_FOUND Failed to identify the image type. 366 @retval Others Unexpect error happened. 367 368 **/ 369 EFI_STATUS 370 HttpBootCheckImageType ( 371 IN CHAR8 *Uri, 372 IN VOID *UriParser, 373 IN UINTN HeaderCount, 374 IN EFI_HTTP_HEADER *Headers, 375 OUT HTTP_BOOT_IMAGE_TYPE *ImageType 376 ); 377 378 /** 379 This function register the RAM disk info to the system. 380 381 @param[in] Private The pointer to the driver's private data. 382 @param[in] BufferSize The size of Buffer in bytes. 383 @param[in] Buffer The base address of the RAM disk. 384 @param[in] ImageType The image type of the file in Buffer. 385 386 @retval EFI_SUCCESS The RAM disk has been registered. 387 @retval EFI_NOT_FOUND No RAM disk protocol instances were found. 388 @retval EFI_UNSUPPORTED The ImageType is not supported. 389 @retval Others Unexpected error happened. 390 391 **/ 392 EFI_STATUS 393 HttpBootRegisterRamDisk ( 394 IN HTTP_BOOT_PRIVATE_DATA *Private, 395 IN UINTN BufferSize, 396 IN VOID *Buffer, 397 IN HTTP_BOOT_IMAGE_TYPE ImageType 398 ); 399 #endif 400