system76-edk2/NetworkPkg/Include/Library/HttpIoLib.h

/** @file
  HttpIoLib.h.

(C) Copyright 2020 Hewlett-Packard Development Company, L.P.<BR>
SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#ifndef HTTP_IO_LIB_H_
#define HTTP_IO_LIB_H_

#include <IndustryStandard/Http11.h>

#include <Library/DpcLib.h>
#include <Library/HttpLib.h>
#include <Library/NetLib.h>

#define HTTP_IO_MAX_SEND_PAYLOAD                     1024
#define HTTP_IO_CHUNK_SIZE_STRING_LEN                50
#define HTTP_IO_CHUNKED_TRANSFER_CODING_DATA_LENGTH  256

///
/// HTTP_IO_CALLBACK_EVENT
///
typedef enum {
  HttpIoRequest,
  HttpIoResponse
} HTTP_IO_CALLBACK_EVENT;

/**
  HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.

  @param[in]    EventType      Indicate the Event type that occurs in the current callback.
  @param[in]    Message        HTTP message which will be send to, or just received from HTTP server.
  @param[in]    Context        The Callback Context pointer.

  @retval EFI_SUCCESS          Tells the HttpIo to continue the HTTP process.
  @retval Others               Tells the HttpIo to abort the current HTTP process.
**/
typedef
EFI_STATUS
(EFIAPI *HTTP_IO_CALLBACK)(
  IN  HTTP_IO_CALLBACK_EVENT    EventType,
  IN  EFI_HTTP_MESSAGE          *Message,
  IN  VOID                      *Context
  );

///
/// A wrapper structure to hold the received HTTP response data.
///
typedef struct {
  EFI_HTTP_RESPONSE_DATA    Response;
  UINTN                     HeaderCount;
  EFI_HTTP_HEADER           *Headers;
  UINTN                     BodyLength;
  CHAR8                     *Body;
  EFI_STATUS                Status;
} HTTP_IO_RESPONSE_DATA;

///
/// HTTP_IO configuration data for IPv4
///
typedef struct {
  EFI_HTTP_VERSION    HttpVersion;
  UINT32              RequestTimeOut;        ///< In milliseconds.
  UINT32              ResponseTimeOut;       ///< In milliseconds.
  BOOLEAN             UseDefaultAddress;
  EFI_IPv4_ADDRESS    LocalIp;
  EFI_IPv4_ADDRESS    SubnetMask;
  UINT16              LocalPort;
} HTTP4_IO_CONFIG_DATA;

///
/// HTTP_IO configuration data for IPv6
///
typedef struct {
  EFI_HTTP_VERSION    HttpVersion;
  UINT32              RequestTimeOut;        ///< In milliseconds.
  BOOLEAN             UseDefaultAddress;
  EFI_IPv6_ADDRESS    LocalIp;
  UINT16              LocalPort;
} HTTP6_IO_CONFIG_DATA;

///
/// HTTP_IO configuration
///
typedef union {
  HTTP4_IO_CONFIG_DATA    Config4;
  HTTP6_IO_CONFIG_DATA    Config6;
} HTTP_IO_CONFIG_DATA;

///
/// HTTP_IO wrapper of the EFI HTTP service.
///
typedef struct {
  UINT8                IpVersion;
  EFI_HANDLE           Image;
  EFI_HANDLE           Controller;
  EFI_HANDLE           Handle;

  EFI_HTTP_PROTOCOL    *Http;

  HTTP_IO_CALLBACK     Callback;
  VOID                 *Context;

  EFI_HTTP_TOKEN       ReqToken;
  EFI_HTTP_MESSAGE     ReqMessage;
  EFI_HTTP_TOKEN       RspToken;
  EFI_HTTP_MESSAGE     RspMessage;

  BOOLEAN              IsTxDone;
  BOOLEAN              IsRxDone;

  EFI_EVENT            TimeoutEvent;
  UINT32               Timeout;
} HTTP_IO;

///
/// Process code of HTTP chunk transfer.
///
typedef enum  {
  HttpIoSendChunkNone = 0,
  HttpIoSendChunkHeaderZeroContent,
  HttpIoSendChunkContent,
  HttpIoSendChunkEndChunk,
  HttpIoSendChunkFinish
} HTTP_IO_SEND_CHUNK_PROCESS;

///
/// Process code of HTTP non chunk transfer.
///
typedef enum  {
  HttpIoSendNonChunkNone = 0,
  HttpIoSendNonChunkHeaderZeroContent,
  HttpIoSendNonChunkContent,
  HttpIoSendNonChunkFinish
} HTTP_IO_SEND_NON_CHUNK_PROCESS;

///
/// Chunk links for HTTP chunked transfer coding.
///
typedef struct {
  LIST_ENTRY    NextChunk;
  UINTN         Length;
  CHAR8         *Data;
} HTTP_IO_CHUNKS;

/**
  Notify the callback function when an event is triggered.

  @param[in]  Context         The opaque parameter to the function.

**/
VOID
EFIAPI
HttpIoNotifyDpc (
  IN VOID  *Context
  );

/**
  Request HttpIoNotifyDpc as a DPC at TPL_CALLBACK.

  @param[in]  Event                 The event signaled.
  @param[in]  Context               The opaque parameter to the function.

**/
VOID
EFIAPI
HttpIoNotify (
  IN EFI_EVENT  Event,
  IN VOID       *Context
  );

/**
  Destroy the HTTP_IO and release the resources.

  @param[in]  HttpIo          The HTTP_IO which wraps the HTTP service to be destroyed.

**/
VOID
HttpIoDestroyIo (
  IN HTTP_IO  *HttpIo
  );

/**
  Create a HTTP_IO to access the HTTP service. It will create and configure
  a HTTP child handle.

  @param[in]  Image          The handle of the driver image.
  @param[in]  Controller     The handle of the controller.
  @param[in]  IpVersion      IP_VERSION_4 or IP_VERSION_6.
  @param[in]  ConfigData     The HTTP_IO configuration data.
  @param[in]  Callback       Callback function which will be invoked when specified
                             HTTP_IO_CALLBACK_EVENT happened.
  @param[in]  Context        The Context data which will be passed to the Callback function.
  @param[out] HttpIo         The HTTP_IO.

  @retval EFI_SUCCESS            The HTTP_IO is created and configured.
  @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
  @retval EFI_UNSUPPORTED        One or more of the control options are not
                                 supported in the implementation.
  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
  @retval Others                 Failed to create the HTTP_IO or configure it.

**/
EFI_STATUS
HttpIoCreateIo (
  IN EFI_HANDLE           Image,
  IN EFI_HANDLE           Controller,
  IN UINT8                IpVersion,
  IN HTTP_IO_CONFIG_DATA  *ConfigData,
  IN HTTP_IO_CALLBACK     Callback,
  IN VOID                 *Context,
  OUT HTTP_IO             *HttpIo
  );

/**
  Synchronously send a HTTP REQUEST message to the server.

  @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
  @param[in]   Request          A pointer to storage such data as URL and HTTP method.
  @param[in]   HeaderCount      Number of HTTP header structures in Headers list.
  @param[in]   Headers          Array containing list of HTTP headers.
  @param[in]   BodyLength       Length in bytes of the HTTP body.
  @param[in]   Body             Body associated with the HTTP request.

  @retval EFI_SUCCESS            The HTTP request is transmitted.
  @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
  @retval Others                 Other errors as indicated.

**/
EFI_STATUS
HttpIoSendRequest (
  IN  HTTP_IO                *HttpIo,
  IN  EFI_HTTP_REQUEST_DATA  *Request       OPTIONAL,
  IN  UINTN                  HeaderCount,
  IN  EFI_HTTP_HEADER        *Headers       OPTIONAL,
  IN  UINTN                  BodyLength,
  IN  VOID                   *Body          OPTIONAL
  );

/**
  Synchronously receive a HTTP RESPONSE message from the server.

  @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
  @param[in]   RecvMsgHeader    TRUE to receive a new HTTP response (from message header).
                                FALSE to continue receive the previous response message.
  @param[out]  ResponseData     Point to a wrapper of the received response data.

  @retval EFI_SUCCESS            The HTTP response is received.
  @retval EFI_INVALID_PARAMETER  One or more parameters are invalid.
  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
  @retval EFI_DEVICE_ERROR       An unexpected network or system error occurred.
  @retval Others                 Other errors as indicated.

**/
EFI_STATUS
HttpIoRecvResponse (
  IN      HTTP_IO                *HttpIo,
  IN      BOOLEAN                RecvMsgHeader,
  OUT     HTTP_IO_RESPONSE_DATA  *ResponseData
  );

/**
  Get the value of the content length if there is a "Content-Length" header.

  @param[in]    HeaderCount        Number of HTTP header structures in Headers.
  @param[in]    Headers            Array containing list of HTTP headers.
  @param[out]   ContentLength      Pointer to save the value of the content length.

  @retval EFI_SUCCESS              Successfully get the content length.
  @retval EFI_NOT_FOUND            No "Content-Length" header in the Headers.

**/
EFI_STATUS
HttpIoGetContentLength (
  IN     UINTN            HeaderCount,
  IN     EFI_HTTP_HEADER  *Headers,
  OUT    UINTN            *ContentLength
  );

/**
  Synchronously receive a HTTP RESPONSE message from the server.

  @param[in]   HttpIo           The HttpIo wrapping the HTTP service.
  @param[in]   HeaderCount      Number of headers in Headers.
  @param[in]   Headers          Array containing list of HTTP headers.
  @param[out]  ChunkListHead    A pointer to receivce list head of chunked data.
                                Caller has to release memory of ChunkListHead
                                and all list entries.
  @param[out]  ContentLength    Total content length

  @retval EFI_SUCCESS            The HTTP chunked transfer is received.
  @retval EFI_NOT_FOUND          No chunked transfer coding header found.
  @retval EFI_OUT_OF_RESOURCES   Failed to allocate memory.
  @retval EFI_INVALID_PARAMETER  Improper parameters.
  @retval Others                 Other errors as indicated.

**/
EFI_STATUS
HttpIoGetChunkedTransferContent (
  IN     HTTP_IO          *HttpIo,
  IN     UINTN            HeaderCount,
  IN     EFI_HTTP_HEADER  *Headers,
  OUT    LIST_ENTRY       **ChunkListHead,
  OUT    UINTN            *ContentLength
  );

/**
  Send HTTP request in chunks.

  @param[in]   HttpIo             The HttpIo wrapping the HTTP service.
  @param[in]   SendChunkProcess   Pointer to current chunk process status.
  @param[out]  RequestMessage     Request to send.

  @retval EFI_SUCCESS             Successfully to send chunk data according to SendChunkProcess.
  @retval Other                   Other errors.

**/
EFI_STATUS
HttpIoSendChunkedTransfer (
  IN  HTTP_IO                     *HttpIo,
  IN  HTTP_IO_SEND_CHUNK_PROCESS  *SendChunkProcess,
  IN  EFI_HTTP_MESSAGE            *RequestMessage
  );

#endif