NetworkPkg/HttpBootDxe/HttpBootSupport.h

   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 // HTTP_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_RESPONSE_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 response 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_RESPONSE_DATA    *ResponseData
 318   );
 319
 320 #endif