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