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