MdePkg/Include/Protocol/Dhcp4.h

   1 /** @file
   2   EFI_DHCP4_PROTOCOL as defined in UEFI 2.0.
   3   EFI_DHCP4_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0.
   4   These protocols are used to collect configuration information for the EFI IPv4 Protocol
   5   drivers and to provide DHCPv4 server and PXE boot server discovery services.
   6
   7   Copyright (c) 2006 - 2008, Intel Corporation
   8   All rights reserved. This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16 **/
  17
  18 #ifndef __EFI_DHCP4_PROTOCOL_H__
  19 #define __EFI_DHCP4_PROTOCOL_H__
  20
  21 #define EFI_DHCP4_PROTOCOL_GUID \
  22   { \
  23     0x8a219718, 0x4ef5, 0x4761, {0x91, 0xc8, 0xc0, 0xf0, 0x4b, 0xda, 0x9e, 0x56 } \
  24   }
  25
  26 #define EFI_DHCP4_SERVICE_BINDING_PROTOCOL_GUID \
  27   { \
  28     0x9d9a39d8, 0xbd42, 0x4a73, {0xa4, 0xd5, 0x8e, 0xe9, 0x4b, 0xe1, 0x13, 0x80 } \
  29   }
  30
  31 typedef struct _EFI_DHCP4_PROTOCOL EFI_DHCP4_PROTOCOL;
  32
  33
  34 #pragma pack(1)
  35 typedef struct {
  36   UINT8               OpCode;
  37   UINT8               Length;
  38   UINT8               Data[1];
  39 } EFI_DHCP4_PACKET_OPTION;
  40 #pragma pack()
  41
  42
  43 #pragma pack(1)
  44 typedef struct {
  45     UINT8             OpCode;
  46     UINT8             HwType;
  47     UINT8             HwAddrLen;
  48     UINT8             Hops;
  49     UINT32            Xid;
  50     UINT16            Seconds;
  51     UINT16            Reserved;
  52     EFI_IPv4_ADDRESS  ClientAddr;       ///< Client IP address from client
  53     EFI_IPv4_ADDRESS  YourAddr;         ///< Client IP address from server
  54     EFI_IPv4_ADDRESS  ServerAddr;       ///< IP address of next server in bootstrap
  55     EFI_IPv4_ADDRESS  GatewayAddr;      ///< Relay agent IP address
  56     UINT8             ClientHwAddr[16]; ///< Client hardware address
  57     CHAR8             ServerName[64];
  58     CHAR8             BootFileName[128];
  59 }EFI_DHCP4_HEADER;
  60 #pragma pack()
  61
  62
  63 #pragma pack(1)
  64 typedef struct {
  65   UINT32              Size;
  66   UINT32              Length;
  67
  68   struct {
  69     EFI_DHCP4_HEADER  Header;
  70     UINT32            Magik;
  71     UINT8             Option[1];
  72   } Dhcp4;
  73 } EFI_DHCP4_PACKET;
  74 #pragma pack()
  75
  76
  77 typedef enum {
  78   Dhcp4Stopped        = 0x0,
  79   Dhcp4Init           = 0x1,
  80   Dhcp4Selecting      = 0x2,
  81   Dhcp4Requesting     = 0x3,
  82   Dhcp4Bound          = 0x4,
  83   Dhcp4Renewing       = 0x5,
  84   Dhcp4Rebinding      = 0x6,
  85   Dhcp4InitReboot     = 0x7,
  86   Dhcp4Rebooting      = 0x8
  87 } EFI_DHCP4_STATE;
  88
  89
  90 typedef enum{
  91   Dhcp4SendDiscover   = 0x01,
  92   Dhcp4RcvdOffer      = 0x02,
  93   Dhcp4SelectOffer    = 0x03,
  94   Dhcp4SendRequest    = 0x04,
  95   Dhcp4RcvdAck        = 0x05,
  96   Dhcp4RcvdNak        = 0x06,
  97   Dhcp4SendDecline    = 0x07,
  98   Dhcp4BoundCompleted = 0x08,
  99   Dhcp4EnterRenewing  = 0x09,
 100   Dhcp4EnterRebinding = 0x0a,
 101   Dhcp4AddressLost    = 0x0b,
 102   Dhcp4Fail           = 0x0c
 103 } EFI_DHCP4_EVENT;
 104
 105 /**
 106   Callback routine
 107
 108   @param  This                  Pointer to the EFI DHCPv4 Protocol instance that is used to
 109                                 configure this callback function.
 110   @param  Context               Pointer to the context that is initialized by
 111                                 EFI_DHCP4_PROTOCOL.Configure().
 112   @param  CurrentState          The current operational state of the EFI DHCPv4 Protocol
 113                                 driver.
 114   @param  Dhcp4Event            The event that occurs in the current state, which usually means a
 115                                 state transition.
 116   @param  Packet                The DHCP packet that is going to be sent or already received.
 117   @param  NewPacket             The packet that is used to replace the above Packet.
 118
 119   @retval EFI_SUCCESS           Tells the EFI DHCPv4 Protocol driver to continue the DHCP process.
 120   @retval EFI_NOT_READY         Only used in the Dhcp4Selecting state. The EFI DHCPv4 Protocol
 121                                 driver will continue to wait for more DHCPOFFER packets until the retry
 122                                 timeout expires.
 123   @retval EFI_ABORTED           Tells the EFI DHCPv4 Protocol driver to abort the current process and
 124                                 return to the Dhcp4Init or Dhcp4InitReboot state.
 125
 126 **/
 127 typedef
 128 EFI_STATUS
 129 (EFIAPI *EFI_DHCP4_CALLBACK)(
 130   IN  EFI_DHCP4_PROTOCOL         *This,
 131   IN  VOID                       *Context,
 132   IN  EFI_DHCP4_STATE            CurrentState,
 133   IN  EFI_DHCP4_EVENT            Dhcp4Event,
 134   IN  EFI_DHCP4_PACKET           *Packet     OPTIONAL,
 135   OUT EFI_DHCP4_PACKET           **NewPacket OPTIONAL
 136   );
 137
 138
 139 typedef struct {
 140   UINT32                      DiscoverTryCount;
 141   UINT32                      *DiscoverTimeout;
 142   UINT32                      RequestTryCount;
 143   UINT32                      *RequestTimeout;
 144   EFI_IPv4_ADDRESS            ClientAddress;
 145   EFI_DHCP4_CALLBACK          Dhcp4Callback;
 146   void                        *CallbackContext;
 147   UINT32                      OptionCount;
 148   EFI_DHCP4_PACKET_OPTION     **OptionList;
 149 } EFI_DHCP4_CONFIG_DATA;
 150
 151
 152 typedef struct {
 153   EFI_DHCP4_STATE             State;
 154   EFI_DHCP4_CONFIG_DATA       ConfigData;
 155   EFI_IPv4_ADDRESS            ClientAddress;
 156   EFI_MAC_ADDRESS             ClientMacAddress;
 157   EFI_IPv4_ADDRESS            ServerAddress;
 158   EFI_IPv4_ADDRESS            RouterAddress;
 159   EFI_IPv4_ADDRESS            SubnetMask;
 160   UINT32                      LeaseTime;
 161   EFI_DHCP4_PACKET            *ReplyPacket;
 162 } EFI_DHCP4_MODE_DATA;
 163
 164
 165 typedef struct {
 166   EFI_IPv4_ADDRESS            ListenAddress;
 167   EFI_IPv4_ADDRESS            SubnetMask;
 168   UINT16                      ListenPort;
 169 } EFI_DHCP4_LISTEN_POINT;
 170
 171
 172 typedef struct {
 173   EFI_STATUS              Status;
 174   EFI_EVENT               CompletionEvent;
 175   EFI_IPv4_ADDRESS        RemoteAddress;
 176   UINT16                  RemotePort;
 177   EFI_IPv4_ADDRESS        GatewayAddress;
 178   UINT32                  ListenPointCount;
 179   EFI_DHCP4_LISTEN_POINT  *ListenPoints;
 180   UINT32                  TimeoutValue;
 181   EFI_DHCP4_PACKET        *Packet;
 182   UINT32                  ResponseCount;
 183   EFI_DHCP4_PACKET        *ResponseList;
 184 } EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN;
 185
 186
 187 /**
 188   Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver.
 189
 190   @param  This          Pointer to the EFI_DHCP4_PROTOCOL instance.
 191   @param  Dhcp4ModeData Pointer to storage for the EFI_DHCP4_MODE_DATA structure.
 192
 193   @retval EFI_SUCCESS           The mode data was returned.
 194   @retval EFI_INVALID_PARAMETER This is NULL.
 195
 196 **/
 197 typedef
 198 EFI_STATUS
 199 (EFIAPI *EFI_DHCP4_GET_MODE_DATA)(
 200   IN  EFI_DHCP4_PROTOCOL      *This,
 201   OUT EFI_DHCP4_MODE_DATA     *Dhcp4ModeData
 202   );
 203
 204 /**
 205   Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver.
 206
 207   @param  This                   Pointer to the EFI_DHCP4_PROTOCOL instance.
 208   @param  Dhcp4CfgData           Pointer to the EFI_DHCP4_CONFIG_DATA.
 209
 210   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init or
 211                                 Dhcp4InitReboot state, if the original state of this driver
 212                                 was Dhcp4Stopped and the value of Dhcp4CfgData was
 213                                 not NULL. Otherwise, the state was left unchanged.
 214   @retval EFI_ACCESS_DENIED     This instance of the EFI DHCPv4 Protocol driver was not in the
 215                                 Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;
 216                                 Or onother instance of this EFI DHCPv4 Protocol driver is already
 217                                 in a valid configured state.
 218   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 219   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 220   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 221
 222 **/
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *EFI_DHCP4_CONFIGURE)(
 226   IN EFI_DHCP4_PROTOCOL       *This,
 227   IN EFI_DHCP4_CONFIG_DATA    *Dhcp4CfgData  OPTIONAL
 228   );
 229
 230
 231 /**
 232   Starts the DHCP configuration process.
 233
 234   @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.
 235   @param  CompletionEvent If not NULL, indicates the event that will be signaled when the
 236                           EFI DHCPv4 Protocol driver is transferred into the
 237                           Dhcp4Bound state or when the DHCP process is aborted.
 238                           EFI_DHCP4_PROTOCOL.GetModeData() can be called to
 239                           check the completion status. If NULL,
 240                           EFI_DHCP4_PROTOCOL.Start() will wait until the driver
 241                           is transferred into the Dhcp4Bound state or the process fails.
 242
 243   @retval EFI_SUCCESS           The DHCP configuration process has started, or it has completed
 244                                 when CompletionEvent is NULL.
 245   @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped
 246                                 state. EFI_DHCP4_PROTOCOL. Configure() needs to be called.
 247   @retval EFI_INVALID_PARAMETER This is NULL.
 248   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 249   @retval EFI_TIMEOUT           The DHCP configuration process failed because no response was
 250                                 received from the server within the specified timeout value.
 251   @retval EFI_ABORTED           The user aborted the DHCP process.
 252   @retval EFI_ALREADY_STARTED   Some other EFI DHCPv4 Protocol instance already started the
 253                                 DHCP process.
 254   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 255
 256 **/
 257 typedef
 258 EFI_STATUS
 259 (EFIAPI *EFI_DHCP4_START)(
 260   IN EFI_DHCP4_PROTOCOL       *This,
 261   IN EFI_EVENT                CompletionEvent   OPTIONAL
 262   );
 263
 264 /**
 265   Extends the lease time by sending a request packet.
 266
 267   @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.
 268   @param  RebindRequest   If TRUE, this function broadcasts the request packets and enters
 269                           the Dhcp4Rebinding state. Otherwise, it sends a unicast
 270                           request packet and enters the Dhcp4Renewing state.
 271   @param  CompletionEvent If not NULL, this event is signaled when the renew/rebind phase
 272                           completes or some error occurs.
 273                           EFI_DHCP4_PROTOCOL.GetModeData() can be called to
 274                           check the completion status. If NULL,
 275                           EFI_DHCP4_PROTOCOL.RenewRebind() will busy-wait
 276                           until the DHCP process finishes.
 277
 278   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the
 279                                 Dhcp4Renewing state or is back to the Dhcp4Bound state.
 280   @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped
 281                                 state. EFI_DHCP4_PROTOCOL.Configure() needs to
 282                                 be called.
 283   @retval EFI_INVALID_PARAMETER This is NULL.
 284   @retval EFI_TIMEOUT           There was no response from the server when the try count was
 285                                 exceeded.
 286   @retval EFI_ACCESS_DENIED     The driver is not in the Dhcp4Bound state.
 287   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 288
 289 **/
 290 typedef
 291 EFI_STATUS
 292 (EFIAPI *EFI_DHCP4_RENEW_REBIND)(
 293   IN EFI_DHCP4_PROTOCOL       *This,
 294   IN BOOLEAN                  RebindRequest,
 295   IN EFI_EVENT                CompletionEvent  OPTIONAL
 296   );
 297
 298 /**
 299   Releases the current address configuration.
 300
 301   @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.
 302
 303   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase.
 304   @retval EFI_INVALID_PARAMETER This is NULL.
 305   @retval EFI_ACCESS_DENIED     The EFI DHCPv4 Protocol driver is not Dhcp4InitReboot state.
 306   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 307
 308 **/
 309 typedef
 310 EFI_STATUS
 311 (EFIAPI *EFI_DHCP4_RELEASE)(
 312   IN EFI_DHCP4_PROTOCOL       *This
 313   );
 314
 315 /**
 316   Stops the current address configuration.
 317
 318   @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.
 319
 320   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase.
 321   @retval EFI_INVALID_PARAMETER This is NULL.
 322
 323 **/
 324 typedef
 325 EFI_STATUS
 326 (EFIAPI *EFI_DHCP4_STOP)(
 327   IN EFI_DHCP4_PROTOCOL       *This
 328   );
 329
 330 /**
 331   Builds a DHCP packet, given the options to be appended or deleted or replaced.
 332
 333   @param  This        Pointer to the EFI_DHCP4_PROTOCOL instance.
 334   @param  SeedPacket  Initial packet to be used as a base for building new packet.
 335   @param  DeleteCount Number of opcodes in the DeleteList.
 336   @param  DeleteList  List of opcodes to be deleted from the seed packet.
 337                       Ignored if DeleteCount is zero.
 338   @param  AppendCount Number of entries in the OptionList.
 339   @param  AppendList  Pointer to a DHCP option list to be appended to SeedPacket.
 340                       If SeedPacket also contains options in this list, they are
 341                       replaced by new options (except pad option). Ignored if
 342                       AppendCount is zero. Type EFI_DHCP4_PACKET_OPTION
 343   @param  NewPacket   Pointer to storage for the pointer to the new allocated packet.
 344                       Use the EFI Boot Service FreePool() on the resulting pointer
 345                       when done with the packet.
 346
 347   @retval EFI_SUCCESS           The new packet was built.
 348   @retval EFI_OUT_OF_RESOURCES  Storage for the new packet could not be allocated.
 349   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 350
 351 **/
 352 typedef
 353 EFI_STATUS
 354 (EFIAPI *EFI_DHCP4_BUILD)(
 355   IN  EFI_DHCP4_PROTOCOL      *This,
 356   IN  EFI_DHCP4_PACKET        *SeedPacket,
 357   IN  UINT32                  DeleteCount,
 358   IN  UINT8                   *DeleteList         OPTIONAL,
 359   IN  UINT32                  AppendCount,
 360   IN  EFI_DHCP4_PACKET_OPTION *AppendList[]       OPTIONAL,
 361   OUT EFI_DHCP4_PACKET        **NewPacket
 362   );
 363 /**
 364   Transmits a DHCP formatted packet and optionally waits for responses.
 365
 366   @param  This    Pointer to the EFI_DHCP4_PROTOCOL instance.
 367   @param  Token   Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.
 368
 369   @retval EFI_SUCCESS           The packet was successfully queued for transmission.
 370   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 371   @retval EFI_NOT_READY         The previous call to this function has not finished yet. Try to call
 372                                 this function after collection process completes.
 373   @retval EFI_NO_MAPPING        The default station address is not available yet.
 374   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 375   @retval Others                Some other unexpected error occurred.
 376
 377 **/
 378 typedef
 379 EFI_STATUS
 380 (EFIAPI *EFI_DHCP4_TRANSMIT_RECEIVE)(
 381   IN EFI_DHCP4_PROTOCOL                *This,
 382   IN EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN  *Token
 383   );
 384
 385
 386 /**
 387   Parses the packed DHCP option data.
 388
 389   @param  This             Pointer to the EFI_DHCP4_PROTOCOL instance.
 390   @param  Packet           Pointer to packet to be parsed.
 391   @param  OptionCount      On input, the number of entries in the PacketOptionList.
 392                            On output, the number of entries that were written into the
 393                            PacketOptionList.
 394   @param  PacketOptionList List of packet option entries to be filled in. End option or pad
 395                            options are not included.
 396
 397   @retval EFI_SUCCESS           The packet was successfully parsed.
 398   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 399   @retval EFI_BUFFER_TOO_SMALL  One or more of the following conditions is TRUE:
 400                                 1) *OptionCount is smaller than the number of options that
 401                                 were found in the Packet.
 402                                 2) PacketOptionList is NULL.
 403
 404 **/
 405 typedef
 406 EFI_STATUS
 407 (EFIAPI *EFI_DHCP4_PARSE)(
 408   IN EFI_DHCP4_PROTOCOL        *This,
 409   IN EFI_DHCP4_PACKET          *Packet,
 410   IN OUT UINT32                *OptionCount,
 411   OUT EFI_DHCP4_PACKET_OPTION  *PacketOptionList[]  OPTIONAL
 412   );
 413
 414 /**
 415   @par Protocol Description:
 416   This protocol is used to collect configuration information for the EFI IPv4 Protocol drivers
 417   and to provide DHCPv4 server and PXE boot server discovery services.
 418 **/
 419 struct _EFI_DHCP4_PROTOCOL {
 420   EFI_DHCP4_GET_MODE_DATA      GetModeData;
 421   EFI_DHCP4_CONFIGURE          Configure;
 422   EFI_DHCP4_START              Start;
 423   EFI_DHCP4_RENEW_REBIND       RenewRebind;
 424   EFI_DHCP4_RELEASE            Release;
 425   EFI_DHCP4_STOP               Stop;
 426   EFI_DHCP4_BUILD              Build;
 427   EFI_DHCP4_TRANSMIT_RECEIVE   TransmitReceive;
 428   EFI_DHCP4_PARSE              Parse;
 429 };
 430
 431 extern EFI_GUID gEfiDhcp4ProtocolGuid;
 432 extern EFI_GUID gEfiDhcp4ServiceBindingProtocolGuid;
 433
 434 #endif