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