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   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   Retrieve the host address using the EFI_DNS6_PROTOCOL.
  91
  92   @param[in]  Private             The pointer to the driver's private data.
  93   @param[in]  HostName            Pointer to buffer containing hostname.
  94   @param[out] IpAddress           On output, pointer to buffer containing IPv6 address.
  95
  96   @retval EFI_SUCCESS             Operation succeeded.
  97   @retval EFI_DEVICE_ERROR        An unexpected network error occurred.
  98   @retval Others                  Other errors as indicated.
  99 **/
 100 EFI_STATUS
 101 HttpBootDns (
 102   IN     HTTP_BOOT_PRIVATE_DATA  *Private,
 103   IN     CHAR16                  *HostName,
 104   OUT EFI_IPv6_ADDRESS           *IpAddress
 105   );
 106
 107 /**
 108   Notify the callback function when an event is triggered.
 109
 110   @param[in]  Event           The triggered event.
 111   @param[in]  Context         The opaque parameter to the function.
 112
 113 **/
 114 VOID
 115 EFIAPI
 116 HttpBootCommonNotify (
 117   IN EFI_EVENT  Event,
 118   IN VOID       *Context
 119   );
 120
 121 /**
 122   This function checks the HTTP(S) URI scheme.
 123
 124   @param[in]    Uri              The pointer to the URI string.
 125
 126   @retval EFI_SUCCESS            The URI scheme is valid.
 127   @retval EFI_INVALID_PARAMETER  The URI scheme is not HTTP or HTTPS.
 128   @retval EFI_ACCESS_DENIED      HTTP is disabled and the URI is HTTP.
 129
 130 **/
 131 EFI_STATUS
 132 HttpBootCheckUriScheme (
 133   IN      CHAR8  *Uri
 134   );
 135
 136 /**
 137   Get the URI address string from the input device path.
 138
 139   Caller need to free the buffer in the UriAddress pointer.
 140
 141   @param[in]   FilePath         Pointer to the device path which contains a URI device path node.
 142   @param[out]  UriAddress       The URI address string extract from the device path.
 143
 144   @retval EFI_SUCCESS            The URI string is returned.
 145   @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
 146
 147 **/
 148 EFI_STATUS
 149 HttpBootParseFilePath (
 150   IN     EFI_DEVICE_PATH_PROTOCOL  *FilePath,
 151   OUT CHAR8                        **UriAddress
 152   );
 153
 154 /**
 155   This function returns the image type according to server replied HTTP message
 156   and also the image's URI info.
 157
 158   @param[in]    Uri              The pointer to the image's URI string.
 159   @param[in]    UriParser        URI Parse result returned by NetHttpParseUrl().
 160   @param[in]    HeaderCount      Number of HTTP header structures in Headers list.
 161   @param[in]    Headers          Array containing list of HTTP headers.
 162   @param[out]   ImageType        The image type of the downloaded file.
 163
 164   @retval EFI_SUCCESS            The image type is returned in ImageType.
 165   @retval EFI_INVALID_PARAMETER  ImageType, Uri or UriParser is NULL.
 166   @retval EFI_INVALID_PARAMETER  HeaderCount is not zero, and Headers is NULL.
 167   @retval EFI_NOT_FOUND          Failed to identify the image type.
 168   @retval Others                 Unexpected error happened.
 169
 170 **/
 171 EFI_STATUS
 172 HttpBootCheckImageType (
 173   IN      CHAR8              *Uri,
 174   IN      VOID               *UriParser,
 175   IN      UINTN              HeaderCount,
 176   IN      EFI_HTTP_HEADER    *Headers,
 177   OUT  HTTP_BOOT_IMAGE_TYPE  *ImageType
 178   );
 179
 180 /**
 181   This function register the RAM disk info to the system.
 182
 183   @param[in]       Private         The pointer to the driver's private data.
 184   @param[in]       BufferSize      The size of Buffer in bytes.
 185   @param[in]       Buffer          The base address of the RAM disk.
 186   @param[in]       ImageType       The image type of the file in Buffer.
 187
 188   @retval EFI_SUCCESS              The RAM disk has been registered.
 189   @retval EFI_NOT_FOUND            No RAM disk protocol instances were found.
 190   @retval EFI_UNSUPPORTED          The ImageType is not supported.
 191   @retval Others                   Unexpected error happened.
 192
 193 **/
 194 EFI_STATUS
 195 HttpBootRegisterRamDisk (
 196   IN  HTTP_BOOT_PRIVATE_DATA  *Private,
 197   IN  UINTN                   BufferSize,
 198   IN  VOID                    *Buffer,
 199   IN  HTTP_BOOT_IMAGE_TYPE    ImageType
 200   );
 201
 202 /**
 203   Indicate if the HTTP status code indicates a redirection.
 204
 205   @param[in]  StatusCode      HTTP status code from server.
 206
 207   @return                     TRUE if it's redirection.
 208
 209 **/
 210 BOOLEAN
 211 HttpBootIsHttpRedirectStatusCode (
 212   IN   EFI_HTTP_STATUS_CODE  StatusCode
 213   );
 214
 215 #endif