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 (C) Copyright 2020 Hewlett-Packard Development Company, L.P.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __EFI_HTTP_BOOT_SUPPORT_H__
  11 #define __EFI_HTTP_BOOT_SUPPORT_H__
  12
  13 /**
  14   Get the Nic handle using any child handle in the IPv4 stack.
  15
  16   @param[in]  ControllerHandle    Pointer to child handle over IPv4.
  17
  18   @return NicHandle               The pointer to the Nic handle.
  19   @return NULL                    Can't find the Nic handle.
  20
  21 **/
  22 EFI_HANDLE
  23 HttpBootGetNicByIp4Children (
  24   IN EFI_HANDLE                 ControllerHandle
  25   );
  26
  27 /**
  28   Get the Nic handle using any child handle in the IPv6 stack.
  29
  30   @param[in]  ControllerHandle    Pointer to child handle over IPv6.
  31
  32   @return NicHandle               The pointer to the Nic handle.
  33   @return NULL                    Can't find the Nic handle.
  34
  35 **/
  36 EFI_HANDLE
  37 HttpBootGetNicByIp6Children (
  38   IN EFI_HANDLE                 ControllerHandle
  39   );
  40
  41 /**
  42   This function is to convert UINTN to ASCII string with the required formatting.
  43
  44   @param[in]  Number         Numeric value to be converted.
  45   @param[in]  Buffer         The pointer to the buffer for ASCII string.
  46   @param[in]  Length         The length of the required format.
  47
  48 **/
  49 VOID
  50 HttpBootUintnToAscDecWithFormat (
  51   IN UINTN                       Number,
  52   IN UINT8                       *Buffer,
  53   IN INTN                        Length
  54   );
  55
  56
  57 /**
  58   This function is to display the IPv4 address.
  59
  60   @param[in]  Ip        The pointer to the IPv4 address.
  61
  62 **/
  63 VOID
  64 HttpBootShowIp4Addr (
  65   IN EFI_IPv4_ADDRESS   *Ip
  66   );
  67
  68 /**
  69   This function is to display the IPv6 address.
  70
  71   @param[in]  Ip        The pointer to the IPv6 address.
  72
  73 **/
  74 VOID
  75 HttpBootShowIp6Addr (
  76   IN EFI_IPv6_ADDRESS   *Ip
  77   );
  78
  79 /**
  80   This function is to display the HTTP error status.
  81
  82   @param[in]      StatusCode      The status code value in HTTP message.
  83
  84 **/
  85 VOID
  86 HttpBootPrintErrorMessage (
  87   EFI_HTTP_STATUS_CODE            StatusCode
  88   );
  89
  90 //
  91 // A wrapper structure to hold the HTTP headers.
  92 //
  93 typedef struct {
  94   UINTN                       MaxHeaderCount;
  95   UINTN                       HeaderCount;
  96   EFI_HTTP_HEADER             *Headers;
  97 } HTTP_IO_HEADER;
  98
  99 /**
 100   Create a HTTP_IO_HEADER to hold the HTTP header items.
 101
 102   @param[in]  MaxHeaderCount         The maximum number of HTTP header in this holder.
 103
 104   @return    A pointer of the HTTP header holder or NULL if failed.
 105
 106 **/
 107 HTTP_IO_HEADER *
 108 HttpBootCreateHeader (
 109   IN  UINTN                MaxHeaderCount
 110   );
 111
 112 /**
 113   Destroy the HTTP_IO_HEADER and release the resources.
 114
 115   @param[in]  HttpIoHeader       Point to the HTTP header holder to be destroyed.
 116
 117 **/
 118 VOID
 119 HttpBootFreeHeader (
 120   IN  HTTP_IO_HEADER       *HttpIoHeader
 121   );
 122
 123 /**
 124   Set or update a HTTP header with the field name and corresponding value.
 125
 126   @param[in]  HttpIoHeader       Point to the HTTP header holder.
 127   @param[in]  FieldName          Null terminated string which describes a field name.
 128   @param[in]  FieldValue         Null terminated string which describes the corresponding field value.
 129
 130   @retval  EFI_SUCCESS           The HTTP header has been set or updated.
 131   @retval  EFI_INVALID_PARAMETER Any input parameter is invalid.
 132   @retval  EFI_OUT_OF_RESOURCES  Insufficient resource to complete the operation.
 133   @retval  Other                 Unexpected error happened.
 134
 135 **/
 136 EFI_STATUS
 137 HttpBootSetHeader (
 138   IN  HTTP_IO_HEADER       *HttpIoHeader,
 139   IN  CHAR8                *FieldName,
 140   IN  CHAR8                *FieldValue
 141   );
 142
 143 /**
 144   Retrieve the host address using the EFI_DNS6_PROTOCOL.
 145
 146   @param[in]  Private             The pointer to the driver's private data.
 147   @param[in]  HostName            Pointer to buffer containing hostname.
 148   @param[out] IpAddress           On output, pointer to buffer containing IPv6 address.
 149
 150   @retval EFI_SUCCESS             Operation succeeded.
 151   @retval EFI_DEVICE_ERROR        An unexpected network error occurred.
 152   @retval Others                  Other errors as indicated.
 153 **/
 154 EFI_STATUS
 155 HttpBootDns (
 156   IN     HTTP_BOOT_PRIVATE_DATA   *Private,
 157   IN     CHAR16                   *HostName,
 158      OUT EFI_IPv6_ADDRESS         *IpAddress
 159   );
 160
 161 /**
 162   Notify the callback function when an event is triggered.
 163
 164   @param[in]  Event           The triggered event.
 165   @param[in]  Context         The opaque parameter to the function.
 166
 167 **/
 168 VOID
 169 EFIAPI
 170 HttpBootCommonNotify (
 171   IN EFI_EVENT           Event,
 172   IN VOID                *Context
 173   );
 174
 175 /**
 176   This function checks the HTTP(S) URI scheme.
 177
 178   @param[in]    Uri              The pointer to the URI string.
 179
 180   @retval EFI_SUCCESS            The URI scheme is valid.
 181   @retval EFI_INVALID_PARAMETER  The URI scheme is not HTTP or HTTPS.
 182   @retval EFI_ACCESS_DENIED      HTTP is disabled and the URI is HTTP.
 183
 184 **/
 185 EFI_STATUS
 186 HttpBootCheckUriScheme (
 187   IN      CHAR8                  *Uri
 188   );
 189
 190 /**
 191   Get the URI address string from the input device path.
 192
 193   Caller need to free the buffer in the UriAddress pointer.
 194
 195   @param[in]   FilePath         Pointer to the device path which contains a URI device path node.
 196   @param[out]  UriAddress       The URI address string extract from the device path.
 197
 198   @retval EFI_SUCCESS            The URI string is returned.
 199   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 200
 201 **/
 202 EFI_STATUS
 203 HttpBootParseFilePath (
 204   IN     EFI_DEVICE_PATH_PROTOCOL     *FilePath,
 205      OUT CHAR8                        **UriAddress
 206   );
 207
 208 /**
 209   This function returns the image type according to server replied HTTP message
 210   and also the image's URI info.
 211
 212   @param[in]    Uri              The pointer to the image's URI string.
 213   @param[in]    UriParser        URI Parse result returned by NetHttpParseUrl().
 214   @param[in]    HeaderCount      Number of HTTP header structures in Headers list.
 215   @param[in]    Headers          Array containing list of HTTP headers.
 216   @param[out]   ImageType        The image type of the downloaded file.
 217
 218   @retval EFI_SUCCESS            The image type is returned in ImageType.
 219   @retval EFI_INVALID_PARAMETER  ImageType, Uri or UriParser is NULL.
 220   @retval EFI_INVALID_PARAMETER  HeaderCount is not zero, and Headers is NULL.
 221   @retval EFI_NOT_FOUND          Failed to identify the image type.
 222   @retval Others                 Unexpected error happened.
 223
 224 **/
 225 EFI_STATUS
 226 HttpBootCheckImageType (
 227   IN      CHAR8                  *Uri,
 228   IN      VOID                   *UriParser,
 229   IN      UINTN                  HeaderCount,
 230   IN      EFI_HTTP_HEADER        *Headers,
 231      OUT  HTTP_BOOT_IMAGE_TYPE   *ImageType
 232   );
 233
 234 /**
 235   This function register the RAM disk info to the system.
 236
 237   @param[in]       Private         The pointer to the driver's private data.
 238   @param[in]       BufferSize      The size of Buffer in bytes.
 239   @param[in]       Buffer          The base address of the RAM disk.
 240   @param[in]       ImageType       The image type of the file in Buffer.
 241
 242   @retval EFI_SUCCESS              The RAM disk has been registered.
 243   @retval EFI_NOT_FOUND            No RAM disk protocol instances were found.
 244   @retval EFI_UNSUPPORTED          The ImageType is not supported.
 245   @retval Others                   Unexpected error happened.
 246
 247 **/
 248 EFI_STATUS
 249 HttpBootRegisterRamDisk (
 250   IN  HTTP_BOOT_PRIVATE_DATA       *Private,
 251   IN  UINTN                        BufferSize,
 252   IN  VOID                         *Buffer,
 253   IN  HTTP_BOOT_IMAGE_TYPE         ImageType
 254   );
 255
 256 /**
 257   Indicate if the HTTP status code indicates a redirection.
 258
 259   @param[in]  StatusCode      HTTP status code from server.
 260
 261   @return                     TRUE if it's redirection.
 262
 263 **/
 264 BOOLEAN
 265 HttpBootIsHttpRedirectStatusCode (
 266   IN   EFI_HTTP_STATUS_CODE        StatusCode
 267   );
 268 #endif