NetworkPkg/HttpUtilitiesDxe/HttpUtilitiesDxe.h

   1 /** @file
   2   The header files of Http Utilities functions for HttpUtilities driver.
   3
   4   Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
   5
   6   This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  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_UTILITIES_DXE_H__
  17 #define __EFI_HTTP_UTILITIES_DXE_H__
  18
  19 #include <Uefi.h>
  20
  21 //
  22 // Libraries
  23 //
  24 #include <Library/UefiBootServicesTableLib.h>
  25 #include <Library/MemoryAllocationLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/BaseLib.h>
  28 #include <Library/UefiLib.h>
  29 #include <Library/DebugLib.h>
  30
  31 //
  32 // Consumed Protocols
  33 //
  34 #include <Protocol/HttpUtilities.h>
  35 #include <Protocol/Http.h>
  36
  37 //
  38 // Protocol instances
  39 //
  40 extern EFI_HTTP_UTILITIES_PROTOCOL mHttpUtilitiesProtocol;
  41
  42
  43 /**
  44   Free existing HeaderFields.
  45
  46   @param[in]  HeaderFields       Pointer to array of key/value header pairs waitting for free.
  47   @param[in]  FieldCount         The number of header pairs in HeaderFields.
  48
  49 **/
  50 VOID
  51 FreeHeaderFields (
  52   IN  EFI_HTTP_HEADER  *HeaderFields,
  53   IN  UINTN            FieldCount
  54   );
  55
  56
  57 /**
  58   Find required header field in HeaderFields.
  59
  60   @param[in]  HeaderFields        Pointer to array of key/value header pairs.
  61   @param[in]  FieldCount          The number of header pairs.
  62   @param[in]  FieldName           Pointer to header field's name.
  63
  64   @return     Pointer to the queried header field.
  65   @return     NULL if not find this required header field.
  66
  67 **/
  68 EFI_HTTP_HEADER *
  69 FindHttpHeader (
  70   IN  EFI_HTTP_HEADER  *HeaderFields,
  71   IN  UINTN            FieldCount,
  72   IN  CHAR8            *FieldName
  73   );
  74
  75
  76 /**
  77   Check whether header field called FieldName is in DeleteList.
  78
  79   @param[in]  DeleteList        Pointer to array of key/value header pairs.
  80   @param[in]  DeleteCount       The number of header pairs.
  81   @param[in]  FieldName         Pointer to header field's name.
  82
  83   @return     TRUE if FieldName is not in DeleteList, that means this header field is valid.
  84   @return     FALSE if FieldName is in DeleteList, that means this header field is invalid.
  85
  86 **/
  87 BOOLEAN
  88 IsValidHttpHeader (
  89   IN  CHAR8            *DeleteList[],
  90   IN  UINTN            DeleteCount,
  91   IN  CHAR8            *FieldName
  92   );
  93
  94
  95 /**
  96   Set FieldName and FieldValue into specified HttpHeader.
  97
  98   @param[in]  HttpHeader          Specified HttpHeader.
  99   @param[in]  FieldName           FieldName of this HttpHeader.
 100   @param[in]  FieldValue          FieldValue of this HttpHeader.
 101
 102
 103   @retval EFI_SUCCESS             The FieldName and FieldValue are set into HttpHeader successfully.
 104   @retval EFI_OUT_OF_RESOURCES    Failed to allocate resources.
 105
 106 **/
 107 EFI_STATUS
 108 SetFieldNameAndValue (
 109   IN  EFI_HTTP_HEADER     *HttpHeader,
 110   IN  CHAR8               *FieldName,
 111   IN  CHAR8               *FieldValue
 112   );
 113
 114
 115 /**
 116   Get one key/value header pair from the raw string.
 117
 118   @param[in]  String             Pointer to the raw string.
 119   @param[out] FieldName          Pointer to header field's name.
 120   @param[out] FieldValue         Pointer to header field's value.
 121
 122   @return     Pointer to the next raw string.
 123   @return     NULL if no key/value header pair from this raw string.
 124
 125 **/
 126 CHAR8 *
 127 GetFieldNameAndValue (
 128   IN  CHAR8   *String,
 129   OUT CHAR8   **FieldName,
 130   OUT CHAR8   **FieldValue
 131   );
 132
 133
 134 /**
 135   Create HTTP header based on a combination of seed header, fields
 136   to delete, and fields to append.
 137
 138   The Build() function is used to manage the headers portion of an
 139   HTTP message by providing the ability to add, remove, or replace
 140   HTTP headers.
 141
 142   @param[in]  This                Pointer to EFI_HTTP_UTILITIES_PROTOCOL instance.
 143   @param[in]  SeedMessageSize     Size of the initial HTTP header. This can be zero.
 144   @param[in]  SeedMessage         Initial HTTP header to be used as a base for
 145                                   building a new HTTP header. If NULL,
 146                                   SeedMessageSize is ignored.
 147   @param[in]  DeleteCount         Number of null-terminated HTTP header field names
 148                                   in DeleteList.
 149   @param[in]  DeleteList          List of null-terminated HTTP header field names to
 150                                   remove from SeedMessage. Only the field names are
 151                                   in this list because the field values are irrelevant
 152                                   to this operation.
 153   @param[in]  AppendCount         Number of header fields in AppendList.
 154   @param[in]  AppendList          List of HTTP headers to populate NewMessage with.
 155                                   If SeedMessage is not NULL, AppendList will be
 156                                   appended to the existing list from SeedMessage in
 157                                   NewMessage.
 158   @param[out] NewMessageSize      Pointer to number of header fields in NewMessage.
 159   @param[out] NewMessage          Pointer to a new list of HTTP headers based on.
 160
 161   @retval EFI_SUCCESS             Add, remove, and replace operations succeeded.
 162   @retval EFI_OUT_OF_RESOURCES    Could not allocate memory for NewMessage.
 163   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 164                                   This is NULL.
 165 **/
 166 EFI_STATUS
 167 EFIAPI
 168 HttpUtilitiesBuild (
 169   IN     EFI_HTTP_UTILITIES_PROTOCOL *This,
 170   IN     UINTN                       SeedMessageSize,
 171   IN     VOID                        *SeedMessage, OPTIONAL
 172   IN     UINTN                       DeleteCount,
 173   IN     CHAR8                       *DeleteList[], OPTIONAL
 174   IN     UINTN                       AppendCount,
 175   IN     EFI_HTTP_HEADER             *AppendList[], OPTIONAL
 176      OUT UINTN                       *NewMessageSize,
 177      OUT VOID                        **NewMessage
 178   );
 179
 180
 181 /**
 182   Parses HTTP header and produces an array of key/value pairs.
 183
 184   The Parse() function is used to transform data stored in HttpHeader
 185   into a list of fields paired with their corresponding values.
 186
 187   @param[in]  This                Pointer to EFI_HTTP_UTILITIES_PROTOCOL instance.
 188   @param[in]  HttpMessage         Contains raw unformatted HTTP header string.
 189   @param[in]  HttpMessageSize     Size of HTTP header.
 190   @param[out] HeaderFields        Array of key/value header pairs.
 191   @param[out] FieldCount          Number of headers in HeaderFields.
 192
 193   @retval EFI_SUCCESS             Allocation succeeded.
 194   @retval EFI_NOT_STARTED         This EFI HTTP Protocol instance has not been
 195                                   initialized.
 196   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is TRUE:
 197                                   This is NULL.
 198                                   HttpMessage is NULL.
 199                                   HeaderFields is NULL.
 200                                   FieldCount is NULL.
 201 **/
 202 EFI_STATUS
 203 EFIAPI
 204 HttpUtilitiesParse (
 205   IN  EFI_HTTP_UTILITIES_PROTOCOL  *This,
 206   IN  CHAR8                        *HttpMessage,
 207   IN  UINTN                        HttpMessageSize,
 208   OUT EFI_HTTP_HEADER              **HeaderFields,
 209   OUT UINTN                        *FieldCount
 210   );
 211
 212 #endif