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