NetworkPkg/HttpDxe/HttpDriver.h

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