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