NetworkPkg/Include/Library/HttpIoLib.h - third_party/edk2 - Git at Google

 /** @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
	/** @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