1 /** @file 2 Support functions declaration for UEFI HTTP boot driver. 3 4 Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 **/ 8 9 #ifndef __EFI_HTTP_BOOT_SUPPORT_H__ 10 #define __EFI_HTTP_BOOT_SUPPORT_H__ 11 12 /** 13 Get the Nic handle using any child handle in the IPv4 stack. 14 15 @param[in] ControllerHandle Pointer to child handle over IPv4. 16 17 @return NicHandle The pointer to the Nic handle. 18 @return NULL Can't find the Nic handle. 19 20 **/ 21 EFI_HANDLE 22 HttpBootGetNicByIp4Children ( 23 IN EFI_HANDLE ControllerHandle 24 ); 25 26 /** 27 Get the Nic handle using any child handle in the IPv6 stack. 28 29 @param[in] ControllerHandle Pointer to child handle over IPv6. 30 31 @return NicHandle The pointer to the Nic handle. 32 @return NULL Can't find the Nic handle. 33 34 **/ 35 EFI_HANDLE 36 HttpBootGetNicByIp6Children ( 37 IN EFI_HANDLE ControllerHandle 38 ); 39 40 /** 41 This function is to convert UINTN to ASCII string with the required formatting. 42 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. 46 47 **/ 48 VOID 49 HttpBootUintnToAscDecWithFormat ( 50 IN UINTN Number, 51 IN UINT8 *Buffer, 52 IN INTN Length 53 ); 54 55 56 /** 57 This function is to display the IPv4 address. 58 59 @param[in] Ip The pointer to the IPv4 address. 60 61 **/ 62 VOID 63 HttpBootShowIp4Addr ( 64 IN EFI_IPv4_ADDRESS *Ip 65 ); 66 67 /** 68 This function is to display the IPv6 address. 69 70 @param[in] Ip The pointer to the IPv6 address. 71 72 **/ 73 VOID 74 HttpBootShowIp6Addr ( 75 IN EFI_IPv6_ADDRESS *Ip 76 ); 77 78 /** 79 This function is to display the HTTP error status. 80 81 @param[in] StatusCode The status code value in HTTP message. 82 83 **/ 84 VOID 85 HttpBootPrintErrorMessage ( 86 EFI_HTTP_STATUS_CODE StatusCode 87 ); 88 89 // 90 // A wrapper structure to hold the HTTP headers. 91 // 92 typedef struct { 93 UINTN MaxHeaderCount; 94 UINTN HeaderCount; 95 EFI_HTTP_HEADER *Headers; 96 } HTTP_IO_HEADER; 97 98 /** 99 Create a HTTP_IO_HEADER to hold the HTTP header items. 100 101 @param[in] MaxHeaderCount The maximun number of HTTP header in this holder. 102 103 @return A pointer of the HTTP header holder or NULL if failed. 104 105 **/ 106 HTTP_IO_HEADER * 107 HttpBootCreateHeader ( 108 IN UINTN MaxHeaderCount 109 ); 110 111 /** 112 Destroy the HTTP_IO_HEADER and release the resouces. 113 114 @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed. 115 116 **/ 117 VOID 118 HttpBootFreeHeader ( 119 IN HTTP_IO_HEADER *HttpIoHeader 120 ); 121 122 /** 123 Set or update a HTTP header with the field name and corresponding value. 124 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. 128 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. 133 134 **/ 135 EFI_STATUS 136 HttpBootSetHeader ( 137 IN HTTP_IO_HEADER *HttpIoHeader, 138 IN CHAR8 *FieldName, 139 IN CHAR8 *FieldValue 140 ); 141 142 /// 143 /// HTTP_IO_CALLBACK_EVENT 144 /// 145 typedef enum { 146 HttpIoRequest, 147 HttpIoResponse 148 } HTTP_IO_CALLBACK_EVENT; 149 150 /** 151 HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened. 152 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. 156 157 @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process. 158 @retval Others Tells the HttpIo to abort the current HTTP process. 159 **/ 160 typedef 161 EFI_STATUS 162 (EFIAPI * HTTP_IO_CALLBACK) ( 163 IN HTTP_IO_CALLBACK_EVENT EventType, 164 IN EFI_HTTP_MESSAGE *Message, 165 IN VOID *Context 166 ); 167 168 // 169 // HTTP_IO configuration data for IPv4 170 // 171 typedef struct { 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; 178 UINT16 LocalPort; 179 } HTTP4_IO_CONFIG_DATA; 180 181 // 182 // HTTP_IO configuration data for IPv6 183 // 184 typedef struct { 185 EFI_HTTP_VERSION HttpVersion; 186 UINT32 RequestTimeOut; // In milliseconds. 187 BOOLEAN UseDefaultAddress; 188 EFI_IPv6_ADDRESS LocalIp; 189 UINT16 LocalPort; 190 } HTTP6_IO_CONFIG_DATA; 191 192 193 // 194 // HTTP_IO configuration 195 // 196 typedef union { 197 HTTP4_IO_CONFIG_DATA Config4; 198 HTTP6_IO_CONFIG_DATA Config6; 199 } HTTP_IO_CONFIG_DATA; 200 201 // 202 // HTTP_IO wrapper of the EFI HTTP service. 203 // 204 typedef struct { 205 UINT8 IpVersion; 206 EFI_HANDLE Image; 207 EFI_HANDLE Controller; 208 EFI_HANDLE Handle; 209 210 EFI_HTTP_PROTOCOL *Http; 211 212 HTTP_IO_CALLBACK Callback; 213 VOID *Context; 214 215 EFI_HTTP_TOKEN ReqToken; 216 EFI_HTTP_MESSAGE ReqMessage; 217 EFI_HTTP_TOKEN RspToken; 218 EFI_HTTP_MESSAGE RspMessage; 219 220 BOOLEAN IsTxDone; 221 BOOLEAN IsRxDone; 222 223 EFI_EVENT TimeoutEvent; 224 } HTTP_IO; 225 226 // 227 // A wrapper structure to hold the received HTTP response data. 228 // 229 typedef struct { 230 EFI_HTTP_RESPONSE_DATA Response; 231 UINTN HeaderCount; 232 EFI_HTTP_HEADER *Headers; 233 UINTN BodyLength; 234 CHAR8 *Body; 235 EFI_STATUS Status; 236 } HTTP_IO_RESPONSE_DATA; 237 238 /** 239 Retrieve the host address using the EFI_DNS6_PROTOCOL. 240 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. 244 245 @retval EFI_SUCCESS Operation succeeded. 246 @retval EFI_DEVICE_ERROR An unexpected network error occurred. 247 @retval Others Other errors as indicated. 248 **/ 249 EFI_STATUS 250 HttpBootDns ( 251 IN HTTP_BOOT_PRIVATE_DATA *Private, 252 IN CHAR16 *HostName, 253 OUT EFI_IPv6_ADDRESS *IpAddress 254 ); 255 256 /** 257 Notify the callback function when an event is triggered. 258 259 @param[in] Event The triggered event. 260 @param[in] Context The opaque parameter to the function. 261 262 **/ 263 VOID 264 EFIAPI 265 HttpBootCommonNotify ( 266 IN EFI_EVENT Event, 267 IN VOID *Context 268 ); 269 270 /** 271 Create a HTTP_IO to access the HTTP service. It will create and configure 272 a HTTP child handle. 273 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. 282 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. 289 290 **/ 291 EFI_STATUS 292 HttpIoCreateIo ( 293 IN EFI_HANDLE Image, 294 IN EFI_HANDLE Controller, 295 IN UINT8 IpVersion, 296 IN HTTP_IO_CONFIG_DATA *ConfigData, 297 IN HTTP_IO_CALLBACK Callback, 298 IN VOID *Context, 299 OUT HTTP_IO *HttpIo 300 ); 301 302 /** 303 Destroy the HTTP_IO and release the resouces. 304 305 @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed. 306 307 **/ 308 VOID 309 HttpIoDestroyIo ( 310 IN HTTP_IO *HttpIo 311 ); 312 313 /** 314 Synchronously send a HTTP REQUEST message to the server. 315 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. 322 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. 328 329 **/ 330 EFI_STATUS 331 HttpIoSendRequest ( 332 IN HTTP_IO *HttpIo, 333 IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL 334 IN UINTN HeaderCount, 335 IN EFI_HTTP_HEADER *Headers, OPTIONAL 336 IN UINTN BodyLength, 337 IN VOID *Body OPTIONAL 338 ); 339 340 /** 341 Synchronously receive a HTTP RESPONSE message from the server. 342 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. 347 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. 353 354 **/ 355 EFI_STATUS 356 HttpIoRecvResponse ( 357 IN HTTP_IO *HttpIo, 358 IN BOOLEAN RecvMsgHeader, 359 OUT HTTP_IO_RESPONSE_DATA *ResponseData 360 ); 361 362 /** 363 This function checks the HTTP(S) URI scheme. 364 365 @param[in] Uri The pointer to the URI string. 366 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. 370 371 **/ 372 EFI_STATUS 373 HttpBootCheckUriScheme ( 374 IN CHAR8 *Uri 375 ); 376 377 /** 378 Get the URI address string from the input device path. 379 380 Caller need to free the buffer in the UriAddress pointer. 381 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. 384 385 @retval EFI_SUCCESS The URI string is returned. 386 @retval EFI_OUT_OF_RESOURCES Failed to allocate memory. 387 388 **/ 389 EFI_STATUS 390 HttpBootParseFilePath ( 391 IN EFI_DEVICE_PATH_PROTOCOL *FilePath, 392 OUT CHAR8 **UriAddress 393 ); 394 395 /** 396 This function returns the image type according to server replied HTTP message 397 and also the image's URI info. 398 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. 404 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. 410 411 **/ 412 EFI_STATUS 413 HttpBootCheckImageType ( 414 IN CHAR8 *Uri, 415 IN VOID *UriParser, 416 IN UINTN HeaderCount, 417 IN EFI_HTTP_HEADER *Headers, 418 OUT HTTP_BOOT_IMAGE_TYPE *ImageType 419 ); 420 421 /** 422 This function register the RAM disk info to the system. 423 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. 428 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. 433 434 **/ 435 EFI_STATUS 436 HttpBootRegisterRamDisk ( 437 IN HTTP_BOOT_PRIVATE_DATA *Private, 438 IN UINTN BufferSize, 439 IN VOID *Buffer, 440 IN HTTP_BOOT_IMAGE_TYPE ImageType 441 ); 442 443 /** 444 Indicate if the HTTP status code indicates a redirection. 445 446 @param[in] StatusCode HTTP status code from server. 447 448 @return TRUE if it's redirection. 449 450 **/ 451 BOOLEAN 452 HttpBootIsHttpRedirectStatusCode ( 453 IN EFI_HTTP_STATUS_CODE StatusCode 454 ); 455 #endif 456