HttpIoLib.h 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329
  1. /** @file
  2. HttpIoLib.h.
  3. (C) Copyright 2020 Hewlett-Packard Development Company, L.P.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef HTTP_IO_LIB_H_
  7. #define HTTP_IO_LIB_H_
  8. #include <IndustryStandard/Http11.h>
  9. #include <Library/DpcLib.h>
  10. #include <Library/HttpLib.h>
  11. #include <Library/NetLib.h>
  12. #define HTTP_IO_MAX_SEND_PAYLOAD 1024
  13. #define HTTP_IO_CHUNK_SIZE_STRING_LEN 50
  14. #define HTTP_IO_CHUNKED_TRANSFER_CODING_DATA_LENGTH 256
  15. ///
  16. /// HTTP_IO_CALLBACK_EVENT
  17. ///
  18. typedef enum {
  19. HttpIoRequest,
  20. HttpIoResponse
  21. } HTTP_IO_CALLBACK_EVENT;
  22. /**
  23. HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
  24. @param[in] EventType Indicate the Event type that occurs in the current callback.
  25. @param[in] Message HTTP message which will be send to, or just received from HTTP server.
  26. @param[in] Context The Callback Context pointer.
  27. @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process.
  28. @retval Others Tells the HttpIo to abort the current HTTP process.
  29. **/
  30. typedef
  31. EFI_STATUS
  32. (EFIAPI *HTTP_IO_CALLBACK)(
  33. IN HTTP_IO_CALLBACK_EVENT EventType,
  34. IN EFI_HTTP_MESSAGE *Message,
  35. IN VOID *Context
  36. );
  37. ///
  38. /// A wrapper structure to hold the received HTTP response data.
  39. ///
  40. typedef struct {
  41. EFI_HTTP_RESPONSE_DATA Response;
  42. UINTN HeaderCount;
  43. EFI_HTTP_HEADER *Headers;
  44. UINTN BodyLength;
  45. CHAR8 *Body;
  46. EFI_STATUS Status;
  47. } HTTP_IO_RESPONSE_DATA;
  48. ///
  49. /// HTTP_IO configuration data for IPv4
  50. ///
  51. typedef struct {
  52. EFI_HTTP_VERSION HttpVersion;
  53. UINT32 RequestTimeOut; ///< In milliseconds.
  54. UINT32 ResponseTimeOut; ///< In milliseconds.
  55. BOOLEAN UseDefaultAddress;
  56. EFI_IPv4_ADDRESS LocalIp;
  57. EFI_IPv4_ADDRESS SubnetMask;
  58. UINT16 LocalPort;
  59. } HTTP4_IO_CONFIG_DATA;
  60. ///
  61. /// HTTP_IO configuration data for IPv6
  62. ///
  63. typedef struct {
  64. EFI_HTTP_VERSION HttpVersion;
  65. UINT32 RequestTimeOut; ///< In milliseconds.
  66. BOOLEAN UseDefaultAddress;
  67. EFI_IPv6_ADDRESS LocalIp;
  68. UINT16 LocalPort;
  69. } HTTP6_IO_CONFIG_DATA;
  70. ///
  71. /// HTTP_IO configuration
  72. ///
  73. typedef union {
  74. HTTP4_IO_CONFIG_DATA Config4;
  75. HTTP6_IO_CONFIG_DATA Config6;
  76. } HTTP_IO_CONFIG_DATA;
  77. ///
  78. /// HTTP_IO wrapper of the EFI HTTP service.
  79. ///
  80. typedef struct {
  81. UINT8 IpVersion;
  82. EFI_HANDLE Image;
  83. EFI_HANDLE Controller;
  84. EFI_HANDLE Handle;
  85. EFI_HTTP_PROTOCOL *Http;
  86. HTTP_IO_CALLBACK Callback;
  87. VOID *Context;
  88. EFI_HTTP_TOKEN ReqToken;
  89. EFI_HTTP_MESSAGE ReqMessage;
  90. EFI_HTTP_TOKEN RspToken;
  91. EFI_HTTP_MESSAGE RspMessage;
  92. BOOLEAN IsTxDone;
  93. BOOLEAN IsRxDone;
  94. EFI_EVENT TimeoutEvent;
  95. UINT32 Timeout;
  96. } HTTP_IO;
  97. ///
  98. /// Process code of HTTP chunk transfer.
  99. ///
  100. typedef enum {
  101. HttpIoSendChunkNone = 0,
  102. HttpIoSendChunkHeaderZeroContent,
  103. HttpIoSendChunkContent,
  104. HttpIoSendChunkEndChunk,
  105. HttpIoSendChunkFinish
  106. } HTTP_IO_SEND_CHUNK_PROCESS;
  107. ///
  108. /// Process code of HTTP non chunk transfer.
  109. ///
  110. typedef enum {
  111. HttpIoSendNonChunkNone = 0,
  112. HttpIoSendNonChunkHeaderZeroContent,
  113. HttpIoSendNonChunkContent,
  114. HttpIoSendNonChunkFinish
  115. } HTTP_IO_SEND_NON_CHUNK_PROCESS;
  116. ///
  117. /// Chunk links for HTTP chunked transfer coding.
  118. ///
  119. typedef struct {
  120. LIST_ENTRY NextChunk;
  121. UINTN Length;
  122. CHAR8 *Data;
  123. } HTTP_IO_CHUNKS;
  124. /**
  125. Notify the callback function when an event is triggered.
  126. @param[in] Context The opaque parameter to the function.
  127. **/
  128. VOID
  129. EFIAPI
  130. HttpIoNotifyDpc (
  131. IN VOID *Context
  132. );
  133. /**
  134. Request HttpIoNotifyDpc as a DPC at TPL_CALLBACK.
  135. @param[in] Event The event signaled.
  136. @param[in] Context The opaque parameter to the function.
  137. **/
  138. VOID
  139. EFIAPI
  140. HttpIoNotify (
  141. IN EFI_EVENT Event,
  142. IN VOID *Context
  143. );
  144. /**
  145. Destroy the HTTP_IO and release the resources.
  146. @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
  147. **/
  148. VOID
  149. HttpIoDestroyIo (
  150. IN HTTP_IO *HttpIo
  151. );
  152. /**
  153. Create a HTTP_IO to access the HTTP service. It will create and configure
  154. a HTTP child handle.
  155. @param[in] Image The handle of the driver image.
  156. @param[in] Controller The handle of the controller.
  157. @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
  158. @param[in] ConfigData The HTTP_IO configuration data.
  159. @param[in] Callback Callback function which will be invoked when specified
  160. HTTP_IO_CALLBACK_EVENT happened.
  161. @param[in] Context The Context data which will be passed to the Callback function.
  162. @param[out] HttpIo The HTTP_IO.
  163. @retval EFI_SUCCESS The HTTP_IO is created and configured.
  164. @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  165. @retval EFI_UNSUPPORTED One or more of the control options are not
  166. supported in the implementation.
  167. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  168. @retval Others Failed to create the HTTP_IO or configure it.
  169. **/
  170. EFI_STATUS
  171. HttpIoCreateIo (
  172. IN EFI_HANDLE Image,
  173. IN EFI_HANDLE Controller,
  174. IN UINT8 IpVersion,
  175. IN HTTP_IO_CONFIG_DATA *ConfigData,
  176. IN HTTP_IO_CALLBACK Callback,
  177. IN VOID *Context,
  178. OUT HTTP_IO *HttpIo
  179. );
  180. /**
  181. Synchronously send a HTTP REQUEST message to the server.
  182. @param[in] HttpIo The HttpIo wrapping the HTTP service.
  183. @param[in] Request A pointer to storage such data as URL and HTTP method.
  184. @param[in] HeaderCount Number of HTTP header structures in Headers list.
  185. @param[in] Headers Array containing list of HTTP headers.
  186. @param[in] BodyLength Length in bytes of the HTTP body.
  187. @param[in] Body Body associated with the HTTP request.
  188. @retval EFI_SUCCESS The HTTP request is transmitted.
  189. @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  190. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  191. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
  192. @retval Others Other errors as indicated.
  193. **/
  194. EFI_STATUS
  195. HttpIoSendRequest (
  196. IN HTTP_IO *HttpIo,
  197. IN EFI_HTTP_REQUEST_DATA *Request OPTIONAL,
  198. IN UINTN HeaderCount,
  199. IN EFI_HTTP_HEADER *Headers OPTIONAL,
  200. IN UINTN BodyLength,
  201. IN VOID *Body OPTIONAL
  202. );
  203. /**
  204. Synchronously receive a HTTP RESPONSE message from the server.
  205. @param[in] HttpIo The HttpIo wrapping the HTTP service.
  206. @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
  207. FALSE to continue receive the previous response message.
  208. @param[out] ResponseData Point to a wrapper of the received response data.
  209. @retval EFI_SUCCESS The HTTP response is received.
  210. @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  211. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  212. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
  213. @retval Others Other errors as indicated.
  214. **/
  215. EFI_STATUS
  216. HttpIoRecvResponse (
  217. IN HTTP_IO *HttpIo,
  218. IN BOOLEAN RecvMsgHeader,
  219. OUT HTTP_IO_RESPONSE_DATA *ResponseData
  220. );
  221. /**
  222. Get the value of the content length if there is a "Content-Length" header.
  223. @param[in] HeaderCount Number of HTTP header structures in Headers.
  224. @param[in] Headers Array containing list of HTTP headers.
  225. @param[out] ContentLength Pointer to save the value of the content length.
  226. @retval EFI_SUCCESS Successfully get the content length.
  227. @retval EFI_NOT_FOUND No "Content-Length" header in the Headers.
  228. **/
  229. EFI_STATUS
  230. HttpIoGetContentLength (
  231. IN UINTN HeaderCount,
  232. IN EFI_HTTP_HEADER *Headers,
  233. OUT UINTN *ContentLength
  234. );
  235. /**
  236. Synchronously receive a HTTP RESPONSE message from the server.
  237. @param[in] HttpIo The HttpIo wrapping the HTTP service.
  238. @param[in] HeaderCount Number of headers in Headers.
  239. @param[in] Headers Array containing list of HTTP headers.
  240. @param[out] ChunkListHead A pointer to receivce list head of chunked data.
  241. Caller has to release memory of ChunkListHead
  242. and all list entries.
  243. @param[out] ContentLength Total content length
  244. @retval EFI_SUCCESS The HTTP chunked transfer is received.
  245. @retval EFI_NOT_FOUND No chunked transfer coding header found.
  246. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  247. @retval EFI_INVALID_PARAMETER Improper parameters.
  248. @retval Others Other errors as indicated.
  249. **/
  250. EFI_STATUS
  251. HttpIoGetChunkedTransferContent (
  252. IN HTTP_IO *HttpIo,
  253. IN UINTN HeaderCount,
  254. IN EFI_HTTP_HEADER *Headers,
  255. OUT LIST_ENTRY **ChunkListHead,
  256. OUT UINTN *ContentLength
  257. );
  258. /**
  259. Send HTTP request in chunks.
  260. @param[in] HttpIo The HttpIo wrapping the HTTP service.
  261. @param[in] SendChunkProcess Pointer to current chunk process status.
  262. @param[out] RequestMessage Request to send.
  263. @retval EFI_SUCCESS Successfully to send chunk data according to SendChunkProcess.
  264. @retval Other Other errors.
  265. **/
  266. EFI_STATUS
  267. HttpIoSendChunkedTransfer (
  268. IN HTTP_IO *HttpIo,
  269. IN HTTP_IO_SEND_CHUNK_PROCESS *SendChunkProcess,
  270. IN EFI_HTTP_MESSAGE *RequestMessage
  271. );
  272. #endif