NetworkPkg/HttpBootDxe/HttpBootClient.h

   1 /** @file
   2   Declaration of the boot file download function.
   3
   4 Copyright (c) 2015 - 2021, Intel Corporation. All rights reserved.<BR>
   5 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __EFI_HTTP_BOOT_HTTP_H__
  11 #define __EFI_HTTP_BOOT_HTTP_H__
  12
  13 #define HTTP_BOOT_BLOCK_SIZE                   1500
  14 #define HTTP_USER_AGENT_EFI_HTTP_BOOT          "UefiHttpBoot/1.0"
  15 #define HTTP_BOOT_AUTHENTICATION_INFO_MAX_LEN  255
  16
  17 //
  18 // Record the data length and start address of a data block.
  19 //
  20 typedef struct {
  21   LIST_ENTRY    Link;                     // Link to the EntityDataList in HTTP_BOOT_CACHE_CONTENT
  22   UINT8         *Block;                   // If NULL, the data is in previous data block.
  23   UINT8         *DataStart;               // Point to somewhere in the Block
  24   UINTN         DataLength;
  25 } HTTP_BOOT_ENTITY_DATA;
  26
  27 //
  28 // Structure for a cache item
  29 //
  30 typedef struct {
  31   LIST_ENTRY               Link;              // Link to the CacheList in driver's private data.
  32   EFI_HTTP_REQUEST_DATA    *RequestData;
  33   HTTP_IO_RESPONSE_DATA    *ResponseData;     // Not include any message-body data.
  34   HTTP_BOOT_IMAGE_TYPE     ImageType;
  35   UINTN                    EntityLength;
  36   LIST_ENTRY               EntityDataList;    // Entity data (message-body)
  37 } HTTP_BOOT_CACHE_CONTENT;
  38
  39 //
  40 // Callback data for HTTP_BODY_PARSER_CALLBACK()
  41 //
  42 typedef struct {
  43   EFI_STATUS                 Status;
  44   //
  45   // Cache info.
  46   //
  47   HTTP_BOOT_CACHE_CONTENT    *Cache;
  48   BOOLEAN                    NewBlock;
  49   UINT8                      *Block;
  50
  51   //
  52   // Caller provided buffer to load the file in.
  53   //
  54   UINTN                      CopyedSize;
  55   UINTN                      BufferSize;
  56   UINT8                      *Buffer;
  57
  58   HTTP_BOOT_PRIVATE_DATA     *Private;
  59 } HTTP_BOOT_CALLBACK_DATA;
  60
  61 /**
  62   Discover all the boot information for boot file.
  63
  64   @param[in, out]    Private        The pointer to the driver's private data.
  65
  66   @retval EFI_SUCCESS          Successfully obtained all the boot information .
  67   @retval Others               Failed to retrieve the boot information.
  68
  69 **/
  70 EFI_STATUS
  71 HttpBootDiscoverBootInfo (
  72   IN OUT HTTP_BOOT_PRIVATE_DATA  *Private
  73   );
  74
  75 /**
  76   Create a HttpIo instance for the file download.
  77
  78   @param[in]    Private        The pointer to the driver's private data.
  79
  80   @retval EFI_SUCCESS          Successfully created.
  81   @retval Others               Failed to create HttpIo.
  82
  83 **/
  84 EFI_STATUS
  85 HttpBootCreateHttpIo (
  86   IN     HTTP_BOOT_PRIVATE_DATA  *Private
  87   );
  88
  89 /**
  90   This function download the boot file by using UEFI HTTP protocol.
  91
  92   @param[in]       Private         The pointer to the driver's private data.
  93   @param[in]       HeaderOnly      Only request the response header, it could save a lot of time if
  94                                    the caller only want to know the size of the requested file.
  95   @param[in, out]  BufferSize      On input the size of Buffer in bytes. On output with a return
  96                                    code of EFI_SUCCESS, the amount of data transferred to
  97                                    Buffer. On output with a return code of EFI_BUFFER_TOO_SMALL,
  98                                    the size of Buffer required to retrieve the requested file.
  99   @param[out]      Buffer          The memory buffer to transfer the file to. IF Buffer is NULL,
 100                                    then the size of the requested file is returned in
 101                                    BufferSize.
 102   @param[out]      ImageType       The image type of the downloaded file.
 103
 104   @retval EFI_SUCCESS              The file was loaded.
 105   @retval EFI_INVALID_PARAMETER    BufferSize is NULL or Buffer Size is not NULL but Buffer is NULL.
 106   @retval EFI_OUT_OF_RESOURCES     Could not allocate needed resources
 107   @retval EFI_BUFFER_TOO_SMALL     The BufferSize is too small to read the current directory entry.
 108                                    BufferSize has been updated with the size needed to complete
 109                                    the request.
 110   @retval EFI_ACCESS_DENIED        The server needs to authenticate the client.
 111   @retval Others                   Unexpected error happened.
 112
 113 **/
 114 EFI_STATUS
 115 HttpBootGetBootFile (
 116   IN     HTTP_BOOT_PRIVATE_DATA  *Private,
 117   IN     BOOLEAN                 HeaderOnly,
 118   IN OUT UINTN                   *BufferSize,
 119   OUT UINT8                      *Buffer,
 120   OUT HTTP_BOOT_IMAGE_TYPE       *ImageType
 121   );
 122
 123 /**
 124   Clean up all cached data.
 125
 126   @param[in]          Private         The pointer to the driver's private data.
 127
 128 **/
 129 VOID
 130 HttpBootFreeCacheList (
 131   IN     HTTP_BOOT_PRIVATE_DATA  *Private
 132   );
 133
 134 #endif