NetworkPkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / NetworkPkg / HttpBootDxe / HttpBootClient.h

/** @file\r
  Declaration of the boot file download function.\r
\r
Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>\r
(C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __EFI_HTTP_BOOT_HTTP_H__\r
#define __EFI_HTTP_BOOT_HTTP_H__\r
\r
#define HTTP_BOOT_REQUEST_TIMEOUT            5000      // 5 seconds in uints of millisecond.\r
#define HTTP_BOOT_RESPONSE_TIMEOUT           5000      // 5 seconds in uints of millisecond.\r
#define HTTP_BOOT_BLOCK_SIZE                 1500\r
\r
\r
\r
#define HTTP_USER_AGENT_EFI_HTTP_BOOT        "UefiHttpBoot/1.0"\r
\r
//\r
// Record the data length and start address of a data block.\r
//\r
typedef struct {\r
  LIST_ENTRY                 Link;        // Link to the EntityDataList in HTTP_BOOT_CACHE_CONTENT\r
  UINT8                      *Block;      // If NULL, the data is in previous data block.\r
  UINT8                      *DataStart;  // Point to somewhere in the Block\r
  UINTN                      DataLength;\r
} HTTP_BOOT_ENTITY_DATA;\r
\r
//\r
// Structure for a cache item\r
//\r
typedef struct {\r
  LIST_ENTRY                 Link;            // Link to the CacheList in driver's private data.\r
  EFI_HTTP_REQUEST_DATA      *RequestData;\r
  HTTP_IO_RESPONSE_DATA      *ResponseData;   // Not include any message-body data.\r
  HTTP_BOOT_IMAGE_TYPE       ImageType;\r
  UINTN                      EntityLength;\r
  LIST_ENTRY                 EntityDataList;  // Entity data (message-body)\r
} HTTP_BOOT_CACHE_CONTENT;\r
\r
//\r
// Callback data for HTTP_BODY_PARSER_CALLBACK()\r
//\r
typedef struct {\r
  EFI_STATUS                 Status;\r
  //\r
  // Cache info.\r
  //\r
  HTTP_BOOT_CACHE_CONTENT    *Cache;\r
  BOOLEAN                    NewBlock;\r
  UINT8                      *Block;\r
\r
  //\r
  // Caller provided buffer to load the file in.\r
  //\r
  UINTN                      CopyedSize;\r
  UINTN                      BufferSize;\r
  UINT8                      *Buffer;\r
\r
  HTTP_BOOT_PRIVATE_DATA     *Private;\r
} HTTP_BOOT_CALLBACK_DATA;\r
\r
/**\r
  Discover all the boot information for boot file.\r
\r
  @param[in, out]    Private        The pointer to the driver's private data.\r
\r
  @retval EFI_SUCCESS          Successfully obtained all the boot information .\r
  @retval Others               Failed to retrieve the boot information.\r
\r
**/\r
EFI_STATUS\r
HttpBootDiscoverBootInfo (\r
  IN OUT HTTP_BOOT_PRIVATE_DATA   *Private\r
  );\r
\r
/**\r
  Create a HttpIo instance for the file download.\r
\r
  @param[in]    Private        The pointer to the driver's private data.\r
\r
  @retval EFI_SUCCESS          Successfully created.\r
  @retval Others               Failed to create HttpIo.\r
\r
**/\r
EFI_STATUS\r
HttpBootCreateHttpIo (\r
  IN     HTTP_BOOT_PRIVATE_DATA       *Private\r
  );\r
\r
/**\r
  This function download the boot file by using UEFI HTTP protocol.\r
\r
  @param[in]       Private         The pointer to the driver's private data.\r
  @param[in]       HeaderOnly      Only request the response header, it could save a lot of time if\r
                                   the caller only want to know the size of the requested file.\r
  @param[in, out]  BufferSize      On input the size of Buffer in bytes. On output with a return\r
                                   code of EFI_SUCCESS, the amount of data transferred to\r
                                   Buffer. On output with a return code of EFI_BUFFER_TOO_SMALL,\r
                                   the size of Buffer required to retrieve the requested file.\r
  @param[out]      Buffer          The memory buffer to transfer the file to. IF Buffer is NULL,\r
                                   then the size of the requested file is returned in\r
                                   BufferSize.\r
  @param[out]      ImageType       The image type of the downloaded file.\r
\r
  @retval EFI_SUCCESS              The file was loaded.\r
  @retval EFI_INVALID_PARAMETER    BufferSize is NULL or Buffer Size is not NULL but Buffer is NULL.\r
  @retval EFI_OUT_OF_RESOURCES     Could not allocate needed resources\r
  @retval EFI_BUFFER_TOO_SMALL     The BufferSize is too small to read the current directory entry.\r
                                   BufferSize has been updated with the size needed to complete\r
                                   the request.\r
  @retval Others                   Unexpected error happened.\r
\r
**/\r
EFI_STATUS\r
HttpBootGetBootFile (\r
  IN     HTTP_BOOT_PRIVATE_DATA   *Private,\r
  IN     BOOLEAN                  HeaderOnly,\r
  IN OUT UINTN                    *BufferSize,\r
     OUT UINT8                    *Buffer,\r
     OUT HTTP_BOOT_IMAGE_TYPE     *ImageType\r
  );\r
\r
/**\r
  Clean up all cached data.\r
\r
  @param[in]          Private         The pointer to the driver's private data.\r
\r
**/\r
VOID\r
HttpBootFreeCacheList (\r
  IN     HTTP_BOOT_PRIVATE_DATA   *Private\r
  );\r
\r
#endif\r