NetworkPkg/HttpBootDxe/HttpBootClient.h

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