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   This function is to convert UINTN to ASCII string with the required formatting.
  34
  35   @param[in]  Number         Numeric value to be converted.
  36   @param[in]  Buffer         The pointer to the buffer for ASCII string.
  37   @param[in]  Length         The length of the required format.
  38
  39 **/
  40 VOID
  41 HttpBootUintnToAscDecWithFormat (
  42   IN UINTN                       Number,
  43   IN UINT8                       *Buffer,
  44   IN INTN                        Length
  45   );
  46
  47
  48 /**
  49   This function is to display the IPv4 address.
  50
  51   @param[in]  Ip        The pointer to the IPv4 address.
  52
  53 **/
  54 VOID
  55 HttpBootShowIp4Addr (
  56   IN EFI_IPv4_ADDRESS   *Ip
  57   );
  58
  59 //
  60 // A wrapper structure to hold the HTTP headers.
  61 //
  62 typedef struct {
  63   UINTN                       MaxHeaderCount;
  64   UINTN                       HeaderCount;
  65   EFI_HTTP_HEADER             *Headers;
  66 } HTTP_IO_HEADER;
  67
  68 /**
  69   Create a HTTP_IO_HEADER to hold the HTTP header items.
  70
  71   @param[in]  MaxHeaderCount         The maximun number of HTTP header in this holder.
  72
  73   @return    A pointer of the HTTP header holder or NULL if failed.
  74
  75 **/
  76 HTTP_IO_HEADER *
  77 HttpBootCreateHeader (
  78   IN  UINTN                MaxHeaderCount
  79   );
  80
  81 /**
  82   Destroy the HTTP_IO_HEADER and release the resouces.
  83
  84   @param[in]  HttpIoHeader       Point to the HTTP header holder to be destroyed.
  85
  86 **/
  87 VOID
  88 HttpBootFreeHeader (
  89   IN  HTTP_IO_HEADER       *HttpIoHeader
  90   );
  91
  92 /**
  93   Set or update a HTTP header with the field name and corresponding value.
  94
  95   @param[in]  HttpIoHeader       Point to the HTTP header holder.
  96   @param[in]  FieldName          Null terminated string which describes a field name.
  97   @param[in]  FieldValue         Null terminated string which describes the corresponding field value.
  98
  99   @retval  EFI_SUCCESS           The HTTP header has been set or updated.
 100   @retval  EFI_INVALID_PARAMETER Any input parameter is invalid.
 101   @retval  EFI_OUT_OF_RESOURCES  Insufficient resource to complete the operation.
 102   @retval  Other                 Unexpected error happened.
 103
 104 **/
 105 EFI_STATUS
 106 HttpBootSetHeader (
 107   IN  HTTP_IO_HEADER       *HttpIoHeader,
 108   IN  CHAR8                *FieldName,
 109   IN  CHAR8                *FieldValue
 110   );
 111
 112 //
 113 // HTTP_IO configuration data for IPv4
 114 //
 115 typedef struct {
 116   EFI_HTTP_VERSION          HttpVersion;
 117   UINT32                    RequestTimeOut;  // In milliseconds.
 118   UINT32                    ResponseTimeOut; // In milliseconds.
 119   BOOLEAN                   UseDefaultAddress;
 120   EFI_IPv4_ADDRESS          LocalIp;
 121   EFI_IPv4_ADDRESS          SubnetMask;
 122   UINT16                    LocalPort;
 123 } HTTP4_IO_CONFIG_DATA;
 124
 125 //
 126 // HTTP_IO configuration
 127 //
 128 typedef union {
 129   HTTP4_IO_CONFIG_DATA       Config4;
 130 } HTTP_IO_CONFIG_DATA;
 131
 132 //
 133 // HTTO_IO wrapper of the EFI HTTP service.
 134 //
 135 typedef struct {
 136   UINT8                     IpVersion;
 137   EFI_HANDLE                Image;
 138   EFI_HANDLE                Controller;
 139   EFI_HANDLE                Handle;
 140
 141   EFI_HTTP_PROTOCOL         *Http;
 142
 143   EFI_HTTP_TOKEN            ReqToken;
 144   EFI_HTTP_MESSAGE          ReqMessage;
 145   EFI_HTTP_TOKEN            RspToken;
 146   EFI_HTTP_MESSAGE          RspMessage;
 147
 148   BOOLEAN                   IsTxDone;
 149   BOOLEAN                   IsRxDone;
 150 } HTTP_IO;
 151
 152 //
 153 // A wrapper structure to hold the received HTTP response data.
 154 //
 155 typedef struct {
 156   EFI_HTTP_RESPONSE_DATA      Response;
 157   UINTN                       HeaderCount;
 158   EFI_HTTP_HEADER             *Headers;
 159   UINTN                       BodyLength;
 160   CHAR8                       *Body;
 161 } HTTP_IO_RESOPNSE_DATA;
 162
 163 /**
 164   Create a HTTP_IO to access the HTTP service. It will create and configure
 165   a HTTP child handle.
 166
 167   @param[in]  Image          The handle of the driver image.
 168   @param[in]  Controller     The handle of the controller.
 169   @param[in]  IpVersion      IP_VERSION_4 or IP_VERSION_6.
 170   @param[in]  ConfigData     The HTTP_IO configuration data.
 171   @param[out] HttpIo         The HTTP_IO.
 172
 173   @retval EFI_SUCCESS            The HTTP_IO is created and configured.
 174   @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
 175   @retval EFI_UNSUPPORTED        One or more of the control options are not
 176                                  supported in the implementation.
 177   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 178   @retval Others                 Failed to create the HTTP_IO or configure it.
 179
 180 **/
 181 EFI_STATUS
 182 HttpIoCreateIo (
 183   IN EFI_HANDLE             Image,
 184   IN EFI_HANDLE             Controller,
 185   IN UINT8                  IpVersion,
 186   IN HTTP_IO_CONFIG_DATA    *ConfigData,
 187   OUT HTTP_IO               *HttpIo
 188   );
 189
 190 /**
 191   Destroy the HTTP_IO and release the resouces.
 192
 193   @param[in]  HttpIo          The HTTP_IO which wraps the HTTP service to be destroyed.
 194
 195 **/
 196 VOID
 197 HttpIoDestroyIo (
 198   IN HTTP_IO                *HttpIo
 199   );
 200
 201 /**
 202   Synchronously send a HTTP REQUEST message to the server.
 203
 204   @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
 205   @param[in]   Request          A pointer to storage such data as URL and HTTP method.
 206   @param[in]   HeaderCount      Number of HTTP header structures in Headers list.
 207   @param[in]   Headers          Array containing list of HTTP headers.
 208   @param[in]   BodyLength       Length in bytes of the HTTP body.
 209   @param[in]   Body             Body associated with the HTTP request.
 210
 211   @retval EFI_SUCCESS            The HTTP request is trasmitted.
 212   @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
 213   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 214   @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
 215   @retval Others                 Other errors as indicated.
 216
 217 **/
 218 EFI_STATUS
 219 HttpIoSendRequest (
 220   IN  HTTP_IO                *HttpIo,
 221   IN  EFI_HTTP_REQUEST_DATA  *Request,      OPTIONAL
 222   IN  UINTN                  HeaderCount,
 223   IN  EFI_HTTP_HEADER        *Headers,      OPTIONAL
 224   IN  UINTN                  BodyLength,
 225   IN  VOID                   *Body          OPTIONAL
 226   );
 227
 228 /**
 229   Synchronously receive a HTTP RESPONSE message from the server.
 230
 231   @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
 232   @param[in]   RecvMsgHeader    TRUE to receive a new HTTP response (from message header).
 233                                 FALSE to continue receive the previous response message.
 234   @param[out]  ResponseData     Point to a wrapper of the received response data.
 235
 236   @retval EFI_SUCCESS            The HTTP resopnse is received.
 237   @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
 238   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 239   @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
 240   @retval Others                 Other errors as indicated.
 241
 242 **/
 243 EFI_STATUS
 244 HttpIoRecvResponse (
 245   IN      HTTP_IO                  *HttpIo,
 246   IN      BOOLEAN                  RecvMsgHeader,
 247      OUT  HTTP_IO_RESOPNSE_DATA    *ResponseData
 248   );
 249
 250 #endif