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 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