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