NetworkPkg/HttpBootDxe/HttpBootSupport.h

   1 /** @file
   2   Support functions declaration for UEFI HTTP boot driver.
   3
   4 Copyright (c) 2015 - 2018, 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_CALLBACK_EVENT
 150 ///
 151 typedef enum {
 152   HttpIoRequest,
 153   HttpIoResponse
 154 } HTTP_IO_CALLBACK_EVENT;
 155
 156 /**
 157   HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
 158
 159   @param[in]    EventType      Indicate the Event type that occurs in the current callback.
 160   @param[in]    Message        HTTP message which will be send to, or just received from HTTP server.
 161   @param[in]    Context        The Callback Context pointer.
 162
 163   @retval EFI_SUCCESS          Tells the HttpIo to continue the HTTP process.
 164   @retval Others               Tells the HttpIo to abort the current HTTP process.
 165 **/
 166 typedef
 167 EFI_STATUS
 168 (EFIAPI * HTTP_IO_CALLBACK) (
 169   IN  HTTP_IO_CALLBACK_EVENT    EventType,
 170   IN  EFI_HTTP_MESSAGE          *Message,
 171   IN  VOID                      *Context
 172   );
 173
 174 //
 175 // HTTP_IO configuration data for IPv4
 176 //
 177 typedef struct {
 178   EFI_HTTP_VERSION          HttpVersion;
 179   UINT32                    RequestTimeOut;  // In milliseconds.
 180   UINT32                    ResponseTimeOut; // In milliseconds.
 181   BOOLEAN                   UseDefaultAddress;
 182   EFI_IPv4_ADDRESS          LocalIp;
 183   EFI_IPv4_ADDRESS          SubnetMask;
 184   UINT16                    LocalPort;
 185 } HTTP4_IO_CONFIG_DATA;
 186
 187 //
 188 // HTTP_IO configuration data for IPv6
 189 //
 190 typedef struct {
 191   EFI_HTTP_VERSION          HttpVersion;
 192   UINT32                    RequestTimeOut;  // In milliseconds.
 193   BOOLEAN                   UseDefaultAddress;
 194   EFI_IPv6_ADDRESS          LocalIp;
 195   UINT16                    LocalPort;
 196 } HTTP6_IO_CONFIG_DATA;
 197
 198
 199 //
 200 // HTTP_IO configuration
 201 //
 202 typedef union {
 203   HTTP4_IO_CONFIG_DATA       Config4;
 204   HTTP6_IO_CONFIG_DATA       Config6;
 205 } HTTP_IO_CONFIG_DATA;
 206
 207 //
 208 // HTTP_IO wrapper of the EFI HTTP service.
 209 //
 210 typedef struct {
 211   UINT8                     IpVersion;
 212   EFI_HANDLE                Image;
 213   EFI_HANDLE                Controller;
 214   EFI_HANDLE                Handle;
 215
 216   EFI_HTTP_PROTOCOL         *Http;
 217
 218   HTTP_IO_CALLBACK          Callback;
 219   VOID                      *Context;
 220
 221   EFI_HTTP_TOKEN            ReqToken;
 222   EFI_HTTP_MESSAGE          ReqMessage;
 223   EFI_HTTP_TOKEN            RspToken;
 224   EFI_HTTP_MESSAGE          RspMessage;
 225
 226   BOOLEAN                   IsTxDone;
 227   BOOLEAN                   IsRxDone;
 228
 229   EFI_EVENT                 TimeoutEvent;
 230 } HTTP_IO;
 231
 232 //
 233 // A wrapper structure to hold the received HTTP response data.
 234 //
 235 typedef struct {
 236   EFI_HTTP_RESPONSE_DATA      Response;
 237   UINTN                       HeaderCount;
 238   EFI_HTTP_HEADER             *Headers;
 239   UINTN                       BodyLength;
 240   CHAR8                       *Body;
 241   EFI_STATUS                  Status;
 242 } HTTP_IO_RESPONSE_DATA;
 243
 244 /**
 245   Retrieve the host address using the EFI_DNS6_PROTOCOL.
 246
 247   @param[in]  Private             The pointer to the driver's private data.
 248   @param[in]  HostName            Pointer to buffer containing hostname.
 249   @param[out] IpAddress           On output, pointer to buffer containing IPv6 address.
 250
 251   @retval EFI_SUCCESS             Operation succeeded.
 252   @retval EFI_DEVICE_ERROR        An unexpected network error occurred.
 253   @retval Others                  Other errors as indicated.
 254 **/
 255 EFI_STATUS
 256 HttpBootDns (
 257   IN     HTTP_BOOT_PRIVATE_DATA   *Private,
 258   IN     CHAR16                   *HostName,
 259      OUT EFI_IPv6_ADDRESS         *IpAddress
 260   );
 261
 262 /**
 263   Notify the callback function when an event is triggered.
 264
 265   @param[in]  Event           The triggered event.
 266   @param[in]  Context         The opaque parameter to the function.
 267
 268 **/
 269 VOID
 270 EFIAPI
 271 HttpBootCommonNotify (
 272   IN EFI_EVENT           Event,
 273   IN VOID                *Context
 274   );
 275
 276 /**
 277   Create a HTTP_IO to access the HTTP service. It will create and configure
 278   a HTTP child handle.
 279
 280   @param[in]  Image          The handle of the driver image.
 281   @param[in]  Controller     The handle of the controller.
 282   @param[in]  IpVersion      IP_VERSION_4 or IP_VERSION_6.
 283   @param[in]  ConfigData     The HTTP_IO configuration data.
 284   @param[in]  Callback       Callback function which will be invoked when specified
 285                              HTTP_IO_CALLBACK_EVENT happened.
 286   @param[in]  Context        The Context data which will be passed to the Callback function.
 287   @param[out] HttpIo         The HTTP_IO.
 288
 289   @retval EFI_SUCCESS            The HTTP_IO is created and configured.
 290   @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
 291   @retval EFI_UNSUPPORTED        One or more of the control options are not
 292                                  supported in the implementation.
 293   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 294   @retval Others                 Failed to create the HTTP_IO or configure it.
 295
 296 **/
 297 EFI_STATUS
 298 HttpIoCreateIo (
 299   IN EFI_HANDLE             Image,
 300   IN EFI_HANDLE             Controller,
 301   IN UINT8                  IpVersion,
 302   IN HTTP_IO_CONFIG_DATA    *ConfigData,
 303   IN HTTP_IO_CALLBACK       Callback,
 304   IN VOID                   *Context,
 305   OUT HTTP_IO               *HttpIo
 306   );
 307
 308 /**
 309   Destroy the HTTP_IO and release the resouces.
 310
 311   @param[in]  HttpIo          The HTTP_IO which wraps the HTTP service to be destroyed.
 312
 313 **/
 314 VOID
 315 HttpIoDestroyIo (
 316   IN HTTP_IO                *HttpIo
 317   );
 318
 319 /**
 320   Synchronously send a HTTP REQUEST message to the server.
 321
 322   @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
 323   @param[in]   Request          A pointer to storage such data as URL and HTTP method.
 324   @param[in]   HeaderCount      Number of HTTP header structures in Headers list.
 325   @param[in]   Headers          Array containing list of HTTP headers.
 326   @param[in]   BodyLength       Length in bytes of the HTTP body.
 327   @param[in]   Body             Body associated with the HTTP request.
 328
 329   @retval EFI_SUCCESS            The HTTP request is trasmitted.
 330   @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
 331   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 332   @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
 333   @retval Others                 Other errors as indicated.
 334
 335 **/
 336 EFI_STATUS
 337 HttpIoSendRequest (
 338   IN  HTTP_IO                *HttpIo,
 339   IN  EFI_HTTP_REQUEST_DATA  *Request,      OPTIONAL
 340   IN  UINTN                  HeaderCount,
 341   IN  EFI_HTTP_HEADER        *Headers,      OPTIONAL
 342   IN  UINTN                  BodyLength,
 343   IN  VOID                   *Body          OPTIONAL
 344   );
 345
 346 /**
 347   Synchronously receive a HTTP RESPONSE message from the server.
 348
 349   @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
 350   @param[in]   RecvMsgHeader    TRUE to receive a new HTTP response (from message header).
 351                                 FALSE to continue receive the previous response message.
 352   @param[out]  ResponseData     Point to a wrapper of the received response data.
 353
 354   @retval EFI_SUCCESS            The HTTP response is received.
 355   @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
 356   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 357   @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
 358   @retval Others                 Other errors as indicated.
 359
 360 **/
 361 EFI_STATUS
 362 HttpIoRecvResponse (
 363   IN      HTTP_IO                  *HttpIo,
 364   IN      BOOLEAN                  RecvMsgHeader,
 365      OUT  HTTP_IO_RESPONSE_DATA    *ResponseData
 366   );
 367
 368 /**
 369   This function checks the HTTP(S) URI scheme.
 370
 371   @param[in]    Uri              The pointer to the URI string.
 372
 373   @retval EFI_SUCCESS            The URI scheme is valid.
 374   @retval EFI_INVALID_PARAMETER  The URI scheme is not HTTP or HTTPS.
 375   @retval EFI_ACCESS_DENIED      HTTP is disabled and the URI is HTTP.
 376
 377 **/
 378 EFI_STATUS
 379 HttpBootCheckUriScheme (
 380   IN      CHAR8                  *Uri
 381   );
 382
 383 /**
 384   Get the URI address string from the input device path.
 385
 386   Caller need to free the buffer in the UriAddress pointer.
 387
 388   @param[in]   FilePath         Pointer to the device path which contains a URI device path node.
 389   @param[out]  UriAddress       The URI address string extract from the device path.
 390
 391   @retval EFI_SUCCESS            The URI string is returned.
 392   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 393
 394 **/
 395 EFI_STATUS
 396 HttpBootParseFilePath (
 397   IN     EFI_DEVICE_PATH_PROTOCOL     *FilePath,
 398      OUT CHAR8                        **UriAddress
 399   );
 400
 401 /**
 402   This function returns the image type according to server replied HTTP message
 403   and also the image's URI info.
 404
 405   @param[in]    Uri              The pointer to the image's URI string.
 406   @param[in]    UriParser        URI Parse result returned by NetHttpParseUrl().
 407   @param[in]    HeaderCount      Number of HTTP header structures in Headers list.
 408   @param[in]    Headers          Array containing list of HTTP headers.
 409   @param[out]   ImageType        The image type of the downloaded file.
 410
 411   @retval EFI_SUCCESS            The image type is returned in ImageType.
 412   @retval EFI_INVALID_PARAMETER  ImageType, Uri or UriParser is NULL.
 413   @retval EFI_INVALID_PARAMETER  HeaderCount is not zero, and Headers is NULL.
 414   @retval EFI_NOT_FOUND          Failed to identify the image type.
 415   @retval Others                 Unexpect error happened.
 416
 417 **/
 418 EFI_STATUS
 419 HttpBootCheckImageType (
 420   IN      CHAR8                  *Uri,
 421   IN      VOID                   *UriParser,
 422   IN      UINTN                  HeaderCount,
 423   IN      EFI_HTTP_HEADER        *Headers,
 424      OUT  HTTP_BOOT_IMAGE_TYPE   *ImageType
 425   );
 426
 427 /**
 428   This function register the RAM disk info to the system.
 429
 430   @param[in]       Private         The pointer to the driver's private data.
 431   @param[in]       BufferSize      The size of Buffer in bytes.
 432   @param[in]       Buffer          The base address of the RAM disk.
 433   @param[in]       ImageType       The image type of the file in Buffer.
 434
 435   @retval EFI_SUCCESS              The RAM disk has been registered.
 436   @retval EFI_NOT_FOUND            No RAM disk protocol instances were found.
 437   @retval EFI_UNSUPPORTED          The ImageType is not supported.
 438   @retval Others                   Unexpected error happened.
 439
 440 **/
 441 EFI_STATUS
 442 HttpBootRegisterRamDisk (
 443   IN  HTTP_BOOT_PRIVATE_DATA       *Private,
 444   IN  UINTN                        BufferSize,
 445   IN  VOID                         *Buffer,
 446   IN  HTTP_BOOT_IMAGE_TYPE         ImageType
 447   );
 448
 449 /**
 450   Indicate if the HTTP status code indicates a redirection.
 451
 452   @param[in]  StatusCode      HTTP status code from server.
 453
 454   @return                     TRUE if it's redirection.
 455
 456 **/
 457 BOOLEAN
 458 HttpBootIsHttpRedirectStatusCode (
 459   IN   EFI_HTTP_STATUS_CODE        StatusCode
 460   );
 461 #endif