MdePkg/Include/Protocol/Dhcp6.h

   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