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, 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 /**
 206   Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver.
 207
 208   @param  This                   Pointer to the EFI_DHCP4_PROTOCOL instance.
 209   @param  Dhcp4CfgData           Pointer to the EFI_DHCP4_CONFIG_DATA.
 210
 211   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init or
 212                                 Dhcp4InitReboot state, if the original state of this driver
 213                                 was Dhcp4Stopped and the value of Dhcp4CfgData was
 214                                 not NULL. Otherwise, the state was left unchanged.
 215   @retval EFI_ACCESS_DENIED     This instance of the EFI DHCPv4 Protocol driver was not in the
 216                                 Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;
 217                                 Or onother instance of this EFI DHCPv4 Protocol driver is already
 218                                 in a valid configured state.
 219   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 220   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 221   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 222
 223 **/
 224 typedef
 225 EFI_STATUS
 226 (EFIAPI *EFI_DHCP4_CONFIGURE) (
 227   IN EFI_DHCP4_PROTOCOL       *This,
 228   IN EFI_DHCP4_CONFIG_DATA    *Dhcp4CfgData  OPTIONAL
 229   )
 230 ;
 231
 232
 233 /**
 234   Starts the DHCP configuration process.
 235
 236   @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.
 237   @param  CompletionEvent If not NULL, indicates the event that will be signaled when the
 238                           EFI DHCPv4 Protocol driver is transferred into the
 239                           Dhcp4Bound state or when the DHCP process is aborted.
 240                           EFI_DHCP4_PROTOCOL.GetModeData() can be called to
 241                           check the completion status. If NULL,
 242                           EFI_DHCP4_PROTOCOL.Start() will wait until the driver
 243                           is transferred into the Dhcp4Bound state or the process fails.
 244
 245   @retval EFI_SUCCESS           The DHCP configuration process has started, or it has completed
 246                                 when CompletionEvent is NULL.
 247   @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped
 248                                 state. EFI_DHCP4_PROTOCOL. Configure() needs to be called.
 249   @retval EFI_INVALID_PARAMETER This is NULL.
 250   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 251   @retval EFI_TIMEOUT           The DHCP configuration process failed because no response was
 252                                 received from the server within the specified timeout value.
 253   @retval EFI_ABORTED           The user aborted the DHCP process.
 254   @retval EFI_ALREADY_STARTED   Some other EFI DHCPv4 Protocol instance already started the
 255                                 DHCP process.
 256   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 257
 258 **/
 259 typedef
 260 EFI_STATUS
 261 (EFIAPI *EFI_DHCP4_START) (
 262   IN EFI_DHCP4_PROTOCOL       *This,
 263   IN EFI_EVENT                CompletionEvent   OPTIONAL
 264   )
 265 ;
 266
 267 /**
 268   Extends the lease time by sending a request packet.
 269
 270   @param  This            Pointer to the EFI_DHCP4_PROTOCOL instance.
 271   @param  RebindRequest   If TRUE, this function broadcasts the request packets and enters
 272                           the Dhcp4Rebinding state. Otherwise, it sends a unicast
 273                           request packet and enters the Dhcp4Renewing state.
 274   @param  CompletionEvent If not NULL, this event is signaled when the renew/rebind phase
 275                           completes or some error occurs.
 276                           EFI_DHCP4_PROTOCOL.GetModeData() can be called to
 277                           check the completion status. If NULL,
 278                           EFI_DHCP4_PROTOCOL.RenewRebind() will busy-wait
 279                           until the DHCP process finishes.
 280
 281   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the
 282                                 Dhcp4Renewing state or is back to the Dhcp4Bound state.
 283   @retval EFI_NOT_STARTED       The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped
 284                                 state. EFI_DHCP4_PROTOCOL.Configure() needs to
 285                                 be called.
 286   @retval EFI_INVALID_PARAMETER This is NULL.
 287   @retval EFI_TIMEOUT           There was no response from the server when the try count was
 288                                 exceeded.
 289   @retval EFI_ACCESS_DENIED     The driver is not in the Dhcp4Bound state.
 290   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 291
 292 **/
 293 typedef
 294 EFI_STATUS
 295 (EFIAPI *EFI_DHCP4_RENEW_REBIND) (
 296   IN EFI_DHCP4_PROTOCOL       *This,
 297   IN BOOLEAN                  RebindRequest,
 298   IN EFI_EVENT                CompletionEvent  OPTIONAL
 299   )
 300 ;
 301
 302 /**
 303   Releases the current address configuration.
 304
 305   @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.
 306
 307   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase.
 308   @retval EFI_INVALID_PARAMETER This is NULL.
 309   @retval EFI_ACCESS_DENIED     The EFI DHCPv4 Protocol driver is not Dhcp4InitReboot state.
 310   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 311
 312 **/
 313 typedef
 314 EFI_STATUS
 315 (EFIAPI *EFI_DHCP4_RELEASE) (
 316   IN EFI_DHCP4_PROTOCOL       *This
 317   )
 318 ;
 319
 320 /**
 321   Stops the current address configuration.
 322
 323   @param  This                  Pointer to the EFI_DHCP4_PROTOCOL instance.
 324
 325   @retval EFI_SUCCESS           The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase.
 326   @retval EFI_INVALID_PARAMETER This is NULL.
 327
 328 **/
 329 typedef
 330 EFI_STATUS
 331 (EFIAPI *EFI_DHCP4_STOP) (
 332   IN EFI_DHCP4_PROTOCOL       *This
 333   )
 334 ;
 335
 336 /**
 337   Builds a DHCP packet, given the options to be appended or deleted or replaced.
 338
 339   @param  This        Pointer to the EFI_DHCP4_PROTOCOL instance.
 340  @param  SeedPacket  Initial packet to be used as a base for building new packet.
 341   @param  DeleteCount Number of opcodes in the DeleteList.
 342   @param  DeleteList  List of opcodes to be deleted from the seed packet.
 343                       Ignored if DeleteCount is zero.
 344   @param  AppendCount Number of entries in the OptionList.
 345   @param  AppendList  Pointer to a DHCP option list to be appended to SeedPacket.
 346                       If SeedPacket also contains options in this list, they are
 347                       replaced by new options (except pad option). Ignored if
 348                       AppendCount is zero. Type EFI_DHCP4_PACKET_OPTION
 349   @param  NewPacket   Pointer to storage for the pointer to the new allocated packet.
 350                       Use the EFI Boot Service FreePool() on the resulting pointer
 351                       when done with the packet.
 352
 353   @retval EFI_SUCCESS           The new packet was built.
 354   @retval EFI_OUT_OF_RESOURCES  Storage for the new packet could not be allocated.
 355   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 356
 357 **/
 358 typedef
 359 EFI_STATUS
 360 (EFIAPI *EFI_DHCP4_BUILD) (
 361   IN  EFI_DHCP4_PROTOCOL      *This,
 362   IN  EFI_DHCP4_PACKET        *SeedPacket,
 363   IN  UINT32                  DeleteCount,
 364   IN  UINT8                   *DeleteList         OPTIONAL,
 365   IN  UINT32                  AppendCount,
 366   IN  EFI_DHCP4_PACKET_OPTION *AppendList[]       OPTIONAL,
 367   OUT EFI_DHCP4_PACKET        **NewPacket
 368   )
 369 ;
 370 /**
 371   Transmits a DHCP formatted packet and optionally waits for responses.
 372
 373   @param  This    Pointer to the EFI_DHCP4_PROTOCOL instance.
 374   @param  Token   Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.
 375
 376   @retval EFI_SUCCESS           The packet was successfully queued for transmission.
 377   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 378   @retval EFI_NOT_READY         The previous call to this function has not finished yet. Try to call
 379                                 this function after collection process completes.
 380   @retval EFI_NO_MAPPING        The default station address is not available yet.
 381   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 382   @retval Others                Some other unexpected error occurred.
 383
 384 **/
 385 typedef
 386 EFI_STATUS
 387 (EFIAPI *EFI_DHCP4_TRANSMIT_RECEIVE) (
 388   IN EFI_DHCP4_PROTOCOL                *This,
 389   IN EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN  *Token
 390   )
 391 ;
 392
 393
 394 /**
 395   Parses the packed DHCP option data.
 396
 397   @param  This             Pointer to the EFI_DHCP4_PROTOCOL instance.
 398   @param  Packet           Pointer to packet to be parsed.
 399   @param  OptionCount      On input, the number of entries in the PacketOptionList.
 400                            On output, the number of entries that were written into the
 401                            PacketOptionList.
 402   @param  PacketOptionList List of packet option entries to be filled in. End option or pad
 403                            options are not included.
 404
 405   @retval EFI_SUCCESS           The packet was successfully parsed.
 406   @retval EFI_INVALID_PARAMETER Some parameter is NULL.
 407   @retval EFI_BUFFER_TOO_SMALL  One or more of the following conditions is TRUE:
 408                                 1) *OptionCount is smaller than the number of options that
 409                                 were found in the Packet.
 410                                 2) PacketOptionList is NULL.
 411
 412 **/
 413 typedef
 414 EFI_STATUS
 415 (EFIAPI *EFI_DHCP4_PARSE) (
 416   IN EFI_DHCP4_PROTOCOL        *This,
 417   IN EFI_DHCP4_PACKET          *Packet,
 418   IN OUT UINT32                *OptionCount,
 419   OUT EFI_DHCP4_PACKET_OPTION  *PacketOptionList[]  OPTIONAL
 420   )
 421 ;
 422
 423
 424 struct _EFI_DHCP4_PROTOCOL {
 425   EFI_DHCP4_GET_MODE_DATA      GetModeData;
 426   EFI_DHCP4_CONFIGURE          Configure;
 427   EFI_DHCP4_START              Start;
 428   EFI_DHCP4_RENEW_REBIND       RenewRebind;
 429   EFI_DHCP4_RELEASE            Release;
 430   EFI_DHCP4_STOP               Stop;
 431   EFI_DHCP4_BUILD              Build;
 432   EFI_DHCP4_TRANSMIT_RECEIVE   TransmitReceive;
 433   EFI_DHCP4_PARSE              Parse;
 434 };
 435
 436 extern EFI_GUID gEfiDhcp4ProtocolGuid;
 437 extern EFI_GUID gEfiDhcp4ServiceBindingProtocolGuid;
 438
 439 #endif