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