1 /** @file 2 UEFI Dynamic Host Configuration Protocol 6 Definition, which is used to get IPv6 3 addresses and other configuration parameters from DHCPv6 servers. 4 5 Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions of the BSD License 8 which accompanies this distribution. The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 @par Revision Reference: 15 This Protocol is introduced in UEFI Specification 2.2 16 17 **/ 18 19 #ifndef __EFI_DHCP6_PROTOCOL_H__ 20 #define __EFI_DHCP6_PROTOCOL_H__ 21 22 #define EFI_DHCP6_PROTOCOL_GUID \ 23 { \ 24 0x87c8bad7, 0x595, 0x4053, {0x82, 0x97, 0xde, 0xde, 0x39, 0x5f, 0x5d, 0x5b } \ 25 } 26 27 #define EFI_DHCP6_SERVICE_BINDING_PROTOCOL_GUID \ 28 { \ 29 0x9fb9a8a1, 0x2f4a, 0x43a6, {0x88, 0x9c, 0xd0, 0xf7, 0xb6, 0xc4, 0x7a, 0xd5 } \ 30 } 31 32 typedef struct _EFI_DHCP6_PROTOCOL EFI_DHCP6_PROTOCOL; 33 34 typedef enum { 35 /// 36 /// The EFI DHCPv6 Protocol instance is configured, and start() needs 37 /// to be called 38 /// 39 Dhcp6Init = 0x0, 40 /// 41 /// A Solicit packet is sent out to discover DHCPv6 server, and the EFI 42 /// DHCPv6 Protocol instance is collecting Advertise packets. 43 /// 44 Dhcp6Selecting = 0x1, 45 /// 46 /// A Request is sent out to the DHCPv6 server, and the EFI DHCPv6 47 /// Protocol instance is waiting for Reply packet. 48 /// 49 Dhcp6Requesting = 0x2, 50 /// 51 /// A Decline packet is sent out to indicate one or more addresses of the 52 /// configured IA are in use by another node, and the EFI DHCPv6. 53 /// Protocol instance is waiting for Reply packet. 54 /// 55 Dhcp6Declining = 0x3, 56 /// 57 /// A Confirm packet is sent out to confirm the IPv6 addresses of the 58 /// configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet. 59 /// 60 Dhcp6Confirming = 0x4, 61 /// 62 /// A Release packet is sent out to release one or more IPv6 addresses of 63 /// the configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet. 64 /// 65 Dhcp6Releasing = 0x5, 66 /// 67 /// The DHCPv6 S.A.R.R process is completed for the configured IA. 68 /// 69 Dhcp6Bound = 0x6, 70 /// 71 /// A Renew packet is sent out to extend lifetime for the IPv6 addresses of 72 /// the configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet. 73 /// 74 Dhcp6Renewing = 0x7, 75 /// 76 /// A Rebind packet is sent out to extend lifetime for the IPv6 addresses of 77 /// the configured IA, and the EFI DHCPv6 Protocol instance is waiting for Reply packet. 78 /// 79 Dhcp6Rebinding = 0x8 80 } EFI_DHCP6_STATE; 81 82 typedef enum { 83 /// 84 /// A Solicit packet is about to be sent. The packet is passed to Dhcp6Callback and 85 /// can be modified or replaced in Dhcp6Callback. 86 /// 87 Dhcp6SendSolicit = 0x0, 88 /// 89 /// An Advertise packet is received and will be passed to Dhcp6Callback. 90 /// 91 Dhcp6RcvdAdvertise = 0x1, 92 /// 93 /// It is time for Dhcp6Callback to determine whether select the default Advertise 94 /// packet by RFC 3315 policy, or overwrite it by specific user policy. 95 /// 96 Dhcp6SelectAdvertise = 0x2, 97 /// 98 /// A Request packet is about to be sent. The packet is passed to Dhcp6Callback and 99 /// can be modified or replaced in Dhcp6Callback. 100 /// 101 Dhcp6SendRequest = 0x3, 102 /// 103 /// A Reply packet is received and will be passed to Dhcp6Callback. 104 /// 105 Dhcp6RcvdReply = 0x4, 106 /// 107 /// A Reconfigure packet is received and will be passed to Dhcp6Callback. 108 /// 109 Dhcp6RcvdReconfigure = 0x5, 110 /// 111 /// A Decline packet is about to be sent. The packet is passed to Dhcp6Callback and 112 /// can be modified or replaced in Dhcp6Callback. 113 /// 114 Dhcp6SendDecline = 0x6, 115 /// 116 /// A Confirm packet is about to be sent. The packet is passed to Dhcp6Callback and 117 /// can be modified or replaced in Dhcp6Callback. 118 /// 119 Dhcp6SendConfirm = 0x7, 120 /// 121 /// A Release packet is about to be sent. The packet is passed to Dhcp6Callback and 122 /// can be modified or replaced in Dhcp6Callback. 123 /// 124 Dhcp6SendRelease = 0x8, 125 /// 126 /// A Renew packet is about to be sent. The packet is passed to Dhcp6Callback and 127 /// can be modified or replaced in Dhcp6Callback. 128 /// 129 Dhcp6EnterRenewing = 0x9, 130 /// 131 /// A Rebind packet is about to be sent. The packet is passed to Dhcp6Callback and 132 /// can be modified or replaced in Dhcp6Callback. 133 /// 134 Dhcp6EnterRebinding = 0xa 135 } EFI_DHCP6_EVENT; 136 137 /// 138 /// An IA which carries assigned not temporary address. 139 /// 140 #define EFI_DHCP6_IA_TYPE_NA 3 141 /// 142 /// An IA which carries assigned temporary address. 143 /// 144 #define EFI_DHCP6_IA_TYPE_TA 4 145 146 #pragma pack(1) 147 /// 148 /// EFI_DHCP6_PACKET_OPTION 149 /// defines the format of the DHCPv6 option, See RFC 3315 for more information. 150 /// This data structure is used to reference option data that is packed in the DHCPv6 packet. 151 /// 152 typedef struct { 153 /// 154 /// The DHCPv6 option code, stored in network order. 155 /// 156 UINT16 OpCode; 157 /// 158 /// Length of the DHCPv6 option data, stored in network order. 159 /// From the first byte to the last byte of the Data field. 160 /// 161 UINT16 OpLen; 162 /// 163 /// The data for the DHCPv6 option, stored in network order. 164 /// 165 UINT8 Data[1]; 166 } EFI_DHCP6_PACKET_OPTION; 167 168 /// 169 /// EFI_DHCP6_HEADER 170 /// defines the format of the DHCPv6 header. See RFC 3315 for more information. 171 /// 172 typedef struct{ 173 /// 174 /// The DHCPv6 transaction ID. 175 /// 176 UINT32 MessageType:8; 177 /// 178 /// The DHCPv6 message type. 179 /// 180 UINT32 TransactionId:24; 181 } EFI_DHCP6_HEADER; 182 183 /// 184 /// EFI_DHCP6_PACKET 185 /// defines the format of the DHCPv6 packet. See RFC 3315 for more information. 186 /// 187 typedef struct { 188 /// 189 /// Size of the EFI_DHCP6_PACKET buffer. 190 /// 191 UINT32 Size; 192 /// 193 /// Length of the EFI_DHCP6_PACKET from the first byte of the Header field to the last 194 /// byte of the Option[] field. 195 /// 196 UINT32 Length; 197 struct{ 198 /// 199 /// The DHCPv6 packet header. 200 /// 201 EFI_DHCP6_HEADER Header; 202 /// 203 /// Start of the DHCPv6 packed option data. 204 /// 205 UINT8 Option[1]; 206 } Dhcp6; 207 } EFI_DHCP6_PACKET; 208 209 #pragma pack() 210 211 typedef struct { 212 /// 213 /// Length of DUID in octects. 214 /// 215 UINT16 Length; 216 /// 217 /// Array of DUID octects. 218 /// 219 UINT8 Duid[1]; 220 } EFI_DHCP6_DUID; 221 222 typedef struct { 223 /// 224 /// Initial retransmission timeout. 225 /// 226 UINT32 Irt; 227 /// 228 /// Maximum retransmission count for one packet. If Mrc is zero, there's no upper limit 229 /// for retransmission count. 230 /// 231 UINT32 Mrc; 232 /// 233 /// Maximum retransmission timeout for each retry. It's the upper bound of the number of 234 /// retransmission timeout. If Mrt is zero, there is no upper limit for retransmission 235 /// timeout. 236 /// 237 UINT32 Mrt; 238 /// 239 /// Maximum retransmission duration for one packet. It's the upper bound of the numbers 240 /// the client may retransmit a message. If Mrd is zero, there's no upper limit for 241 /// retransmission duration. 242 /// 243 UINT32 Mrd; 244 } EFI_DHCP6_RETRANSMISSION; 245 246 typedef struct { 247 /// 248 /// The IPv6 address. 249 /// 250 EFI_IPv6_ADDRESS IpAddress; 251 /// 252 /// The preferred lifetime in unit of seconds for the IPv6 address. 253 /// 254 UINT32 PreferredLifetime; 255 /// 256 /// The valid lifetime in unit of seconds for the IPv6 address. 257 /// 258 UINT32 ValidLifetime; 259 } EFI_DHCP6_IA_ADDRESS; 260 261 typedef struct { 262 UINT16 Type; ///< Type for an IA. 263 UINT32 IaId; ///< The identifier for an IA. 264 } EFI_DHCP6_IA_DESCRIPTOR; 265 266 typedef struct { 267 /// 268 /// The descriptor for IA. 269 /// 270 EFI_DHCP6_IA_DESCRIPTOR Descriptor; 271 /// 272 /// The state of the configured IA. 273 /// 274 EFI_DHCP6_STATE State; 275 /// 276 /// Pointer to the cached latest Reply packet. May be NULL if no packet is cached. 277 /// 278 EFI_DHCP6_PACKET *ReplyPacket; 279 /// 280 /// Number of IPv6 addresses of the configured IA. 281 /// 282 UINT32 IaAddressCount; 283 /// 284 /// List of the IPv6 addresses of the configured IA. When the state of the configured IA is 285 /// in Dhcp6Bound, Dhcp6Renewing and Dhcp6Rebinding, the IPv6 addresses are usable. 286 /// 287 EFI_DHCP6_IA_ADDRESS IaAddress[1]; 288 } EFI_DHCP6_IA; 289 290 typedef struct { 291 /// 292 /// Pointer to the DHCPv6 unique identifier. The caller is responsible for freeing this buffer. 293 /// 294 EFI_DHCP6_DUID *ClientId; 295 /// 296 /// Pointer to the configured IA of current instance. The caller can free this buffer after 297 /// using it. 298 /// 299 EFI_DHCP6_IA *Ia; 300 } EFI_DHCP6_MODE_DATA; 301 302 /** 303 EFI_DHCP6_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol instance to 304 intercept events that occurs in the DHCPv6 S.A.R.R process. 305 306 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this 307 callback function. 308 @param[in] Context Pointer to the context that is initialized by EFI_DHCP6_PROTOCOL.Configure(). 309 @param[in] CurrentState The current state of the configured IA. 310 @param[in] Dhcp6Event The event that occurs in the current state, which usually means a state transition. 311 @param[in] Packet Pointer to the DHCPv6 packet that is about to be sent or has been received. 312 The EFI DHCPv6 Protocol instance is responsible for freeing the buffer. 313 @param[out] NewPacket Pointer to the new DHCPv6 packet to overwrite the Packet. NewPacket can not 314 share the buffer with Packet. If *NewPacket is not NULL, the EFI DHCPv6 315 Protocol instance is responsible for freeing the buffer. 316 317 @retval EFI_SUCCESS Tell the EFI DHCPv6 Protocol instance to continue the DHCPv6 S.A.R.R process. 318 @retval EFI_ABORTED Tell the EFI DHCPv6 Protocol instance to abort the DHCPv6 S.A.R.R process, 319 and the state of the configured IA will be transferred to Dhcp6Init. 320 321 **/ 322 typedef 323 EFI_STATUS 324 (EFIAPI *EFI_DHCP6_CALLBACK)( 325 IN EFI_DHCP6_PROTOCOL *This, 326 IN VOID *Context, 327 IN EFI_DHCP6_STATE CurrentState, 328 IN EFI_DHCP6_EVENT Dhcp6Event, 329 IN EFI_DHCP6_PACKET *Packet, 330 OUT EFI_DHCP6_PACKET **NewPacket OPTIONAL 331 ); 332 333 typedef struct { 334 /// 335 /// The callback function is to intercept various events that occur in the DHCPv6 S.A.R.R 336 /// process. Set to NULL to ignore all those events. 337 /// 338 EFI_DHCP6_CALLBACK Dhcp6Callback; 339 /// 340 /// Pointer to the context that will be passed to Dhcp6Callback. 341 /// 342 VOID *CallbackContext; 343 /// 344 /// Number of the DHCPv6 options in the OptionList. 345 /// 346 UINT32 OptionCount; 347 /// 348 /// List of the DHCPv6 options to be included in Solicit and Request packet. The buffer 349 /// can be freed after EFI_DHCP6_PROTOCOL.Configure() returns. Ignored if 350 /// OptionCount is zero. OptionList should not contain Client Identifier option 351 /// and any IA option, which will be appended by EFI DHCPv6 Protocol instance 352 /// automatically. 353 /// 354 EFI_DHCP6_PACKET_OPTION **OptionList; 355 /// 356 /// The descriptor for the IA of the EFI DHCPv6 Protocol instance. 357 /// 358 EFI_DHCP6_IA_DESCRIPTOR IaDescriptor; 359 /// 360 /// If not NULL, the event will be signaled when any IPv6 address information of the 361 /// configured IA is updated, including IPv6 address, preferred lifetime and valid 362 /// lifetime, or the DHCPv6 S.A.R.R process fails. Otherwise, Start(), 363 /// renewrebind(), decline(), release() and stop() will be blocking 364 /// operations, and they will wait for the exchange process completion or failure. 365 /// 366 EFI_EVENT IaInfoEvent; 367 /// 368 /// If TRUE, the EFI DHCPv6 Protocol instance is willing to accept Reconfigure packet. 369 /// Otherwise, it will ignore it. Reconfigure Accept option can not be specified through 370 /// OptionList parameter. 371 /// 372 BOOLEAN ReconfigureAccept; 373 /// 374 /// If TRUE, the EFI DHCPv6 Protocol instance will send Solicit packet with Rapid 375 /// Commit option. Otherwise, Rapid Commit option will not be included in Solicit 376 /// packet. Rapid Commit option can not be specified through OptionList parameter. 377 /// 378 BOOLEAN RapidCommit; 379 /// 380 /// Parameter to control Solicit packet retransmission behavior. The 381 /// buffer can be freed after EFI_DHCP6_PROTOCOL.Configure() returns. 382 /// 383 EFI_DHCP6_RETRANSMISSION *SolicitRetransmission; 384 } EFI_DHCP6_CONFIG_DATA; 385 386 /** 387 EFI_DHCP6_INFO_CALLBACK is provided by the consumer of the EFI DHCPv6 Protocol 388 instance to intercept events that occurs in the DHCPv6 Information Request exchange process. 389 390 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance that is used to configure this 391 callback function. 392 @param[in] Context Pointer to the context that is initialized in the EFI_DHCP6_PROTOCOL.InfoRequest(). 393 @param[in] Packet Pointer to Reply packet that has been received. The EFI DHCPv6 Protocol instance is 394 responsible for freeing the buffer. 395 396 @retval EFI_SUCCESS Tell the EFI DHCPv6 Protocol instance to finish Information Request exchange process. 397 @retval EFI_NOT_READY Tell the EFI DHCPv6 Protocol instance to continue Information Request exchange process. 398 @retval EFI_ABORTED Tell the EFI DHCPv6 Protocol instance to abort the Information Request exchange process. 399 400 **/ 401 typedef 402 EFI_STATUS 403 (EFIAPI *EFI_DHCP6_INFO_CALLBACK)( 404 IN EFI_DHCP6_PROTOCOL *This, 405 IN VOID *Context, 406 IN EFI_DHCP6_PACKET *Packet 407 ); 408 409 /** 410 Retrieve the current operating mode data and configuration data for the EFI DHCPv6 Protocol instance. 411 412 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 413 @param[out] Dhcp6ModeData Pointer to the DHCPv6 mode data structure. The caller is responsible for freeing this 414 structure and each reference buffer. 415 @param[out] Dhcp6ConfigData Pointer to the DHCPv6 configuration data structure. The caller is responsible for 416 freeing this structure and each reference buffer. 417 418 @retval EFI_SUCCESS The mode data was returned. 419 @retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has not been configured when Dhcp6ConfigData is not NULL. 420 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: 421 - This is NULL. 422 - Both Dhcp6ConfigData and Dhcp6ModeData are NULL. 423 424 **/ 425 typedef 426 EFI_STATUS 427 (EFIAPI *EFI_DHCP6_GET_MODE_DATA)( 428 IN EFI_DHCP6_PROTOCOL *This, 429 OUT EFI_DHCP6_MODE_DATA *Dhcp6ModeData OPTIONAL, 430 OUT EFI_DHCP6_CONFIG_DATA *Dhcp6ConfigData OPTIONAL 431 ); 432 433 /** 434 Initialize or clean up the configuration data for the EFI DHCPv6 Protocol instance. 435 436 The Configure() function is used to initialize or clean up the configuration data of the EFI 437 DHCPv6 Protocol instance. 438 - When Dhcp6CfgData is not NULL and Configure() is called successfully, the 439 configuration data will be initialized in the EFI DHCPv6 Protocol instance and the state of the 440 configured IA will be transferred into Dhcp6Init. 441 - When Dhcp6CfgData is NULL and Configure() is called successfully, the configuration 442 data will be cleaned up and no IA will be associated with the EFI DHCPv6 Protocol instance. 443 444 To update the configuration data for an EFI DCHPv6 Protocol instance, the original data must be 445 cleaned up before setting the new configuration data. 446 447 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 448 @param[in] Dhcp6CfgData Pointer to the DHCPv6 configuration data structure. 449 450 @retval EFI_SUCCESS The mode data was returned. 451 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE 452 - This is NULL. 453 - OptionCount > 0 and OptionList is NULL. 454 - OptionList is not NULL, and Client Id option, Reconfigure Accept option, 455 Rapid Commit option or any IA option is specified in the OptionList. 456 - IaDescriptor.Type is neither EFI_DHCP6_IA_TYPE_NA nor EFI_DHCP6_IA_TYPE_NA. 457 - IaDescriptor is not unique. 458 - Both IaInfoEvent and SolicitRetransimssion are NULL. 459 - SolicitRetransmission is not NULL, and both SolicitRetransimssion->Mrc and 460 SolicitRetransmission->Mrd are zero. 461 @retval EFI_ACCESS_DENIED The EFI DHCPv6 Protocol instance has been already configured 462 when Dhcp6CfgData is not NULL. 463 The EFI DHCPv6 Protocol instance has already started the 464 DHCPv6 S.A.R.R when Dhcp6CfgData is NULL. 465 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 466 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. 467 468 **/ 469 typedef 470 EFI_STATUS 471 (EFIAPI *EFI_DHCP6_CONFIGURE)( 472 IN EFI_DHCP6_PROTOCOL *This, 473 IN EFI_DHCP6_CONFIG_DATA *Dhcp6CfgData OPTIONAL 474 ); 475 476 /** 477 Start the DHCPv6 S.A.R.R process. 478 479 The Start() function starts the DHCPv6 S.A.R.R process. This function can be called only when 480 the state of the configured IA is in the Dhcp6Init state. If the DHCPv6 S.A.R.R process completes 481 successfully, the state of the configured IA will be transferred through Dhcp6Selecting and 482 Dhcp6Requesting to Dhcp6Bound state. The update of the IPv6 addresses will be notified through 483 EFI_DHCP6_CONFIG_DATA.IaInfoEvent. At the time when each event occurs in this process, the 484 callback function set by EFI_DHCP6_PROTOCOL.Configure() will be called and the user can take 485 this opportunity to control the process. If EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the 486 Start() function call is a blocking operation. It will return after the DHCPv6 S.A.R.R process 487 completes or aborted by users. If the process is aborted by system or network error, the state of 488 the configured IA will be transferred to Dhcp6Init. The Start() function can be called again to 489 restart the process. 490 491 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 492 493 @retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6 494 address has been bound to the configured IA when 495 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. 496 The DHCPv6 S.A.R.R process is started when 497 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. 498 @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured. 499 @retval EFI_INVALID_PARAMETER This is NULL. 500 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated. 501 @retval EFI_ALREADY_STARTED The DHCPv6 S.A.R.R process has already started. 502 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 503 @retval EFI_NO_RESPONSE The DHCPv6 S.A.R.R process failed because of no response. 504 @retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the 505 DHCPv6 S.A.R.R process. 506 @retval EFI_ABORTED The DHCPv6 S.A.R.R process aborted by user. 507 @retval EFI_NO_MEDIA There was a media error. 508 509 **/ 510 typedef 511 EFI_STATUS 512 (EFIAPI *EFI_DHCP6_START)( 513 IN EFI_DHCP6_PROTOCOL *This 514 ); 515 516 /** 517 Request configuration information without the assignment of any IA addresses of the client. 518 519 The InfoRequest() function is used to request configuration information without the assignment 520 of any IPv6 address of the client. Client sends out Information Request packet to obtain 521 the required configuration information, and DHCPv6 server responds with Reply packet containing 522 the information for the client. The received Reply packet will be passed to the user by 523 ReplyCallback function. If user returns EFI_NOT_READY from ReplyCallback, the EFI DHCPv6 524 Protocol instance will continue to receive other Reply packets unless timeout according to 525 the Retransmission parameter. Otherwise, the Information Request exchange process will be 526 finished successfully if user returns EFI_SUCCESS from ReplyCallback. 527 528 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 529 @param[in] SendClientId If TRUE, the EFI DHCPv6 Protocol instance will build Client 530 Identifier option and include it into Information Request 531 packet. If FALSE, Client Identifier option will not be included. 532 Client Identifier option can not be specified through OptionList 533 parameter. 534 @param[in] OptionRequest Pointer to the Option Request option in the Information Request 535 packet. Option Request option can not be specified through 536 OptionList parameter. 537 @param[in] OptionCount Number of options in OptionList. 538 @param[in] OptionList List of other DHCPv6 options. These options will be appended 539 to the Option Request option. The caller is responsible for 540 freeing this buffer. Type is defined in EFI_DHCP6_PROTOCOL.GetModeData(). 541 @param[in] Retransmission Parameter to control Information Request packet retransmission 542 behavior. The buffer can be freed after EFI_DHCP6_PROTOCOL.InfoRequest() 543 returns. 544 @param[in] TimeoutEvent If not NULL, this event is signaled when the information request 545 exchange aborted because of no response. If NULL, the function 546 call is a blocking operation; and it will return after the 547 information-request exchange process finish or aborted by users. 548 @param[in] ReplyCallback The callback function is to intercept various events that occur 549 in the Information Request exchange process. It should not be 550 set to NULL. 551 @param[in] CallbackContext Pointer to the context that will be passed to ReplyCallback. 552 553 @retval EFI_SUCCESS The DHCPv6 S.A.R.R process is completed and at least one IPv6 554 @retval EFI_SUCCESS The DHCPv6 information request exchange process completed 555 when TimeoutEvent is NULL. Information Request packet has been 556 sent to DHCPv6 server when TimeoutEvent is not NULL. 557 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: 558 - This is NULL. 559 - OptionRequest is NULL or OptionRequest->OpCode is invalid. 560 - OptionCount > 0 and OptionList is NULL. 561 - OptionList is not NULL, and Client Identify option or 562 Option Request option is specified in the OptionList. 563 - Retransimssion is NULL. 564 - Both Retransimssion->Mrc and Retransmission->Mrd are zero. 565 - ReplyCallback is NULL. 566 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 567 @retval EFI_NO_RESPONSE The DHCPv6 information request exchange process failed 568 because of no response, or not all requested-options are 569 responded by DHCPv6 servers when Timeout happened. 570 @retval EFI_ABORTED The DHCPv6 information request exchange process aborted by user. 571 572 **/ 573 typedef 574 EFI_STATUS 575 (EFIAPI *EFI_DHCP6_INFO_REQUEST)( 576 IN EFI_DHCP6_PROTOCOL *This, 577 IN BOOLEAN SendClientId, 578 IN EFI_DHCP6_PACKET_OPTION *OptionRequest, 579 IN UINT32 OptionCount, 580 IN EFI_DHCP6_PACKET_OPTION *OptionList[] OPTIONAL, 581 IN EFI_DHCP6_RETRANSMISSION *Retransmission, 582 IN EFI_EVENT TimeoutEvent OPTIONAL, 583 IN EFI_DHCP6_INFO_CALLBACK ReplyCallback, 584 IN VOID *CallbackContext OPTIONAL 585 ); 586 587 /** 588 Manually extend the valid and preferred lifetimes for the IPv6 addresses of the configured 589 IA and update other configuration parameters by sending Renew or Rebind packet. 590 591 The RenewRebind() function is used to manually extend the valid and preferred lifetimes for the 592 IPv6 addresses of the configured IA and update other configuration parameters by sending Renew or 593 Rebind packet. 594 - When RebindRequest is FALSE and the state of the configured IA is Dhcp6Bound, it 595 will send Renew packet to the previously DHCPv6 server and transfer the state of the configured 596 IA to Dhcp6Renewing. If valid Reply packet received, the state transfers to Dhcp6Bound 597 and the valid and preferred timer restarts. If fails, the state transfers to Dhcp6Bound but the 598 timer continues. 599 - When RebindRequest is TRUE and the state of the configured IA is Dhcp6Bound, it will 600 send Rebind packet. If valid Reply packet received, the state transfers to Dhcp6Bound and the 601 valid and preferred timer restarts. If fails, the state transfers to Dhcp6Init and the IA can't 602 be used. 603 604 @param[in] This Pointer to the EFI_DHCP4_PROTOCOL instance. 605 @param[in] RebindRequest If TRUE, it will send Rebind packet and enter the Dhcp6Rebinding state. 606 Otherwise, it will send Renew packet and enter the Dhcp6Renewing state. 607 608 @retval EFI_SUCCESS The DHCPv6 renew/rebind exchange process has completed and at 609 least one IPv6 address of the configured IA has been bound again 610 when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. 611 The EFI DHCPv6 Protocol instance has sent Renew or Rebind packet 612 when EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. 613 @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the state 614 of the configured IA is not in Dhcp6Bound. 615 @retval EFI_ALREADY_STARTED The state of the configured IA has already entered Dhcp6Renewing 616 when RebindRequest is FALSE. 617 The state of the configured IA has already entered Dhcp6Rebinding 618 when RebindRequest is TRUE. 619 @retval EFI_INVALID_PARAMETER This is NULL. 620 @retval EFI_DEVICE_ERROR An unexpected system or system error occurred. 621 @retval EFI_NO_RESPONSE The DHCPv6 renew/rebind exchange process failed because of no response. 622 @retval EFI_NO_MAPPING No IPv6 address has been bound to the configured IA after the DHCPv6 623 renew/rebind exchange process. 624 @retval EFI_ABORTED The DHCPv6 renew/rebind exchange process aborted by user. 625 626 **/ 627 typedef 628 EFI_STATUS 629 (EFIAPI *EFI_DHCP6_RENEW_REBIND)( 630 IN EFI_DHCP6_PROTOCOL *This, 631 IN BOOLEAN RebindRequest 632 ); 633 634 /** 635 Inform that one or more IPv6 addresses assigned by a server are already in use by 636 another node. 637 638 The Decline() function is used to manually decline the assignment of IPv6 addresses, which 639 have been already used by another node. If all IPv6 addresses of the configured IA are declined 640 through this function, the state of the IA will switch through Dhcp6Declining to Dhcp6Init, 641 otherwise, the state of the IA will restore to Dhcp6Bound after the declining process. The 642 Decline() can only be called when the IA is in Dhcp6Bound state. If the 643 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, this function is a blocking operation. It 644 will return after the declining process finishes, or aborted by user. 645 646 @param[in] This Pointer to the EFI_DHCP4_PROTOCOL instance. 647 @param[in] AddressCount Number of declining IPv6 addresses. 648 @param[in] Addresses Pointer to the buffer stored all the declining IPv6 addresses. 649 650 @retval EFI_SUCCESS The DHCPv6 decline exchange process has completed when 651 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. 652 The EFI DHCPv6 Protocol instance has sent Decline packet when 653 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. 654 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE 655 - This is NULL. 656 - AddressCount is zero or Addresses is NULL. 657 @retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured IA 658 for this instance. 659 @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the 660 state of the configured IA is not in Dhcp6Bound. 661 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 662 @retval EFI_ABORTED The DHCPv6 decline exchange process aborted by user. 663 664 **/ 665 typedef 666 EFI_STATUS 667 (EFIAPI *EFI_DHCP6_DECLINE)( 668 IN EFI_DHCP6_PROTOCOL *This, 669 IN UINT32 AddressCount, 670 IN EFI_IPv6_ADDRESS *Addresses 671 ); 672 673 /** 674 Release one or more IPv6 addresses associated with the configured IA for current instance. 675 676 The Release() function is used to manually release the one or more IPv6 address. If AddressCount 677 is zero, it will release all IPv6 addresses of the configured IA. If all IPv6 addresses of the IA 678 are released through this function, the state of the IA will switch through Dhcp6Releasing to 679 Dhcp6Init, otherwise, the state of the IA will restore to Dhcp6Bound after the releasing process. 680 The Release() can only be called when the IA is in Dhcp6Bound state. If the 681 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL, the function is a blocking operation. It will return 682 after the releasing process finishes, or aborted by user. 683 684 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 685 @param[in] AddressCount Number of releasing IPv6 addresses. 686 @param[in] Addresses Pointer to the buffer stored all the releasing IPv6 addresses. 687 Ignored if AddressCount is zero. 688 @retval EFI_SUCCESS The DHCPv6 release exchange process has completed when 689 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. 690 The EFI DHCPv6 Protocol instance has sent Release packet when 691 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. 692 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE 693 - This is NULL. 694 - AddressCount is not zero or Addresses is NULL. 695 @retval EFI_NOT_FOUND Any specified IPv6 address is not correlated with the configured 696 IA for this instance. 697 @retval EFI_ACCESS_DENIED The EFI DHCPv6 Child instance hasn't been configured, or the 698 state of the configured IA is not in Dhcp6Bound. 699 @retval EFI_DEVICE_ERROR An unexpected network or system error occurred. 700 @retval EFI_ABORTED The DHCPv6 release exchange process aborted by user. 701 702 **/ 703 typedef 704 EFI_STATUS 705 (EFIAPI *EFI_DHCP6_RELEASE)( 706 IN EFI_DHCP6_PROTOCOL *This, 707 IN UINT32 AddressCount, 708 IN EFI_IPv6_ADDRESS *Addresses 709 ); 710 711 /** 712 Stop the DHCPv6 S.A.R.R process. 713 714 The Stop() function is used to stop the DHCPv6 S.A.R.R process. If this function is called 715 successfully, all the IPv6 addresses of the configured IA will be released and the state of 716 the configured IA will be transferred to Dhcp6Init. 717 718 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 719 720 @retval EFI_SUCCESS The DHCPv6 S.A.R.R process has been stopped when 721 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is NULL. 722 The EFI DHCPv6 Protocol instance has sent Release packet if 723 need release or has been stopped if needn't, when 724 EFI_DHCP6_CONFIG_DATA.IaInfoEvent is not NULL. 725 @retval EFI_INVALID_PARAMETER This is NULL. 726 727 **/ 728 typedef 729 EFI_STATUS 730 (EFIAPI *EFI_DHCP6_STOP)( 731 IN EFI_DHCP6_PROTOCOL *This 732 ); 733 734 /** 735 Parse the option data in the DHCPv6 packet. 736 737 The Parse() function is used to retrieve the option list in the DHCPv6 packet. 738 739 @param[in] This Pointer to the EFI_DHCP6_PROTOCOL instance. 740 741 @param[in] Packet Pointer to packet to be parsed. 742 @param[in] OptionCount On input, the number of entries in the PacketOptionList. 743 On output, the number of DHCPv6 options in the Packet. 744 @param[in] PacketOptionList List of pointers to the DHCPv6 options in the Packet. 745 The OpCode and OpLen in EFI_DHCP6_PACKET_OPTION are 746 both stored in network byte order. 747 @retval EFI_SUCCESS The packet was successfully parsed. 748 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE 749 - This is NULL. 750 - Packet is NULL. 751 - Packet is not a well-formed DHCPv6 packet. 752 - OptionCount is NULL. 753 - *OptionCount is not zero and PacketOptionList is NULL. 754 @retval EFI_BUFFER_TOO_SMALL *OptionCount is smaller than the number of options that were 755 found in the Packet. 756 757 **/ 758 typedef 759 EFI_STATUS 760 (EFIAPI *EFI_DHCP6_PARSE)( 761 IN EFI_DHCP6_PROTOCOL *This, 762 IN EFI_DHCP6_PACKET *Packet, 763 IN OUT UINT32 *OptionCount, 764 OUT EFI_DHCP6_PACKET_OPTION *PacketOptionList[] OPTIONAL 765 ); 766 767 /// 768 /// The EFI DHCPv6 Protocol is used to get IPv6 addresses and other configuration parameters 769 /// from DHCPv6 servers. 770 /// 771 struct _EFI_DHCP6_PROTOCOL { 772 EFI_DHCP6_GET_MODE_DATA GetModeData; 773 EFI_DHCP6_CONFIGURE Configure; 774 EFI_DHCP6_START Start; 775 EFI_DHCP6_INFO_REQUEST InfoRequest; 776 EFI_DHCP6_RENEW_REBIND RenewRebind; 777 EFI_DHCP6_DECLINE Decline; 778 EFI_DHCP6_RELEASE Release; 779 EFI_DHCP6_STOP Stop; 780 EFI_DHCP6_PARSE Parse; 781 }; 782 783 extern EFI_GUID gEfiDhcp6ProtocolGuid; 784 extern EFI_GUID gEfiDhcp6ServiceBindingProtocolGuid; 785 786 #endif 787
