HttpBootSupport.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455
  1. /** @file
  2. Support functions declaration for UEFI HTTP boot driver.
  3. Copyright (c) 2015 - 2018, Intel Corporation. All rights reserved.<BR>
  4. SPDX-License-Identifier: BSD-2-Clause-Patent
  5. **/
  6. #ifndef __EFI_HTTP_BOOT_SUPPORT_H__
  7. #define __EFI_HTTP_BOOT_SUPPORT_H__
  8. /**
  9. Get the Nic handle using any child handle in the IPv4 stack.
  10. @param[in] ControllerHandle Pointer to child handle over IPv4.
  11. @return NicHandle The pointer to the Nic handle.
  12. @return NULL Can't find the Nic handle.
  13. **/
  14. EFI_HANDLE
  15. HttpBootGetNicByIp4Children (
  16. IN EFI_HANDLE ControllerHandle
  17. );
  18. /**
  19. Get the Nic handle using any child handle in the IPv6 stack.
  20. @param[in] ControllerHandle Pointer to child handle over IPv6.
  21. @return NicHandle The pointer to the Nic handle.
  22. @return NULL Can't find the Nic handle.
  23. **/
  24. EFI_HANDLE
  25. HttpBootGetNicByIp6Children (
  26. IN EFI_HANDLE ControllerHandle
  27. );
  28. /**
  29. This function is to convert UINTN to ASCII string with the required formatting.
  30. @param[in] Number Numeric value to be converted.
  31. @param[in] Buffer The pointer to the buffer for ASCII string.
  32. @param[in] Length The length of the required format.
  33. **/
  34. VOID
  35. HttpBootUintnToAscDecWithFormat (
  36. IN UINTN Number,
  37. IN UINT8 *Buffer,
  38. IN INTN Length
  39. );
  40. /**
  41. This function is to display the IPv4 address.
  42. @param[in] Ip The pointer to the IPv4 address.
  43. **/
  44. VOID
  45. HttpBootShowIp4Addr (
  46. IN EFI_IPv4_ADDRESS *Ip
  47. );
  48. /**
  49. This function is to display the IPv6 address.
  50. @param[in] Ip The pointer to the IPv6 address.
  51. **/
  52. VOID
  53. HttpBootShowIp6Addr (
  54. IN EFI_IPv6_ADDRESS *Ip
  55. );
  56. /**
  57. This function is to display the HTTP error status.
  58. @param[in] StatusCode The status code value in HTTP message.
  59. **/
  60. VOID
  61. HttpBootPrintErrorMessage (
  62. EFI_HTTP_STATUS_CODE StatusCode
  63. );
  64. //
  65. // A wrapper structure to hold the HTTP headers.
  66. //
  67. typedef struct {
  68. UINTN MaxHeaderCount;
  69. UINTN HeaderCount;
  70. EFI_HTTP_HEADER *Headers;
  71. } HTTP_IO_HEADER;
  72. /**
  73. Create a HTTP_IO_HEADER to hold the HTTP header items.
  74. @param[in] MaxHeaderCount The maximun number of HTTP header in this holder.
  75. @return A pointer of the HTTP header holder or NULL if failed.
  76. **/
  77. HTTP_IO_HEADER *
  78. HttpBootCreateHeader (
  79. IN UINTN MaxHeaderCount
  80. );
  81. /**
  82. Destroy the HTTP_IO_HEADER and release the resouces.
  83. @param[in] HttpIoHeader Point to the HTTP header holder to be destroyed.
  84. **/
  85. VOID
  86. HttpBootFreeHeader (
  87. IN HTTP_IO_HEADER *HttpIoHeader
  88. );
  89. /**
  90. Set or update a HTTP header with the field name and corresponding value.
  91. @param[in] HttpIoHeader Point to the HTTP header holder.
  92. @param[in] FieldName Null terminated string which describes a field name.
  93. @param[in] FieldValue Null terminated string which describes the corresponding field value.
  94. @retval EFI_SUCCESS The HTTP header has been set or updated.
  95. @retval EFI_INVALID_PARAMETER Any input parameter is invalid.
  96. @retval EFI_OUT_OF_RESOURCES Insufficient resource to complete the operation.
  97. @retval Other Unexpected error happened.
  98. **/
  99. EFI_STATUS
  100. HttpBootSetHeader (
  101. IN HTTP_IO_HEADER *HttpIoHeader,
  102. IN CHAR8 *FieldName,
  103. IN CHAR8 *FieldValue
  104. );
  105. ///
  106. /// HTTP_IO_CALLBACK_EVENT
  107. ///
  108. typedef enum {
  109. HttpIoRequest,
  110. HttpIoResponse
  111. } HTTP_IO_CALLBACK_EVENT;
  112. /**
  113. HttpIo Callback function which will be invoked when specified HTTP_IO_CALLBACK_EVENT happened.
  114. @param[in] EventType Indicate the Event type that occurs in the current callback.
  115. @param[in] Message HTTP message which will be send to, or just received from HTTP server.
  116. @param[in] Context The Callback Context pointer.
  117. @retval EFI_SUCCESS Tells the HttpIo to continue the HTTP process.
  118. @retval Others Tells the HttpIo to abort the current HTTP process.
  119. **/
  120. typedef
  121. EFI_STATUS
  122. (EFIAPI * HTTP_IO_CALLBACK) (
  123. IN HTTP_IO_CALLBACK_EVENT EventType,
  124. IN EFI_HTTP_MESSAGE *Message,
  125. IN VOID *Context
  126. );
  127. //
  128. // HTTP_IO configuration data for IPv4
  129. //
  130. typedef struct {
  131. EFI_HTTP_VERSION HttpVersion;
  132. UINT32 RequestTimeOut; // In milliseconds.
  133. UINT32 ResponseTimeOut; // In milliseconds.
  134. BOOLEAN UseDefaultAddress;
  135. EFI_IPv4_ADDRESS LocalIp;
  136. EFI_IPv4_ADDRESS SubnetMask;
  137. UINT16 LocalPort;
  138. } HTTP4_IO_CONFIG_DATA;
  139. //
  140. // HTTP_IO configuration data for IPv6
  141. //
  142. typedef struct {
  143. EFI_HTTP_VERSION HttpVersion;
  144. UINT32 RequestTimeOut; // In milliseconds.
  145. BOOLEAN UseDefaultAddress;
  146. EFI_IPv6_ADDRESS LocalIp;
  147. UINT16 LocalPort;
  148. } HTTP6_IO_CONFIG_DATA;
  149. //
  150. // HTTP_IO configuration
  151. //
  152. typedef union {
  153. HTTP4_IO_CONFIG_DATA Config4;
  154. HTTP6_IO_CONFIG_DATA Config6;
  155. } HTTP_IO_CONFIG_DATA;
  156. //
  157. // HTTP_IO wrapper of the EFI HTTP service.
  158. //
  159. typedef struct {
  160. UINT8 IpVersion;
  161. EFI_HANDLE Image;
  162. EFI_HANDLE Controller;
  163. EFI_HANDLE Handle;
  164. EFI_HTTP_PROTOCOL *Http;
  165. HTTP_IO_CALLBACK Callback;
  166. VOID *Context;
  167. EFI_HTTP_TOKEN ReqToken;
  168. EFI_HTTP_MESSAGE ReqMessage;
  169. EFI_HTTP_TOKEN RspToken;
  170. EFI_HTTP_MESSAGE RspMessage;
  171. BOOLEAN IsTxDone;
  172. BOOLEAN IsRxDone;
  173. EFI_EVENT TimeoutEvent;
  174. } HTTP_IO;
  175. //
  176. // A wrapper structure to hold the received HTTP response data.
  177. //
  178. typedef struct {
  179. EFI_HTTP_RESPONSE_DATA Response;
  180. UINTN HeaderCount;
  181. EFI_HTTP_HEADER *Headers;
  182. UINTN BodyLength;
  183. CHAR8 *Body;
  184. EFI_STATUS Status;
  185. } HTTP_IO_RESPONSE_DATA;
  186. /**
  187. Retrieve the host address using the EFI_DNS6_PROTOCOL.
  188. @param[in] Private The pointer to the driver's private data.
  189. @param[in] HostName Pointer to buffer containing hostname.
  190. @param[out] IpAddress On output, pointer to buffer containing IPv6 address.
  191. @retval EFI_SUCCESS Operation succeeded.
  192. @retval EFI_DEVICE_ERROR An unexpected network error occurred.
  193. @retval Others Other errors as indicated.
  194. **/
  195. EFI_STATUS
  196. HttpBootDns (
  197. IN HTTP_BOOT_PRIVATE_DATA *Private,
  198. IN CHAR16 *HostName,
  199. OUT EFI_IPv6_ADDRESS *IpAddress
  200. );
  201. /**
  202. Notify the callback function when an event is triggered.
  203. @param[in] Event The triggered event.
  204. @param[in] Context The opaque parameter to the function.
  205. **/
  206. VOID
  207. EFIAPI
  208. HttpBootCommonNotify (
  209. IN EFI_EVENT Event,
  210. IN VOID *Context
  211. );
  212. /**
  213. Create a HTTP_IO to access the HTTP service. It will create and configure
  214. a HTTP child handle.
  215. @param[in] Image The handle of the driver image.
  216. @param[in] Controller The handle of the controller.
  217. @param[in] IpVersion IP_VERSION_4 or IP_VERSION_6.
  218. @param[in] ConfigData The HTTP_IO configuration data.
  219. @param[in] Callback Callback function which will be invoked when specified
  220. HTTP_IO_CALLBACK_EVENT happened.
  221. @param[in] Context The Context data which will be passed to the Callback function.
  222. @param[out] HttpIo The HTTP_IO.
  223. @retval EFI_SUCCESS The HTTP_IO is created and configured.
  224. @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  225. @retval EFI_UNSUPPORTED One or more of the control options are not
  226. supported in the implementation.
  227. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  228. @retval Others Failed to create the HTTP_IO or configure it.
  229. **/
  230. EFI_STATUS
  231. HttpIoCreateIo (
  232. IN EFI_HANDLE Image,
  233. IN EFI_HANDLE Controller,
  234. IN UINT8 IpVersion,
  235. IN HTTP_IO_CONFIG_DATA *ConfigData,
  236. IN HTTP_IO_CALLBACK Callback,
  237. IN VOID *Context,
  238. OUT HTTP_IO *HttpIo
  239. );
  240. /**
  241. Destroy the HTTP_IO and release the resouces.
  242. @param[in] HttpIo The HTTP_IO which wraps the HTTP service to be destroyed.
  243. **/
  244. VOID
  245. HttpIoDestroyIo (
  246. IN HTTP_IO *HttpIo
  247. );
  248. /**
  249. Synchronously send a HTTP REQUEST message to the server.
  250. @param[in] HttpIo The HttpIo wrapping the HTTP service.
  251. @param[in] Request A pointer to storage such data as URL and HTTP method.
  252. @param[in] HeaderCount Number of HTTP header structures in Headers list.
  253. @param[in] Headers Array containing list of HTTP headers.
  254. @param[in] BodyLength Length in bytes of the HTTP body.
  255. @param[in] Body Body associated with the HTTP request.
  256. @retval EFI_SUCCESS The HTTP request is trasmitted.
  257. @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  258. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  259. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
  260. @retval Others Other errors as indicated.
  261. **/
  262. EFI_STATUS
  263. HttpIoSendRequest (
  264. IN HTTP_IO *HttpIo,
  265. IN EFI_HTTP_REQUEST_DATA *Request, OPTIONAL
  266. IN UINTN HeaderCount,
  267. IN EFI_HTTP_HEADER *Headers, OPTIONAL
  268. IN UINTN BodyLength,
  269. IN VOID *Body OPTIONAL
  270. );
  271. /**
  272. Synchronously receive a HTTP RESPONSE message from the server.
  273. @param[in] HttpIo The HttpIo wrapping the HTTP service.
  274. @param[in] RecvMsgHeader TRUE to receive a new HTTP response (from message header).
  275. FALSE to continue receive the previous response message.
  276. @param[out] ResponseData Point to a wrapper of the received response data.
  277. @retval EFI_SUCCESS The HTTP response is received.
  278. @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
  279. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  280. @retval EFI_DEVICE_ERROR An unexpected network or system error occurred.
  281. @retval Others Other errors as indicated.
  282. **/
  283. EFI_STATUS
  284. HttpIoRecvResponse (
  285. IN HTTP_IO *HttpIo,
  286. IN BOOLEAN RecvMsgHeader,
  287. OUT HTTP_IO_RESPONSE_DATA *ResponseData
  288. );
  289. /**
  290. This function checks the HTTP(S) URI scheme.
  291. @param[in] Uri The pointer to the URI string.
  292. @retval EFI_SUCCESS The URI scheme is valid.
  293. @retval EFI_INVALID_PARAMETER The URI scheme is not HTTP or HTTPS.
  294. @retval EFI_ACCESS_DENIED HTTP is disabled and the URI is HTTP.
  295. **/
  296. EFI_STATUS
  297. HttpBootCheckUriScheme (
  298. IN CHAR8 *Uri
  299. );
  300. /**
  301. Get the URI address string from the input device path.
  302. Caller need to free the buffer in the UriAddress pointer.
  303. @param[in] FilePath Pointer to the device path which contains a URI device path node.
  304. @param[out] UriAddress The URI address string extract from the device path.
  305. @retval EFI_SUCCESS The URI string is returned.
  306. @retval EFI_OUT_OF_RESOURCES Failed to allocate memory.
  307. **/
  308. EFI_STATUS
  309. HttpBootParseFilePath (
  310. IN EFI_DEVICE_PATH_PROTOCOL *FilePath,
  311. OUT CHAR8 **UriAddress
  312. );
  313. /**
  314. This function returns the image type according to server replied HTTP message
  315. and also the image's URI info.
  316. @param[in] Uri The pointer to the image's URI string.
  317. @param[in] UriParser URI Parse result returned by NetHttpParseUrl().
  318. @param[in] HeaderCount Number of HTTP header structures in Headers list.
  319. @param[in] Headers Array containing list of HTTP headers.
  320. @param[out] ImageType The image type of the downloaded file.
  321. @retval EFI_SUCCESS The image type is returned in ImageType.
  322. @retval EFI_INVALID_PARAMETER ImageType, Uri or UriParser is NULL.
  323. @retval EFI_INVALID_PARAMETER HeaderCount is not zero, and Headers is NULL.
  324. @retval EFI_NOT_FOUND Failed to identify the image type.
  325. @retval Others Unexpect error happened.
  326. **/
  327. EFI_STATUS
  328. HttpBootCheckImageType (
  329. IN CHAR8 *Uri,
  330. IN VOID *UriParser,
  331. IN UINTN HeaderCount,
  332. IN EFI_HTTP_HEADER *Headers,
  333. OUT HTTP_BOOT_IMAGE_TYPE *ImageType
  334. );
  335. /**
  336. This function register the RAM disk info to the system.
  337. @param[in] Private The pointer to the driver's private data.
  338. @param[in] BufferSize The size of Buffer in bytes.
  339. @param[in] Buffer The base address of the RAM disk.
  340. @param[in] ImageType The image type of the file in Buffer.
  341. @retval EFI_SUCCESS The RAM disk has been registered.
  342. @retval EFI_NOT_FOUND No RAM disk protocol instances were found.
  343. @retval EFI_UNSUPPORTED The ImageType is not supported.
  344. @retval Others Unexpected error happened.
  345. **/
  346. EFI_STATUS
  347. HttpBootRegisterRamDisk (
  348. IN HTTP_BOOT_PRIVATE_DATA *Private,
  349. IN UINTN BufferSize,
  350. IN VOID *Buffer,
  351. IN HTTP_BOOT_IMAGE_TYPE ImageType
  352. );
  353. /**
  354. Indicate if the HTTP status code indicates a redirection.
  355. @param[in] StatusCode HTTP status code from server.
  356. @return TRUE if it's redirection.
  357. **/
  358. BOOLEAN
  359. HttpBootIsHttpRedirectStatusCode (
  360. IN EFI_HTTP_STATUS_CODE StatusCode
  361. );
  362. #endif