HttpDriver.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400
  1. /** @file
  2. The header files of the driver binding and service binding protocol for HttpDxe driver.
  3. Copyright (c) 2015 - 2021, Intel Corporation. All rights reserved.<BR>
  4. (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
  5. SPDX-License-Identifier: BSD-2-Clause-Patent
  6. **/
  7. #ifndef __EFI_HTTP_DRIVER_H__
  8. #define __EFI_HTTP_DRIVER_H__
  9. #include <Uefi.h>
  10. #include <IndustryStandard/Http11.h>
  11. //
  12. // Libraries
  13. //
  14. #include <Library/UefiBootServicesTableLib.h>
  15. #include <Library/UefiRuntimeServicesTableLib.h>
  16. #include <Library/MemoryAllocationLib.h>
  17. #include <Library/BaseLib.h>
  18. #include <Library/UefiLib.h>
  19. #include <Library/DebugLib.h>
  20. #include <Library/NetLib.h>
  21. #include <Library/HttpLib.h>
  22. #include <Library/DpcLib.h>
  23. //
  24. // UEFI Driver Model Protocols
  25. //
  26. #include <Protocol/DriverBinding.h>
  27. #include <Protocol/ServiceBinding.h>
  28. #include <Protocol/ComponentName2.h>
  29. #include <Protocol/ComponentName.h>
  30. //
  31. // Consumed Protocols
  32. //
  33. #include <Protocol/HttpUtilities.h>
  34. #include <Protocol/Tcp4.h>
  35. #include <Protocol/Tcp6.h>
  36. #include <Protocol/Dns4.h>
  37. #include <Protocol/Dns6.h>
  38. #include <Protocol/Ip4Config2.h>
  39. #include <Protocol/Ip6Config.h>
  40. #include <Protocol/Tls.h>
  41. #include <Protocol/TlsConfig.h>
  42. #include <Protocol/HttpCallback.h>
  43. #include <Guid/ImageAuthentication.h>
  44. //
  45. // Produced Protocols
  46. //
  47. #include <Protocol/Http.h>
  48. #include <Guid/TlsAuthentication.h>
  49. #include <Guid/HttpTlsCipherList.h>
  50. #include <IndustryStandard/Tls1.h>
  51. //
  52. // Driver Version
  53. //
  54. #define HTTP_DRIVER_VERSION 0xa
  55. //
  56. // Protocol instances
  57. //
  58. extern EFI_DRIVER_BINDING_PROTOCOL gHttpDxeIp4DriverBinding;
  59. extern EFI_DRIVER_BINDING_PROTOCOL gHttpDxeIp6DriverBinding;
  60. extern EFI_COMPONENT_NAME2_PROTOCOL gHttpDxeComponentName2;
  61. extern EFI_COMPONENT_NAME_PROTOCOL gHttpDxeComponentName;
  62. extern EFI_HTTP_UTILITIES_PROTOCOL *mHttpUtilities;
  63. //
  64. // Include files with function prototypes
  65. //
  66. #include "ComponentName.h"
  67. #include "HttpImpl.h"
  68. #include "HttpProto.h"
  69. #include "HttpsSupport.h"
  70. #include "HttpDns.h"
  71. typedef struct {
  72. EFI_SERVICE_BINDING_PROTOCOL *ServiceBinding;
  73. UINTN NumberOfChildren;
  74. EFI_HANDLE *ChildHandleBuffer;
  75. } HTTP_DESTROY_CHILD_IN_HANDLE_BUF_CONTEXT;
  76. /**
  77. Tests to see if this driver supports a given controller. If a child device is provided,
  78. it further tests to see if this driver supports creating a handle for the specified child device.
  79. This function checks to see if the driver specified by This supports the device specified by
  80. ControllerHandle. Drivers will typically use the device path attached to
  81. ControllerHandle and/or the services from the bus I/O abstraction attached to
  82. ControllerHandle to determine if the driver supports ControllerHandle. This function
  83. may be called many times during platform initialization. In order to reduce boot times, the tests
  84. performed by this function must be very small, and take as little time as possible to execute. This
  85. function must not change the state of any hardware devices, and this function must be aware that the
  86. device specified by ControllerHandle may already be managed by the same driver or a
  87. different driver. This function must match its calls to AllocatePages() with FreePages(),
  88. AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
  89. Because ControllerHandle may have been previously started by the same driver, if a protocol is
  90. already in the opened state, then it must not be closed with CloseProtocol(). This is required
  91. to guarantee the state of ControllerHandle is not modified by this function.
  92. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  93. @param[in] ControllerHandle The handle of the controller to test. This handle
  94. must support a protocol interface that supplies
  95. an I/O abstraction to the driver.
  96. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  97. parameter is ignored by device drivers, and is optional for bus
  98. drivers. For bus drivers, if this parameter is not NULL, then
  99. the bus driver must determine if the bus controller specified
  100. by ControllerHandle and the child controller specified
  101. by RemainingDevicePath are both supported by this
  102. bus driver.
  103. @retval EFI_SUCCESS The device specified by ControllerHandle and
  104. RemainingDevicePath is supported by the driver specified by This.
  105. @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  106. RemainingDevicePath is already being managed by the driver
  107. specified by This.
  108. @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
  109. RemainingDevicePath is already being managed by a different
  110. driver or an application that requires exclusive access.
  111. Currently not implemented.
  112. @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
  113. RemainingDevicePath is not supported by the driver specified by This.
  114. **/
  115. EFI_STATUS
  116. EFIAPI
  117. HttpDxeIp4DriverBindingSupported (
  118. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  119. IN EFI_HANDLE ControllerHandle,
  120. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
  121. );
  122. /**
  123. Starts a device controller or a bus controller.
  124. The Start() function is designed to be invoked from the EFI boot service ConnectController().
  125. As a result, much of the error checking on the parameters to Start() has been moved into this
  126. common boot service. It is legal to call Start() from other locations,
  127. but the following calling restrictions must be followed, or the system behavior will not be deterministic.
  128. 1. ControllerHandle must be a valid EFI_HANDLE.
  129. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
  130. EFI_DEVICE_PATH_PROTOCOL.
  131. 3. Prior to calling Start(), the Supported() function for the driver specified by This must
  132. have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
  133. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  134. @param[in] ControllerHandle The handle of the controller to start. This handle
  135. must support a protocol interface that supplies
  136. an I/O abstraction to the driver.
  137. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  138. parameter is ignored by device drivers, and is optional for bus
  139. drivers. For a bus driver, if this parameter is NULL, then handles
  140. for all the children of Controller are created by this driver.
  141. If this parameter is not NULL and the first Device Path Node is
  142. not the End of Device Path Node, then only the handle for the
  143. child device specified by the first Device Path Node of
  144. RemainingDevicePath is created by this driver.
  145. If the first Device Path Node of RemainingDevicePath is
  146. the End of Device Path Node, no child handle is created by this
  147. driver.
  148. @retval EFI_SUCCESS The device was started.
  149. @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
  150. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
  151. @retval Others The driver failed to start the device.
  152. **/
  153. EFI_STATUS
  154. EFIAPI
  155. HttpDxeIp4DriverBindingStart (
  156. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  157. IN EFI_HANDLE ControllerHandle,
  158. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
  159. );
  160. /**
  161. Stops a device controller or a bus controller.
  162. The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
  163. As a result, much of the error checking on the parameters to Stop() has been moved
  164. into this common boot service. It is legal to call Stop() from other locations,
  165. but the following calling restrictions must be followed, or the system behavior will not be deterministic.
  166. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
  167. same driver's Start() function.
  168. 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
  169. EFI_HANDLE. In addition, all of these handles must have been created in this driver's
  170. Start() function, and the Start() function must have called OpenProtocol() on
  171. ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
  172. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  173. @param[in] ControllerHandle A handle to the device being stopped. The handle must
  174. support a bus specific I/O protocol for the driver
  175. to use to stop the device.
  176. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
  177. @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
  178. if NumberOfChildren is 0.
  179. @retval EFI_SUCCESS The device was stopped.
  180. @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
  181. **/
  182. EFI_STATUS
  183. EFIAPI
  184. HttpDxeIp4DriverBindingStop (
  185. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  186. IN EFI_HANDLE ControllerHandle,
  187. IN UINTN NumberOfChildren,
  188. IN EFI_HANDLE *ChildHandleBuffer OPTIONAL
  189. );
  190. /**
  191. Tests to see if this driver supports a given controller. If a child device is provided,
  192. it further tests to see if this driver supports creating a handle for the specified child device.
  193. This function checks to see if the driver specified by This supports the device specified by
  194. ControllerHandle. Drivers will typically use the device path attached to
  195. ControllerHandle and/or the services from the bus I/O abstraction attached to
  196. ControllerHandle to determine if the driver supports ControllerHandle. This function
  197. may be called many times during platform initialization. In order to reduce boot times, the tests
  198. performed by this function must be very small, and take as little time as possible to execute. This
  199. function must not change the state of any hardware devices, and this function must be aware that the
  200. device specified by ControllerHandle may already be managed by the same driver or a
  201. different driver. This function must match its calls to AllocatePages() with FreePages(),
  202. AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
  203. Because ControllerHandle may have been previously started by the same driver, if a protocol is
  204. already in the opened state, then it must not be closed with CloseProtocol(). This is required
  205. to guarantee the state of ControllerHandle is not modified by this function.
  206. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  207. @param[in] ControllerHandle The handle of the controller to test. This handle
  208. must support a protocol interface that supplies
  209. an I/O abstraction to the driver.
  210. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  211. parameter is ignored by device drivers, and is optional for bus
  212. drivers. For bus drivers, if this parameter is not NULL, then
  213. the bus driver must determine if the bus controller specified
  214. by ControllerHandle and the child controller specified
  215. by RemainingDevicePath are both supported by this
  216. bus driver.
  217. @retval EFI_SUCCESS The device specified by ControllerHandle and
  218. RemainingDevicePath is supported by the driver specified by This.
  219. @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
  220. RemainingDevicePath is already being managed by the driver
  221. specified by This.
  222. @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
  223. RemainingDevicePath is already being managed by a different
  224. driver or an application that requires exclusive access.
  225. Currently not implemented.
  226. @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
  227. RemainingDevicePath is not supported by the driver specified by This.
  228. **/
  229. EFI_STATUS
  230. EFIAPI
  231. HttpDxeIp6DriverBindingSupported (
  232. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  233. IN EFI_HANDLE ControllerHandle,
  234. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
  235. );
  236. /**
  237. Starts a device controller or a bus controller.
  238. The Start() function is designed to be invoked from the EFI boot service ConnectController().
  239. As a result, much of the error checking on the parameters to Start() has been moved into this
  240. common boot service. It is legal to call Start() from other locations,
  241. but the following calling restrictions must be followed, or the system behavior will not be deterministic.
  242. 1. ControllerHandle must be a valid EFI_HANDLE.
  243. 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
  244. EFI_DEVICE_PATH_PROTOCOL.
  245. 3. Prior to calling Start(), the Supported() function for the driver specified by This must
  246. have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
  247. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  248. @param[in] ControllerHandle The handle of the controller to start. This handle
  249. must support a protocol interface that supplies
  250. an I/O abstraction to the driver.
  251. @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
  252. parameter is ignored by device drivers, and is optional for bus
  253. drivers. For a bus driver, if this parameter is NULL, then handles
  254. for all the children of Controller are created by this driver.
  255. If this parameter is not NULL and the first Device Path Node is
  256. not the End of Device Path Node, then only the handle for the
  257. child device specified by the first Device Path Node of
  258. RemainingDevicePath is created by this driver.
  259. If the first Device Path Node of RemainingDevicePath is
  260. the End of Device Path Node, no child handle is created by this
  261. driver.
  262. @retval EFI_SUCCESS The device was started.
  263. @retval EFI_ALREADY_STARTED This device is already running on ControllerHandle.
  264. @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
  265. @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
  266. @retval Others The driver failed to start the device.
  267. **/
  268. EFI_STATUS
  269. EFIAPI
  270. HttpDxeIp6DriverBindingStart (
  271. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  272. IN EFI_HANDLE ControllerHandle,
  273. IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
  274. );
  275. /**
  276. Stops a device controller or a bus controller.
  277. The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
  278. As a result, much of the error checking on the parameters to Stop() has been moved
  279. into this common boot service. It is legal to call Stop() from other locations,
  280. but the following calling restrictions must be followed, or the system behavior will not be deterministic.
  281. 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
  282. same driver's Start() function.
  283. 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
  284. EFI_HANDLE. In addition, all of these handles must have been created in this driver's
  285. Start() function, and the Start() function must have called OpenProtocol() on
  286. ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
  287. @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
  288. @param[in] ControllerHandle A handle to the device being stopped. The handle must
  289. support a bus specific I/O protocol for the driver
  290. to use to stop the device.
  291. @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
  292. @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
  293. if NumberOfChildren is 0.
  294. @retval EFI_SUCCESS The device was stopped.
  295. @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
  296. **/
  297. EFI_STATUS
  298. EFIAPI
  299. HttpDxeIp6DriverBindingStop (
  300. IN EFI_DRIVER_BINDING_PROTOCOL *This,
  301. IN EFI_HANDLE ControllerHandle,
  302. IN UINTN NumberOfChildren,
  303. IN EFI_HANDLE *ChildHandleBuffer OPTIONAL
  304. );
  305. /**
  306. Creates a child handle and installs a protocol.
  307. The CreateChild() function installs a protocol on ChildHandle.
  308. If ChildHandle is a pointer to NULL, then a new handle is created and returned in ChildHandle.
  309. If ChildHandle is not a pointer to NULL, then the protocol installs on the existing ChildHandle.
  310. @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
  311. @param ChildHandle Pointer to the handle of the child to create. If it is NULL,
  312. then a new handle is created. If it is a pointer to an existing UEFI handle,
  313. then the protocol is added to the existing UEFI handle.
  314. @retval EFI_SUCCESS The protocol was added to ChildHandle.
  315. @retval EFI_INVALID_PARAMETER This is NULL, or ChildHandle is NULL.
  316. @retval EFI_OUT_OF_RESOURCES There are not enough resources available to create
  317. the child.
  318. @retval other The child handle was not created.
  319. **/
  320. EFI_STATUS
  321. EFIAPI
  322. HttpServiceBindingCreateChild (
  323. IN EFI_SERVICE_BINDING_PROTOCOL *This,
  324. IN OUT EFI_HANDLE *ChildHandle
  325. );
  326. /**
  327. Destroys a child handle with a protocol installed on it.
  328. The DestroyChild() function does the opposite of CreateChild(). It removes a protocol
  329. that was installed by CreateChild() from ChildHandle. If the removed protocol is the
  330. last protocol on ChildHandle, then ChildHandle is destroyed.
  331. @param This Pointer to the EFI_SERVICE_BINDING_PROTOCOL instance.
  332. @param ChildHandle Handle of the child to destroy
  333. @retval EFI_SUCCESS The protocol was removed from ChildHandle.
  334. @retval EFI_UNSUPPORTED ChildHandle does not support the protocol that is being removed.
  335. @retval EFI_INVALID_PARAMETER Child handle is NULL.
  336. @retval other The child handle was not destroyed
  337. **/
  338. EFI_STATUS
  339. EFIAPI
  340. HttpServiceBindingDestroyChild (
  341. IN EFI_SERVICE_BINDING_PROTOCOL *This,
  342. IN EFI_HANDLE ChildHandle
  343. );
  344. #endif