HttpDriver.h 20 KB

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