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 - 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 //
  75 extern EFI_DRIVER_BINDING_PROTOCOL  gHttpDxeIp4DriverBinding;
  76 extern EFI_DRIVER_BINDING_PROTOCOL  gHttpDxeIp6DriverBinding;
  77
  78 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpDxeComponentName2;
  79 extern EFI_COMPONENT_NAME_PROTOCOL  gHttpDxeComponentName;
  80
  81 extern 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
  92 typedef 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 **/
 140 EFI_STATUS
 141 EFIAPI
 142 HttpDxeIp4DriverBindingSupported (
 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 **/
 183 EFI_STATUS
 184 EFIAPI
 185 HttpDxeIp4DriverBindingStart (
 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 **/
 217 EFI_STATUS
 218 EFIAPI
 219 HttpDxeIp4DriverBindingStop (
 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 **/
 268 EFI_STATUS
 269 EFIAPI
 270 HttpDxeIp6DriverBindingSupported (
 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 **/
 312 EFI_STATUS
 313 EFIAPI
 314 HttpDxeIp6DriverBindingStart (
 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 **/
 346 EFI_STATUS
 347 EFIAPI
 348 HttpDxeIp6DriverBindingStop (
 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 **/
 374 EFI_STATUS
 375 EFIAPI
 376 HttpServiceBindingCreateChild (
 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 **/
 397 EFI_STATUS
 398 EFIAPI
 399 HttpServiceBindingDestroyChild (
 400   IN EFI_SERVICE_BINDING_PROTOCOL  *This,
 401   IN EFI_HANDLE                    ChildHandle
 402   );
 403
 404 #endif