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 - 2018, Intel Corporation. All rights reserved.<BR> 8 SPDX-License-Identifier: BSD-2-Clause-Patent 9 10 @par Revision Reference: 11 This Protocol was introduced in UEFI Specification 2.0. 12 13 **/ 14 15 #ifndef __EFI_DHCP4_PROTOCOL_H__ 16 #define __EFI_DHCP4_PROTOCOL_H__ 17 18 #define EFI_DHCP4_PROTOCOL_GUID \ 19 { \ 20 0x8a219718, 0x4ef5, 0x4761, {0x91, 0xc8, 0xc0, 0xf0, 0x4b, 0xda, 0x9e, 0x56 } \ 21 } 22 23 #define EFI_DHCP4_SERVICE_BINDING_PROTOCOL_GUID \ 24 { \ 25 0x9d9a39d8, 0xbd42, 0x4a73, {0xa4, 0xd5, 0x8e, 0xe9, 0x4b, 0xe1, 0x13, 0x80 } \ 26 } 27 28 typedef struct _EFI_DHCP4_PROTOCOL EFI_DHCP4_PROTOCOL; 29 30 #pragma pack(1) 31 typedef struct { 32 /// 33 /// DHCP option code. 34 /// 35 UINT8 OpCode; 36 /// 37 /// Length of the DHCP option data. Not present if OpCode is 0 or 255. 38 /// 39 UINT8 Length; 40 /// 41 /// Start of the DHCP option data. Not present if OpCode is 0 or 255 or if Length is zero. 42 /// 43 UINT8 Data[1]; 44 } EFI_DHCP4_PACKET_OPTION; 45 #pragma pack() 46 47 #pragma pack(1) 48 /// 49 /// EFI_DHCP4_PACKET defines the format of DHCPv4 packets. See RFC 2131 for more information. 50 /// 51 typedef struct { 52 UINT8 OpCode; 53 UINT8 HwType; 54 UINT8 HwAddrLen; 55 UINT8 Hops; 56 UINT32 Xid; 57 UINT16 Seconds; 58 UINT16 Reserved; 59 EFI_IPv4_ADDRESS ClientAddr; ///< Client IP address from client. 60 EFI_IPv4_ADDRESS YourAddr; ///< Client IP address from server. 61 EFI_IPv4_ADDRESS ServerAddr; ///< IP address of next server in bootstrap. 62 EFI_IPv4_ADDRESS GatewayAddr; ///< Relay agent IP address. 63 UINT8 ClientHwAddr[16]; ///< Client hardware address. 64 CHAR8 ServerName[64]; 65 CHAR8 BootFileName[128]; 66 } EFI_DHCP4_HEADER; 67 #pragma pack() 68 69 #pragma pack(1) 70 typedef struct { 71 /// 72 /// Size of the EFI_DHCP4_PACKET buffer. 73 /// 74 UINT32 Size; 75 /// 76 /// Length of the EFI_DHCP4_PACKET from the first byte of the Header field 77 /// to the last byte of the Option[] field. 78 /// 79 UINT32 Length; 80 81 struct { 82 /// 83 /// DHCP packet header. 84 /// 85 EFI_DHCP4_HEADER Header; 86 /// 87 /// DHCP magik cookie in network byte order. 88 /// 89 UINT32 Magik; 90 /// 91 /// Start of the DHCP packed option data. 92 /// 93 UINT8 Option[1]; 94 } Dhcp4; 95 } EFI_DHCP4_PACKET; 96 #pragma pack() 97 98 typedef enum { 99 /// 100 /// The EFI DHCPv4 Protocol driver is stopped. 101 /// 102 Dhcp4Stopped = 0x0, 103 /// 104 /// The EFI DHCPv4 Protocol driver is inactive. 105 /// 106 Dhcp4Init = 0x1, 107 /// 108 /// The EFI DHCPv4 Protocol driver is collecting DHCP offer packets from DHCP servers. 109 /// 110 Dhcp4Selecting = 0x2, 111 /// 112 /// The EFI DHCPv4 Protocol driver has sent the request to the DHCP server and is waiting for a response. 113 /// 114 Dhcp4Requesting = 0x3, 115 /// 116 /// The DHCP configuration has completed. 117 /// 118 Dhcp4Bound = 0x4, 119 /// 120 /// The DHCP configuration is being renewed and another request has 121 /// been sent out, but it has not received a response from the server yet. 122 /// 123 Dhcp4Renewing = 0x5, 124 /// 125 /// The DHCP configuration has timed out and the EFI DHCPv4 126 /// Protocol driver is trying to extend the lease time. 127 /// 128 Dhcp4Rebinding = 0x6, 129 /// 130 /// The EFI DHCPv4 Protocol driver was initialized with a previously 131 /// allocated or known IP address. 132 /// 133 Dhcp4InitReboot = 0x7, 134 /// 135 /// The EFI DHCPv4 Protocol driver is seeking to reuse the previously 136 /// allocated IP address by sending a request to the DHCP server. 137 /// 138 Dhcp4Rebooting = 0x8 139 } EFI_DHCP4_STATE; 140 141 typedef enum { 142 /// 143 /// The packet to start the configuration sequence is about to be sent. 144 /// 145 Dhcp4SendDiscover = 0x01, 146 /// 147 /// A reply packet was just received. 148 /// 149 Dhcp4RcvdOffer = 0x02, 150 /// 151 /// It is time for Dhcp4Callback to select an offer. 152 /// 153 Dhcp4SelectOffer = 0x03, 154 /// 155 /// A request packet is about to be sent. 156 /// 157 Dhcp4SendRequest = 0x04, 158 /// 159 /// A DHCPACK packet was received and will be passed to Dhcp4Callback. 160 /// 161 Dhcp4RcvdAck = 0x05, 162 /// 163 /// A DHCPNAK packet was received and will be passed to Dhcp4Callback. 164 /// 165 Dhcp4RcvdNak = 0x06, 166 /// 167 /// A decline packet is about to be sent. 168 /// 169 Dhcp4SendDecline = 0x07, 170 /// 171 /// The DHCP configuration process has completed. No packet is associated with this event. 172 /// 173 Dhcp4BoundCompleted = 0x08, 174 /// 175 /// It is time to enter the Dhcp4Renewing state and to contact the server 176 /// that originally issued the network address. No packet is associated with this event. 177 /// 178 Dhcp4EnterRenewing = 0x09, 179 /// 180 /// It is time to enter the Dhcp4Rebinding state and to contact any server. 181 /// No packet is associated with this event. 182 /// 183 Dhcp4EnterRebinding = 0x0a, 184 /// 185 /// The configured IP address was lost either because the lease has expired, 186 /// the user released the configuration, or a DHCPNAK packet was received in 187 /// the Dhcp4Renewing or Dhcp4Rebinding state. No packet is associated with this event. 188 /// 189 Dhcp4AddressLost = 0x0b, 190 /// 191 /// The DHCP process failed because a DHCPNAK packet was received or the user 192 /// aborted the DHCP process at a time when the configuration was not available yet. 193 /// No packet is associated with this event. 194 /// 195 Dhcp4Fail = 0x0c 196 } EFI_DHCP4_EVENT; 197 198 /** 199 Callback routine. 200 201 EFI_DHCP4_CALLBACK is provided by the consumer of the EFI DHCPv4 Protocol driver 202 to intercept events that occurred in the configuration process. This structure 203 provides advanced control of each state transition of the DHCP process. The 204 returned status code determines the behavior of the EFI DHCPv4 Protocol driver. 205 There are three possible returned values, which are described in the following 206 table. 207 208 @param This The pointer to the EFI DHCPv4 Protocol instance that is used to 209 configure this callback function. 210 @param Context The pointer to the context that is initialized by 211 EFI_DHCP4_PROTOCOL.Configure(). 212 @param CurrentState The current operational state of the EFI DHCPv4 Protocol 213 driver. 214 @param Dhcp4Event The event that occurs in the current state, which usually means a 215 state transition. 216 @param Packet The DHCP packet that is going to be sent or already received. 217 @param NewPacket The packet that is used to replace the above Packet. 218 219 @retval EFI_SUCCESS Tells the EFI DHCPv4 Protocol driver to continue the DHCP process. 220 When it is in the Dhcp4Selecting state, it tells the EFI DHCPv4 Protocol 221 driver to stop collecting additional packets. The driver will exit 222 the Dhcp4Selecting state and enter the Dhcp4Requesting state. 223 @retval EFI_NOT_READY Only used in the Dhcp4Selecting state. The EFI DHCPv4 Protocol 224 driver will continue to wait for more packets until the retry 225 timeout expires. 226 @retval EFI_ABORTED Tells the EFI DHCPv4 Protocol driver to abort the current process and 227 return to the Dhcp4Init or Dhcp4InitReboot state. 228 229 **/ 230 typedef 231 EFI_STATUS 232 (EFIAPI *EFI_DHCP4_CALLBACK)( 233 IN EFI_DHCP4_PROTOCOL *This, 234 IN VOID *Context, 235 IN EFI_DHCP4_STATE CurrentState, 236 IN EFI_DHCP4_EVENT Dhcp4Event, 237 IN EFI_DHCP4_PACKET *Packet OPTIONAL, 238 OUT EFI_DHCP4_PACKET **NewPacket OPTIONAL 239 ); 240 241 typedef struct { 242 /// 243 /// The number of times to try sending a packet during the Dhcp4SendDiscover 244 /// event and waiting for a response during the Dhcp4RcvdOffer event. 245 /// Set to zero to use the default try counts and timeout values. 246 /// 247 UINT32 DiscoverTryCount; 248 /// 249 /// The maximum amount of time (in seconds) to wait for returned packets in each 250 /// of the retries. Timeout values of zero will default to a timeout value 251 /// of one second. Set to NULL to use default timeout values. 252 /// 253 UINT32 *DiscoverTimeout; 254 /// 255 /// The number of times to try sending a packet during the Dhcp4SendRequest event 256 /// and waiting for a response during the Dhcp4RcvdAck event before accepting 257 /// failure. Set to zero to use the default try counts and timeout values. 258 /// 259 UINT32 RequestTryCount; 260 /// 261 /// The maximum amount of time (in seconds) to wait for return packets in each of the retries. 262 /// Timeout values of zero will default to a timeout value of one second. 263 /// Set to NULL to use default timeout values. 264 /// 265 UINT32 *RequestTimeout; 266 /// 267 /// For a DHCPDISCOVER, setting this parameter to the previously allocated IP 268 /// address will cause the EFI DHCPv4 Protocol driver to enter the Dhcp4InitReboot state. 269 /// And set this field to 0.0.0.0 to enter the Dhcp4Init state. 270 /// For a DHCPINFORM this parameter should be set to the client network address 271 /// which was assigned to the client during a DHCPDISCOVER. 272 /// 273 EFI_IPv4_ADDRESS ClientAddress; 274 /// 275 /// The callback function to intercept various events that occurred in 276 /// the DHCP configuration process. Set to NULL to ignore all those events. 277 /// 278 EFI_DHCP4_CALLBACK Dhcp4Callback; 279 /// 280 /// The pointer to the context that will be passed to Dhcp4Callback when it is called. 281 /// 282 VOID *CallbackContext; 283 /// 284 /// Number of DHCP options in the OptionList. 285 /// 286 UINT32 OptionCount; 287 /// 288 /// List of DHCP options to be included in every packet that is sent during the 289 /// Dhcp4SendDiscover event. Pad options are appended automatically by DHCP driver 290 /// in outgoing DHCP packets. If OptionList itself contains pad option, they are 291 /// ignored by the driver. OptionList can be freed after EFI_DHCP4_PROTOCOL.Configure() 292 /// returns. Ignored if OptionCount is zero. 293 /// 294 EFI_DHCP4_PACKET_OPTION **OptionList; 295 } EFI_DHCP4_CONFIG_DATA; 296 297 typedef struct { 298 /// 299 /// The EFI DHCPv4 Protocol driver operating state. 300 /// 301 EFI_DHCP4_STATE State; 302 /// 303 /// The configuration data of the current EFI DHCPv4 Protocol driver instance. 304 /// 305 EFI_DHCP4_CONFIG_DATA ConfigData; 306 /// 307 /// The client IP address that was acquired from the DHCP server. If it is zero, 308 /// the DHCP acquisition has not completed yet and the following fields in this structure are undefined. 309 /// 310 EFI_IPv4_ADDRESS ClientAddress; 311 /// 312 /// The local hardware address. 313 /// 314 EFI_MAC_ADDRESS ClientMacAddress; 315 /// 316 /// The server IP address that is providing the DHCP service to this client. 317 /// 318 EFI_IPv4_ADDRESS ServerAddress; 319 /// 320 /// The router IP address that was acquired from the DHCP server. 321 /// May be zero if the server does not offer this address. 322 /// 323 EFI_IPv4_ADDRESS RouterAddress; 324 /// 325 /// The subnet mask of the connected network that was acquired from the DHCP server. 326 /// 327 EFI_IPv4_ADDRESS SubnetMask; 328 /// 329 /// The lease time (in 1-second units) of the configured IP address. 330 /// The value 0xFFFFFFFF means that the lease time is infinite. 331 /// A default lease of 7 days is used if the DHCP server does not provide a value. 332 /// 333 UINT32 LeaseTime; 334 /// 335 /// The cached latest DHCPACK or DHCPNAK or BOOTP REPLY packet. May be NULL if no packet is cached. 336 /// 337 EFI_DHCP4_PACKET *ReplyPacket; 338 } EFI_DHCP4_MODE_DATA; 339 340 typedef struct { 341 /// 342 /// Alternate listening address. It can be a unicast, multicast, or broadcast address. 343 /// 344 EFI_IPv4_ADDRESS ListenAddress; 345 /// 346 /// The subnet mask of above listening unicast/broadcast IP address. 347 /// Ignored if ListenAddress is a multicast address. 348 /// 349 EFI_IPv4_ADDRESS SubnetMask; 350 /// 351 /// Alternate station source (or listening) port number. 352 /// If zero, then the default station port number (68) will be used. 353 /// 354 UINT16 ListenPort; 355 } EFI_DHCP4_LISTEN_POINT; 356 357 typedef struct { 358 /// 359 /// The completion status of transmitting and receiving. 360 /// 361 EFI_STATUS Status; 362 /// 363 /// If not NULL, the event that will be signaled when the collection process 364 /// completes. If NULL, this function will busy-wait until the collection process competes. 365 /// 366 EFI_EVENT CompletionEvent; 367 /// 368 /// The pointer to the server IP address. This address may be a unicast, multicast, or broadcast address. 369 /// 370 EFI_IPv4_ADDRESS RemoteAddress; 371 /// 372 /// The server listening port number. If zero, the default server listening port number (67) will be used. 373 /// 374 UINT16 RemotePort; 375 /// 376 /// The pointer to the gateway address to override the existing setting. 377 /// 378 EFI_IPv4_ADDRESS GatewayAddress; 379 /// 380 /// The number of entries in ListenPoints. If zero, the default station address and port number 68 are used. 381 /// 382 UINT32 ListenPointCount; 383 /// 384 /// An array of station address and port number pairs that are used as receiving filters. 385 /// The first entry is also used as the source address and source port of the outgoing packet. 386 /// 387 EFI_DHCP4_LISTEN_POINT *ListenPoints; 388 /// 389 /// The number of seconds to collect responses. Zero is invalid. 390 /// 391 UINT32 TimeoutValue; 392 /// 393 /// The pointer to the packet to be transmitted. 394 /// 395 EFI_DHCP4_PACKET *Packet; 396 /// 397 /// Number of received packets. 398 /// 399 UINT32 ResponseCount; 400 /// 401 /// The pointer to the allocated list of received packets. 402 /// 403 EFI_DHCP4_PACKET *ResponseList; 404 } EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN; 405 406 /** 407 Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver. 408 409 The GetModeData() function returns the current operating mode and cached data 410 packet for the EFI DHCPv4 Protocol driver. 411 412 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 413 @param Dhcp4ModeData The pointer to storage for the EFI_DHCP4_MODE_DATA structure. 414 415 @retval EFI_SUCCESS The mode data was returned. 416 @retval EFI_INVALID_PARAMETER This is NULL. 417 418 **/ 419 typedef 420 EFI_STATUS 421 (EFIAPI *EFI_DHCP4_GET_MODE_DATA)( 422 IN EFI_DHCP4_PROTOCOL *This, 423 OUT EFI_DHCP4_MODE_DATA *Dhcp4ModeData 424 ); 425 426 /** 427 Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver. 428 429 The Configure() function is used to initialize, change, or reset the operational 430 settings of the EFI DHCPv4 Protocol driver for the communication device on which 431 the EFI DHCPv4 Service Binding Protocol is installed. This function can be 432 successfully called only if both of the following are true: 433 * This instance of the EFI DHCPv4 Protocol driver is in the Dhcp4Stopped, Dhcp4Init, 434 Dhcp4InitReboot, or Dhcp4Bound states. 435 * No other EFI DHCPv4 Protocol driver instance that is controlled by this EFI 436 DHCPv4 Service Binding Protocol driver instance has configured this EFI DHCPv4 437 Protocol driver. 438 When this driver is in the Dhcp4Stopped state, it can transfer into one of the 439 following two possible initial states: 440 * Dhcp4Init 441 * Dhcp4InitReboot. 442 The driver can transfer into these states by calling Configure() with a non-NULL 443 Dhcp4CfgData. The driver will transfer into the appropriate state based on the 444 supplied client network address in the ClientAddress parameter and DHCP options 445 in the OptionList parameter as described in RFC 2131. 446 When Configure() is called successfully while Dhcp4CfgData is set to NULL, the 447 default configuring data will be reset in the EFI DHCPv4 Protocol driver and 448 the state of the EFI DHCPv4 Protocol driver will not be changed. If one instance 449 wants to make it possible for another instance to configure the EFI DHCPv4 Protocol 450 driver, it must call this function with Dhcp4CfgData set to NULL. 451 452 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 453 @param Dhcp4CfgData The pointer to the EFI_DHCP4_CONFIG_DATA. 454 455 @retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Init or 456 Dhcp4InitReboot state, if the original state of this driver 457 was Dhcp4Stopped, Dhcp4Init,Dhcp4InitReboot, or Dhcp4Bound 458 and the value of Dhcp4CfgData was not NULL. 459 Otherwise, the state was left unchanged. 460 @retval EFI_ACCESS_DENIED This instance of the EFI DHCPv4 Protocol driver was not in the 461 Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state; 462 Or onother instance of this EFI DHCPv4 Protocol driver is already 463 in a valid configured state. 464 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: 465 This is NULL. 466 DiscoverTryCount > 0 and DiscoverTimeout is NULL 467 RequestTryCount > 0 and RequestTimeout is NULL. 468 OptionCount >0 and OptionList is NULL. 469 ClientAddress is not a valid unicast address. 470 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 471 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 472 473 **/ 474 typedef 475 EFI_STATUS 476 (EFIAPI *EFI_DHCP4_CONFIGURE)( 477 IN EFI_DHCP4_PROTOCOL *This, 478 IN EFI_DHCP4_CONFIG_DATA *Dhcp4CfgData OPTIONAL 479 ); 480 481 /** 482 Starts the DHCP configuration process. 483 484 The Start() function starts the DHCP configuration process. This function can 485 be called only when the EFI DHCPv4 Protocol driver is in the Dhcp4Init or 486 Dhcp4InitReboot state. 487 If the DHCP process completes successfully, the state of the EFI DHCPv4 Protocol 488 driver will be transferred through Dhcp4Selecting and Dhcp4Requesting to the 489 Dhcp4Bound state. The CompletionEvent will then be signaled if it is not NULL. 490 If the process aborts, either by the user or by some unexpected network error, 491 the state is restored to the Dhcp4Init state. The Start() function can be called 492 again to restart the process. 493 Refer to RFC 2131 for precise state transitions during this process. At the 494 time when each event occurs in this process, the callback function that was set 495 by EFI_DHCP4_PROTOCOL.Configure() will be called and the user can take this 496 opportunity to control the process. 497 498 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 499 @param CompletionEvent If not NULL, it indicates the event that will be signaled when the 500 EFI DHCPv4 Protocol driver is transferred into the 501 Dhcp4Bound state or when the DHCP process is aborted. 502 EFI_DHCP4_PROTOCOL.GetModeData() can be called to 503 check the completion status. If NULL, 504 EFI_DHCP4_PROTOCOL.Start() will wait until the driver 505 is transferred into the Dhcp4Bound state or the process fails. 506 507 @retval EFI_SUCCESS The DHCP configuration process has started, or it has completed 508 when CompletionEvent is NULL. 509 @retval EFI_NOT_STARTED The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped 510 state. EFI_DHCP4_PROTOCOL. Configure() needs to be called. 511 @retval EFI_INVALID_PARAMETER This is NULL. 512 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 513 @retval EFI_TIMEOUT The DHCP configuration process failed because no response was 514 received from the server within the specified timeout value. 515 @retval EFI_ABORTED The user aborted the DHCP process. 516 @retval EFI_ALREADY_STARTED Some other EFI DHCPv4 Protocol instance already started the 517 DHCP process. 518 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 519 @retval EFI_NO_MEDIA There was a media error. 520 521 **/ 522 typedef 523 EFI_STATUS 524 (EFIAPI *EFI_DHCP4_START)( 525 IN EFI_DHCP4_PROTOCOL *This, 526 IN EFI_EVENT CompletionEvent OPTIONAL 527 ); 528 529 /** 530 Extends the lease time by sending a request packet. 531 532 The RenewRebind() function is used to manually extend the lease time when the 533 EFI DHCPv4 Protocol driver is in the Dhcp4Bound state, and the lease time has 534 not expired yet. This function will send a request packet to the previously 535 found server (or to any server when RebindRequest is TRUE) and transfer the 536 state into the Dhcp4Renewing state (or Dhcp4Rebinding when RebindingRequest is 537 TRUE). When a response is received, the state is returned to Dhcp4Bound. 538 If no response is received before the try count is exceeded (the RequestTryCount 539 field that is specified in EFI_DHCP4_CONFIG_DATA) but before the lease time that 540 was issued by the previous server expires, the driver will return to the Dhcp4Bound 541 state, and the previous configuration is restored. The outgoing and incoming packets 542 can be captured by the EFI_DHCP4_CALLBACK function. 543 544 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 545 @param RebindRequest If TRUE, this function broadcasts the request packets and enters 546 the Dhcp4Rebinding state. Otherwise, it sends a unicast 547 request packet and enters the Dhcp4Renewing state. 548 @param CompletionEvent If not NULL, this event is signaled when the renew/rebind phase 549 completes or some error occurs. 550 EFI_DHCP4_PROTOCOL.GetModeData() can be called to 551 check the completion status. If NULL, 552 EFI_DHCP4_PROTOCOL.RenewRebind() will busy-wait 553 until the DHCP process finishes. 554 555 @retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the 556 Dhcp4Renewing state or is back to the Dhcp4Bound state. 557 @retval EFI_NOT_STARTED The EFI DHCPv4 Protocol driver is in the Dhcp4Stopped 558 state. EFI_DHCP4_PROTOCOL.Configure() needs to 559 be called. 560 @retval EFI_INVALID_PARAMETER This is NULL. 561 @retval EFI_TIMEOUT There was no response from the server when the try count was 562 exceeded. 563 @retval EFI_ACCESS_DENIED The driver is not in the Dhcp4Bound state. 564 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 565 566 **/ 567 typedef 568 EFI_STATUS 569 (EFIAPI *EFI_DHCP4_RENEW_REBIND)( 570 IN EFI_DHCP4_PROTOCOL *This, 571 IN BOOLEAN RebindRequest, 572 IN EFI_EVENT CompletionEvent OPTIONAL 573 ); 574 575 /** 576 Releases the current address configuration. 577 578 The Release() function releases the current configured IP address by doing either 579 of the following: 580 * Sending a DHCPRELEASE packet when the EFI DHCPv4 Protocol driver is in the 581 Dhcp4Bound state 582 * Setting the previously assigned IP address that was provided with the 583 EFI_DHCP4_PROTOCOL.Configure() function to 0.0.0.0 when the driver is in 584 Dhcp4InitReboot state 585 After a successful call to this function, the EFI DHCPv4 Protocol driver returns 586 to the Dhcp4Init state, and any subsequent incoming packets will be discarded silently. 587 588 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 589 590 @retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase. 591 @retval EFI_INVALID_PARAMETER This is NULL. 592 @retval EFI_ACCESS_DENIED The EFI DHCPv4 Protocol driver is not Dhcp4InitReboot state. 593 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 594 595 **/ 596 typedef 597 EFI_STATUS 598 (EFIAPI *EFI_DHCP4_RELEASE)( 599 IN EFI_DHCP4_PROTOCOL *This 600 ); 601 602 /** 603 Stops the current address configuration. 604 605 The Stop() function is used to stop the DHCP configuration process. After this 606 function is called successfully, the EFI DHCPv4 Protocol driver is transferred 607 into the Dhcp4Stopped state. EFI_DHCP4_PROTOCOL.Configure() needs to be called 608 before DHCP configuration process can be started again. This function can be 609 called when the EFI DHCPv4 Protocol driver is in any state. 610 611 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 612 613 @retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase. 614 @retval EFI_INVALID_PARAMETER This is NULL. 615 616 **/ 617 typedef 618 EFI_STATUS 619 (EFIAPI *EFI_DHCP4_STOP)( 620 IN EFI_DHCP4_PROTOCOL *This 621 ); 622 623 /** 624 Builds a DHCP packet, given the options to be appended or deleted or replaced. 625 626 The Build() function is used to assemble a new packet from the original packet 627 by replacing or deleting existing options or appending new options. This function 628 does not change any state of the EFI DHCPv4 Protocol driver and can be used at 629 any time. 630 631 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 632 @param SeedPacket Initial packet to be used as a base for building new packet. 633 @param DeleteCount Number of opcodes in the DeleteList. 634 @param DeleteList List of opcodes to be deleted from the seed packet. 635 Ignored if DeleteCount is zero. 636 @param AppendCount Number of entries in the OptionList. 637 @param AppendList The pointer to a DHCP option list to be appended to SeedPacket. 638 If SeedPacket also contains options in this list, they are 639 replaced by new options (except pad option). Ignored if 640 AppendCount is zero. Type EFI_DHCP4_PACKET_OPTION 641 @param NewPacket The pointer to storage for the pointer to the new allocated packet. 642 Use the EFI Boot Service FreePool() on the resulting pointer 643 when done with the packet. 644 645 @retval EFI_SUCCESS The new packet was built. 646 @retval EFI_OUT_OF_RESOURCES Storage for the new packet could not be allocated. 647 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: 648 This is NULL. 649 SeedPacket is NULL. 650 SeedPacket is not a well-formed DHCP packet. 651 AppendCount is not zero and AppendList is NULL. 652 DeleteCount is not zero and DeleteList is NULL. 653 NewPacket is NULL 654 Both DeleteCount and AppendCount are zero and 655 NewPacket is not NULL. 656 657 **/ 658 typedef 659 EFI_STATUS 660 (EFIAPI *EFI_DHCP4_BUILD)( 661 IN EFI_DHCP4_PROTOCOL *This, 662 IN EFI_DHCP4_PACKET *SeedPacket, 663 IN UINT32 DeleteCount, 664 IN UINT8 *DeleteList OPTIONAL, 665 IN UINT32 AppendCount, 666 IN EFI_DHCP4_PACKET_OPTION *AppendList[] OPTIONAL, 667 OUT EFI_DHCP4_PACKET **NewPacket 668 ); 669 670 /** 671 Transmits a DHCP formatted packet and optionally waits for responses. 672 673 The TransmitReceive() function is used to transmit a DHCP packet and optionally 674 wait for the response from servers. This function does not change the state of 675 the EFI DHCPv4 Protocol driver. It can be used at any time because of this. 676 677 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 678 @param Token The pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure. 679 680 @retval EFI_SUCCESS The packet was successfully queued for transmission. 681 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: 682 This is NULL. 683 Token.RemoteAddress is zero. 684 Token.Packet is NULL. 685 Token.Packet is not a well-formed DHCP packet. 686 The transaction ID in Token.Packet is in use by another DHCP process. 687 @retval EFI_NOT_READY The previous call to this function has not finished yet. Try to call 688 this function after collection process completes. 689 @retval EFI_NO_MAPPING The default station address is not available yet. 690 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 691 @retval EFI_UNSUPPORTED The implementation doesn't support this function 692 @retval Others Some other unexpected error occurred. 693 694 **/ 695 typedef 696 EFI_STATUS 697 (EFIAPI *EFI_DHCP4_TRANSMIT_RECEIVE)( 698 IN EFI_DHCP4_PROTOCOL *This, 699 IN EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN *Token 700 ); 701 702 /** 703 Parses the packed DHCP option data. 704 705 The Parse() function is used to retrieve the option list from a DHCP packet. 706 If *OptionCount isn't zero, and there is enough space for all the DHCP options 707 in the Packet, each element of PacketOptionList is set to point to somewhere in 708 the Packet->Dhcp4.Option where a new DHCP option begins. If RFC3396 is supported, 709 the caller should reassemble the parsed DHCP options to get the final result. 710 If *OptionCount is zero or there isn't enough space for all of them, the number 711 of DHCP options in the Packet is returned in OptionCount. 712 713 @param This The pointer to the EFI_DHCP4_PROTOCOL instance. 714 @param Packet The pointer to packet to be parsed. 715 @param OptionCount On input, the number of entries in the PacketOptionList. 716 On output, the number of entries that were written into the 717 PacketOptionList. 718 @param PacketOptionList A list of packet option entries to be filled in. End option or pad 719 options are not included. 720 721 @retval EFI_SUCCESS The packet was successfully parsed. 722 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE: 723 This is NULL. 724 The packet is NULL. 725 The packet is not a well-formed DHCP packet. 726 OptionCount is NULL. 727 @retval EFI_BUFFER_TOO_SMALL One or more of the following conditions is TRUE: 728 1) *OptionCount is smaller than the number of options that 729 were found in the Packet. 730 2) PacketOptionList is NULL. 731 @retval EFI_OUT_OF_RESOURCE The packet failed to parse because of a resource shortage. 732 733 **/ 734 typedef 735 EFI_STATUS 736 (EFIAPI *EFI_DHCP4_PARSE)( 737 IN EFI_DHCP4_PROTOCOL *This, 738 IN EFI_DHCP4_PACKET *Packet, 739 IN OUT UINT32 *OptionCount, 740 OUT EFI_DHCP4_PACKET_OPTION *PacketOptionList[] OPTIONAL 741 ); 742 743 /// 744 /// This protocol is used to collect configuration information for the EFI IPv4 Protocol drivers 745 /// and to provide DHCPv4 server and PXE boot server discovery services. 746 /// 747 struct _EFI_DHCP4_PROTOCOL { 748 EFI_DHCP4_GET_MODE_DATA GetModeData; 749 EFI_DHCP4_CONFIGURE Configure; 750 EFI_DHCP4_START Start; 751 EFI_DHCP4_RENEW_REBIND RenewRebind; 752 EFI_DHCP4_RELEASE Release; 753 EFI_DHCP4_STOP Stop; 754 EFI_DHCP4_BUILD Build; 755 EFI_DHCP4_TRANSMIT_RECEIVE TransmitReceive; 756 EFI_DHCP4_PARSE Parse; 757 }; 758 759 extern EFI_GUID gEfiDhcp4ProtocolGuid; 760 extern EFI_GUID gEfiDhcp4ServiceBindingProtocolGuid; 761 762 #endif 763