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