/** @file\r
EFI_DHCP4_PROTOCOL as defined in UEFI 2.0.\r
EFI_DHCP4_SERVICE_BINDING_PROTOCOL as defined in UEFI 2.0.\r
- These protocols are used to collect configuration information for the EFI IPv4 Protocol \r
+ These protocols are used to collect configuration information for the EFI IPv4 Protocol\r
drivers and to provide DHCPv4 server and PXE boot server discovery services.\r
\r
- Copyright (c) 2006, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
+ Copyright (c) 2006 - 2008, Intel Corporation\r
+ All rights reserved. This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
-\r
- Module Name: DHCP4.h\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
{ \\r
0x9d9a39d8, 0xbd42, 0x4a73, {0xa4, 0xd5, 0x8e, 0xe9, 0x4b, 0xe1, 0x13, 0x80 } \\r
}\r
- \r
+\r
typedef struct _EFI_DHCP4_PROTOCOL EFI_DHCP4_PROTOCOL;\r
\r
\r
#pragma pack(1)\r
typedef struct {\r
+ ///\r
+ /// DHCP option code.\r
+ ///\r
UINT8 OpCode;\r
+ ///\r
+ /// Length of the DHCP option data. Not present if OpCode is 0 or 255.\r
+ ///\r
UINT8 Length;\r
+ ///\r
+ /// Start of the DHCP option data. Not present if OpCode is 0 or 255 or if Length is zero.\r
+ ///\r
UINT8 Data[1];\r
} EFI_DHCP4_PACKET_OPTION;\r
#pragma pack()\r
\r
\r
#pragma pack(1)\r
+///\r
+/// EFI_DHCP4_PACKET defines the format of DHCPv4 packets. See RFC 2131 for more information.\r
+///\r
typedef struct {\r
- UINT8 OpCode;\r
- UINT8 HwType;\r
- UINT8 HwAddrLen;\r
- UINT8 Hops;\r
- UINT32 Xid;\r
- UINT16 Seconds;\r
- UINT16 Reserved;\r
- EFI_IPv4_ADDRESS ClientAddr; //Client IP address from client\r
- EFI_IPv4_ADDRESS YourAddr; //Client IP address from server\r
- EFI_IPv4_ADDRESS ServerAddr; //IP address of next server in bootstrap \r
- EFI_IPv4_ADDRESS GatewayAddr; //Relay agent IP address\r
- UINT8 ClientHwAddr[16]; //Client hardware address\r
- CHAR8 ServerName[64]; \r
- CHAR8 BootFileName[128];\r
+ UINT8 OpCode;\r
+ UINT8 HwType;\r
+ UINT8 HwAddrLen;\r
+ UINT8 Hops;\r
+ UINT32 Xid;\r
+ UINT16 Seconds;\r
+ UINT16 Reserved;\r
+ EFI_IPv4_ADDRESS ClientAddr; ///< Client IP address from client\r
+ EFI_IPv4_ADDRESS YourAddr; ///< Client IP address from server\r
+ EFI_IPv4_ADDRESS ServerAddr; ///< IP address of next server in bootstrap\r
+ EFI_IPv4_ADDRESS GatewayAddr; ///< Relay agent IP address\r
+ UINT8 ClientHwAddr[16]; ///< Client hardware address\r
+ CHAR8 ServerName[64];\r
+ CHAR8 BootFileName[128];\r
}EFI_DHCP4_HEADER;\r
#pragma pack()\r
\r
\r
#pragma pack(1)\r
typedef struct {\r
+ ///\r
+ /// Size of the EFI_DHCP4_PACKET buffer.\r
+ ///\r
UINT32 Size;\r
+ ///\r
+ /// Length of the EFI_DHCP4_PACKET from the first byte of the Header field \r
+ /// to the last byte of the Option[] field.\r
+ ///\r
UINT32 Length;\r
\r
struct {\r
+ ///\r
+ /// DHCP packet header.\r
+ ///\r
EFI_DHCP4_HEADER Header;\r
+ ///\r
+ /// DHCP magik cookie in network byte order.\r
+ ///\r
UINT32 Magik;\r
+ ///\r
+ /// Start of the DHCP packed option data.\r
+ ///\r
UINT8 Option[1];\r
} Dhcp4;\r
} EFI_DHCP4_PACKET;\r
\r
\r
typedef enum {\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver is stopped\r
+ ///\r
Dhcp4Stopped = 0x0,\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver is inactive\r
+ ///\r
Dhcp4Init = 0x1,\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver is collecting DHCP offer packets from DHCP servers.\r
+ ///\r
Dhcp4Selecting = 0x2,\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver has sent the request to the DHCP server and is waiting for a response.\r
+ ///\r
Dhcp4Requesting = 0x3,\r
+ ///\r
+ /// The DHCP configuration has completed.\r
+ ///\r
Dhcp4Bound = 0x4,\r
+ ///\r
+ /// The DHCP configuration is being renewed and another request has\r
+ /// been sent out, but it has not received a response from the server yet.\r
+ ///\r
Dhcp4Renewing = 0x5,\r
+ ///\r
+ /// The DHCP configuration has timed out and the EFI DHCPv4\r
+ /// Protocol driver is trying to extend the lease time.\r
+ ///\r
Dhcp4Rebinding = 0x6,\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver is initialized with a previously\r
+ /// allocated or known IP address.\r
+ ///\r
Dhcp4InitReboot = 0x7,\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver is seeking to reuse the previously\r
+ /// allocated IP address by sending a request to the DHCP server.\r
+ ///\r
Dhcp4Rebooting = 0x8\r
} EFI_DHCP4_STATE;\r
\r
\r
typedef enum{\r
+ ///\r
+ /// The packet to start the configuration sequence is about to be sent.\r
+ ///\r
Dhcp4SendDiscover = 0x01,\r
+ ///\r
+ /// A reply packet was just received.\r
+ ///\r
Dhcp4RcvdOffer = 0x02,\r
+ ///\r
+ /// It is time for Dhcp4Callback to select an offer.\r
+ ///\r
Dhcp4SelectOffer = 0x03,\r
+ ///\r
+ /// A request packet is about to be sent.\r
+ ///\r
Dhcp4SendRequest = 0x04,\r
+ ///\r
+ /// A DHCPACK packet was received and will be passed to Dhcp4Callback.\r
+ ///\r
Dhcp4RcvdAck = 0x05,\r
+ ///\r
+ /// A DHCPNAK packet was received and will be passed to Dhcp4Callback.\r
+ ///\r
Dhcp4RcvdNak = 0x06,\r
+ ///\r
+ /// A decline packet is about to be sent.\r
+ ///\r
Dhcp4SendDecline = 0x07,\r
+ ///\r
+ /// The DHCP configuration process has completed. No packet is associated with this event.\r
+ ///\r
Dhcp4BoundCompleted = 0x08,\r
+ ///\r
+ /// It is time to enter the Dhcp4Renewing state and to contact the server \r
+ /// that originally issued the network address. No packet is associated with this event.\r
+ ///\r
Dhcp4EnterRenewing = 0x09,\r
+ ///\r
+ /// It is time to enter the Dhcp4Rebinding state and to contact any server. \r
+ /// No packet is associated with this event.\r
+ ///\r
Dhcp4EnterRebinding = 0x0a,\r
+ ///\r
+ /// The configured IP address was lost either because the lease has expired, \r
+ /// the user released the configuration, or a DHCPNAK packet was received in \r
+ /// the Dhcp4Renewing or Dhcp4Rebinding state. No packet is associated with this event.\r
+ ///\r
Dhcp4AddressLost = 0x0b,\r
+ ///\r
+ /// The DHCP process failed because a DHCPNAK packet was received or the user \r
+ /// aborted the DHCP process at a time when the configuration was not available yet. \r
+ /// No packet is associated with this event.\r
+ ///\r
Dhcp4Fail = 0x0c\r
} EFI_DHCP4_EVENT;\r
\r
-/** \r
- Callback routine \r
- \r
+/**\r
+ Callback routine.\r
+ \r
+ EFI_DHCP4_CALLBACK is provided by the consumer of the EFI DHCPv4 Protocol driver\r
+ to intercept events that occurred in the configuration process. This structure\r
+ provides advanced control of each state transition of the DHCP process. The\r
+ returned status code determines the behavior of the EFI DHCPv4 Protocol driver.\r
+ There are three possible returned values, which are described in the following\r
+ table.\r
+\r
@param This Pointer to the EFI DHCPv4 Protocol instance that is used to\r
- configure this callback function. \r
+ configure this callback function.\r
@param Context Pointer to the context that is initialized by\r
- EFI_DHCP4_PROTOCOL.Configure(). \r
+ EFI_DHCP4_PROTOCOL.Configure().\r
@param CurrentState The current operational state of the EFI DHCPv4 Protocol\r
- driver. \r
+ driver.\r
@param Dhcp4Event The event that occurs in the current state, which usually means a\r
- state transition. \r
- @param Packet The DHCP packet that is going to be sent or already received. \r
+ state transition.\r
+ @param Packet The DHCP packet that is going to be sent or already received.\r
@param NewPacket The packet that is used to replace the above Packet.\r
- \r
+\r
@retval EFI_SUCCESS Tells the EFI DHCPv4 Protocol driver to continue the DHCP process.\r
- @retval EFI_NOT_READY Only used in the Dhcp4Selecting state. The EFI DHCPv4 Protocol \r
- driver will continue to wait for more DHCPOFFER packets until the retry\r
- timeout expires. \r
+ When it is in the Dhcp4Selecting state, it tells the EFI DHCPv4 Protocol\r
+ driver to stop collecting additional packets. The driver will exit\r
+ the Dhcp4Selecting state and enter the Dhcp4Requesting state.\r
+ @retval EFI_NOT_READY Only used in the Dhcp4Selecting state. The EFI DHCPv4 Protocol\r
+ driver will continue to wait for more packets until the retry\r
+ timeout expires.\r
@retval EFI_ABORTED Tells the EFI DHCPv4 Protocol driver to abort the current process and\r
- return to the Dhcp4Init or Dhcp4InitReboot state. \r
- \r
+ return to the Dhcp4Init or Dhcp4InitReboot state.\r
+\r
**/\r
-typedef \r
-EFI_STATUS \r
-(EFIAPI *EFI_DHCP4_CALLBACK) (\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_DHCP4_CALLBACK)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN VOID *Context,\r
IN EFI_DHCP4_STATE CurrentState,\r
IN EFI_DHCP4_EVENT Dhcp4Event,\r
- IN EFI_DHCP4_PACKET *Packet OPTIONAL, \r
+ IN EFI_DHCP4_PACKET *Packet OPTIONAL,\r
OUT EFI_DHCP4_PACKET **NewPacket OPTIONAL\r
);\r
\r
-\r
typedef struct {\r
- UINT32 DiscoverTryCount; \r
+ ///\r
+ /// Number of times to try sending a packet during the Dhcp4SendDiscover\r
+ /// event and waiting for a response during the Dhcp4RcvdOffer event.\r
+ /// Set to zero to use the default try counts and timeout values.\r
+ ///\r
+ UINT32 DiscoverTryCount;\r
+ ///\r
+ /// Maximum amount of time (in seconds) to wait for returned packets in each \r
+ /// of the retries. Timeout values of zero will default to a timeout value \r
+ /// of one second. Set to NULL to use default timeout values.\r
+ ///\r
UINT32 *DiscoverTimeout;\r
+ ///\r
+ /// Number of times to try sending a packet during the Dhcp4SendRequest event\r
+ /// and waiting for a response during the Dhcp4RcvdAck event before accepting\r
+ /// failure. Set to zero to use the default try counts and timeout values.\r
+ ///\r
UINT32 RequestTryCount;\r
+ ///\r
+ /// Maximum amount of time (in seconds) to wait for return packets in each of the retries. \r
+ /// Timeout values of zero will default to a timeout value of one second. \r
+ /// Set to NULL to use default timeout values.\r
+ ///\r
UINT32 *RequestTimeout;\r
+ ///\r
+ /// For a DHCPDISCOVER, setting this parameter to the previously allocated IP\r
+ /// address will cause the EFI DHCPv4 Protocol driver to enter the Dhcp4InitReboot state. \r
+ /// And set this field to 0.0.0.0 to enter the Dhcp4Init state.\r
+ /// For a DHCPINFORM this parameter should be set to the client network address\r
+ /// which was assigned to the client during a DHCPDISCOVER.\r
+ ///\r
EFI_IPv4_ADDRESS ClientAddress;\r
+ ///\r
+ /// The callback function to intercept various events that occurred in \r
+ /// the DHCP configuration process. Set to NULL to ignore all those events.\r
+ ///\r
EFI_DHCP4_CALLBACK Dhcp4Callback;\r
- void *CallbackContext;\r
+ ///\r
+ /// Pointer to the context that will be passed to Dhcp4Callback when it is called.\r
+ ///\r
+ VOID *CallbackContext;\r
+ ///\r
+ /// Number of DHCP options in the OptionList.\r
+ ///\r
UINT32 OptionCount;\r
+ ///\r
+ /// List of DHCP options to be included in every packet that is sent during the\r
+ /// Dhcp4SendDiscover event. Pad options are appended automatically by DHCP driver\r
+ /// in outgoing DHCP packets. If OptionList itself contains pad option, they are\r
+ /// ignored by the driver. OptionList can be freed after EFI_DHCP4_PROTOCOL.Configure()\r
+ /// returns. Ignored if OptionCount is zero.\r
+ ///\r
EFI_DHCP4_PACKET_OPTION **OptionList;\r
} EFI_DHCP4_CONFIG_DATA;\r
\r
\r
typedef struct {\r
+ ///\r
+ /// The EFI DHCPv4 Protocol driver operating state. \r
+ ///\r
EFI_DHCP4_STATE State;\r
+ ///\r
+ /// The configuration data of the current EFI DHCPv4 Protocol driver instance.\r
+ ///\r
EFI_DHCP4_CONFIG_DATA ConfigData;\r
+ ///\r
+ /// The client IP address that was acquired from the DHCP server. If it is zero,\r
+ /// the DHCP acquisition has not completed yet and the following fields in this structure are undefined.\r
+ ///\r
EFI_IPv4_ADDRESS ClientAddress;\r
+ ///\r
+ /// The local hardware address.\r
+ ///\r
EFI_MAC_ADDRESS ClientMacAddress;\r
+ ///\r
+ /// The server IP address that is providing the DHCP service to this client.\r
+ ///\r
EFI_IPv4_ADDRESS ServerAddress;\r
+ ///\r
+ /// The router IP address that was acquired from the DHCP server. \r
+ /// May be zero if the server does not offer this address.\r
+ ///\r
EFI_IPv4_ADDRESS RouterAddress;\r
+ ///\r
+ /// The subnet mask of the connected network that was acquired from the DHCP server.\r
+ ///\r
EFI_IPv4_ADDRESS SubnetMask;\r
+ ///\r
+ /// The lease time (in 1-second units) of the configured IP address. \r
+ /// The value 0xFFFFFFFF means that the lease time is infinite. \r
+ /// A default lease of 7 days is used if the DHCP server does not provide a value.\r
+ ///\r
UINT32 LeaseTime;\r
+ ///\r
+ /// The cached latest DHCPACK or DHCPNAK or BOOTP REPLY packet. May be NULL if no packet is cached.\r
+ ///\r
EFI_DHCP4_PACKET *ReplyPacket;\r
} EFI_DHCP4_MODE_DATA;\r
\r
\r
typedef struct {\r
+ ///\r
+ /// Alternate listening address. It can be a unicast, multicast, or broadcast address.\r
+ ///\r
EFI_IPv4_ADDRESS ListenAddress;\r
+ ///\r
+ /// The subnet mask of above listening unicast/broadcast IP address. \r
+ /// Ignored if ListenAddress is a multicast address.\r
+ ///\r
EFI_IPv4_ADDRESS SubnetMask;\r
+ ///\r
+ /// Alternate station source (or listening) port number. \r
+ /// If zero, then the default station port number (68) will be used.\r
+ ///\r
UINT16 ListenPort;\r
} EFI_DHCP4_LISTEN_POINT;\r
\r
\r
typedef struct {\r
- OUT EFI_STATUS Status;\r
- IN EFI_EVENT CompletionEvent;\r
- IN EFI_IPv4_ADDRESS RemoteAddress;\r
- IN UINT16 RemotePort;\r
- IN EFI_IPv4_ADDRESS GatewayAddress;\r
- IN UINT32 ListenPointCount;\r
- IN EFI_DHCP4_LISTEN_POINT *ListenPoints;\r
- IN UINT32 TimeoutValue;\r
- IN EFI_DHCP4_PACKET *Packet;\r
- OUT UINT32 ResponseCount;\r
- OUT EFI_DHCP4_PACKET *ResponseList;\r
+ ///\r
+ /// The completion status of transmitting and receiving.\r
+ ///\r
+ EFI_STATUS Status;\r
+ ///\r
+ /// If not NULL, the event that will be signaled when the collection process \r
+ /// completes. If NULL, this function will busy-wait until the collection process competes.\r
+ ///\r
+ EFI_EVENT CompletionEvent;\r
+ ///\r
+ /// Pointer to the server IP address. This address may be a unicast, multicast, or broadcast address.\r
+ ///\r
+ EFI_IPv4_ADDRESS RemoteAddress;\r
+ ///\r
+ /// Server listening port number. If zero, the default server listening port number (67) will be used.\r
+ ///\r
+ UINT16 RemotePort;\r
+ ///\r
+ /// Pointer to the gateway address to override the existing setting.\r
+ ///\r
+ EFI_IPv4_ADDRESS GatewayAddress;\r
+ ///\r
+ /// The number of entries in ListenPoints. If zero, the default station address and port number 68 are used.\r
+ ///\r
+ UINT32 ListenPointCount;\r
+ ///\r
+ /// An array of station address and port number pairs that are used as receiving filters. \r
+ /// The first entry is also used as the source address and source port of the outgoing packet.\r
+ ///\r
+ EFI_DHCP4_LISTEN_POINT *ListenPoints;\r
+ ///\r
+ /// Number of seconds to collect responses. Zero is invalid.\r
+ ///\r
+ UINT32 TimeoutValue;\r
+ ///\r
+ /// Pointer to the packet to be transmitted.\r
+ ///\r
+ EFI_DHCP4_PACKET *Packet;\r
+ ///\r
+ /// Number of received packets.\r
+ ///\r
+ UINT32 ResponseCount;\r
+ ///\r
+ /// Pointer to the allocated list of received packets.\r
+ ///\r
+ EFI_DHCP4_PACKET *ResponseList;\r
} EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN;\r
\r
\r
/**\r
Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver.\r
+ \r
+ The GetModeData() function returns the current operating mode and cached data\r
+ packet for the EFI DHCPv4 Protocol driver.\r
\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param Dhcp4ModeData Pointer to storage for the EFI_DHCP4_MODE_DATA structure.\r
@retval EFI_INVALID_PARAMETER This is NULL.\r
\r
**/\r
-typedef \r
-EFI_STATUS \r
+typedef\r
+EFI_STATUS\r
(EFIAPI *EFI_DHCP4_GET_MODE_DATA)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
OUT EFI_DHCP4_MODE_DATA *Dhcp4ModeData\r
- )\r
-;\r
+ );\r
\r
/**\r
Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver.\r
\r
+ The Configure() function is used to initialize, change, or reset the operational\r
+ settings of the EFI DHCPv4 Protocol driver for the communication device on which\r
+ the EFI DHCPv4 Service Binding Protocol is installed. This function can be\r
+ successfully called only if both of the following are true:\r
+ * This instance of the EFI DHCPv4 Protocol driver is in the Dhcp4Stopped, Dhcp4Init,\r
+ Dhcp4InitReboot, or Dhcp4Bound states.\r
+ * No other EFI DHCPv4 Protocol driver instance that is controlled by this EFI\r
+ DHCPv4 Service Binding Protocol driver instance has configured this EFI DHCPv4\r
+ Protocol driver.\r
+ When this driver is in the Dhcp4Stopped state, it can transfer into one of the\r
+ following two possible initial states:\r
+ * Dhcp4Init\r
+ * Dhcp4InitReboot\r
+ The driver can transfer into these states by calling Configure() with a non-NULL\r
+ Dhcp4CfgData. The driver will transfer into the appropriate state based on the\r
+ supplied client network address in the ClientAddress parameter and DHCP options\r
+ in the OptionList parameter as described in RFC 2131.\r
+ When Configure() is called successfully while Dhcp4CfgData is set to NULL, the\r
+ default configuring data will be reset in the EFI DHCPv4 Protocol driver and\r
+ the state of the EFI DHCPv4 Protocol driver will not be changed. If one instance\r
+ wants to make it possible for another instance to configure the EFI DHCPv4 Protocol\r
+ driver, it must call this function with Dhcp4CfgData set to NULL.\r
+\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param Dhcp4CfgData Pointer to the EFI_DHCP4_CONFIG_DATA.\r
\r
@retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Init or\r
Dhcp4InitReboot state, if the original state of this driver\r
- was Dhcp4Stopped and the value of Dhcp4CfgData was\r
- not NULL. Otherwise, the state was left unchanged.\r
+ was Dhcp4Stopped, Dhcp4Init,Dhcp4InitReboot, or Dhcp4Bound\r
+ and the value of Dhcp4CfgData was not NULL.\r
+ Otherwise, the state was left unchanged.\r
@retval EFI_ACCESS_DENIED This instance of the EFI DHCPv4 Protocol driver was not in the\r
Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;\r
Or onother instance of this EFI DHCPv4 Protocol driver is already\r
in a valid configured state.\r
- @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+ @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:\r
+ This is NULL.\r
+ DiscoverTryCount > 0 and DiscoverTimeout is NULL\r
+ RequestTryCount > 0 and RequestTimeout is NULL.\r
+ OptionCount >0 and OptionList is NULL.\r
+ ClientAddress is not a valid unicast address.\r
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_CONFIGURE) (\r
+(EFIAPI *EFI_DHCP4_CONFIGURE)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN EFI_DHCP4_CONFIG_DATA *Dhcp4CfgData OPTIONAL\r
- )\r
-;\r
+ );\r
\r
\r
/**\r
Starts the DHCP configuration process.\r
\r
+ The Start() function starts the DHCP configuration process. This function can\r
+ be called only when the EFI DHCPv4 Protocol driver is in the Dhcp4Init or\r
+ Dhcp4InitReboot state.\r
+ If the DHCP process completes successfully, the state of the EFI DHCPv4 Protocol\r
+ driver will be transferred through Dhcp4Selecting and Dhcp4Requesting to the\r
+ Dhcp4Bound state. The CompletionEvent will then be signaled if it is not NULL.\r
+ If the process aborts, either by the user or by some unexpected network error,\r
+ the state is restored to the Dhcp4Init state. The Start() function can be called\r
+ again to restart the process.\r
+ Refer to RFC 2131 for precise state transitions during this process. At the\r
+ time when each event occurs in this process, the callback function that was set\r
+ by EFI_DHCP4_PROTOCOL.Configure() will be called and the user can take this\r
+ opportunity to control the process.\r
+ \r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param CompletionEvent If not NULL, indicates the event that will be signaled when the\r
EFI DHCPv4 Protocol driver is transferred into the\r
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_START) (\r
+(EFIAPI *EFI_DHCP4_START)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN EFI_EVENT CompletionEvent OPTIONAL\r
- )\r
-;\r
+ );\r
\r
/**\r
Extends the lease time by sending a request packet.\r
+ \r
+ The RenewRebind() function is used to manually extend the lease time when the\r
+ EFI DHCPv4 Protocol driver is in the Dhcp4Bound state and the lease time has\r
+ not expired yet. This function will send a request packet to the previously\r
+ found server (or to any server when RebindRequest is TRUE) and transfer the\r
+ state into the Dhcp4Renewing state (or Dhcp4Rebinding when RebindingRequest is\r
+ TRUE). When a response is received, the state is returned to Dhcp4Bound.\r
+ If no response is received before the try count is exceeded (the RequestTryCount\r
+ field that is specified in EFI_DHCP4_CONFIG_DATA) but before the lease time that\r
+ was issued by the previous server expires, the driver will return to the Dhcp4Bound\r
+ state and the previous configuration is restored. The outgoing and incoming packets\r
+ can be captured by the EFI_DHCP4_CALLBACK function.\r
\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param RebindRequest If TRUE, this function broadcasts the request packets and enters\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_RENEW_REBIND) (\r
+(EFIAPI *EFI_DHCP4_RENEW_REBIND)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN BOOLEAN RebindRequest,\r
IN EFI_EVENT CompletionEvent OPTIONAL\r
- )\r
-; \r
+ );\r
\r
/**\r
Releases the current address configuration.\r
\r
+ The Release() function releases the current configured IP address by doing either\r
+ of the following:\r
+ * Sending a DHCPRELEASE packet when the EFI DHCPv4 Protocol driver is in the\r
+ Dhcp4Bound state\r
+ * Setting the previously assigned IP address that was provided with the\r
+ EFI_DHCP4_PROTOCOL.Configure() function to 0.0.0.0 when the driver is in\r
+ Dhcp4InitReboot state\r
+ After a successful call to this function, the EFI DHCPv4 Protocol driver returns\r
+ to the Dhcp4Init state and any subsequent incoming packets will be discarded silently.\r
+\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
\r
@retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase.\r
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_RELEASE) (\r
+(EFIAPI *EFI_DHCP4_RELEASE)(\r
IN EFI_DHCP4_PROTOCOL *This\r
- )\r
-; \r
+ );\r
\r
/**\r
Stops the current address configuration.\r
+ \r
+ The Stop() function is used to stop the DHCP configuration process. After this\r
+ function is called successfully, the EFI DHCPv4 Protocol driver is transferred\r
+ into the Dhcp4Stopped state. EFI_DHCP4_PROTOCOL.Configure() needs to be called\r
+ before DHCP configuration process can be started again. This function can be\r
+ called when the EFI DHCPv4 Protocol driver is in any state.\r
\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
- \r
+\r
@retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase.\r
@retval EFI_INVALID_PARAMETER This is NULL.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_STOP) (\r
+(EFIAPI *EFI_DHCP4_STOP)(\r
IN EFI_DHCP4_PROTOCOL *This\r
- )\r
-; \r
+ );\r
\r
/**\r
Builds a DHCP packet, given the options to be appended or deleted or replaced.\r
\r
+ The Build() function is used to assemble a new packet from the original packet\r
+ by replacing or deleting existing options or appending new options. This function\r
+ does not change any state of the EFI DHCPv4 Protocol driver and can be used at\r
+ any time.\r
+\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param SeedPacket Initial packet to be used as a base for building new packet.\r
@param DeleteCount Number of opcodes in the DeleteList.\r
\r
@retval EFI_SUCCESS The new packet was built.\r
@retval EFI_OUT_OF_RESOURCES Storage for the new packet could not be allocated.\r
- @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL.\r
+ SeedPacket is NULL.\r
+ SeedPacket is not a well-formed DHCP packet.\r
+ AppendCount is not zero and AppendList is NULL.\r
+ DeleteCount is not zero and DeleteList is NULL.\r
+ NewPacket is NULL\r
+ Both DeleteCount and AppendCount are zero and\r
+ NewPacket is not NULL.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_BUILD) (\r
+(EFIAPI *EFI_DHCP4_BUILD)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN EFI_DHCP4_PACKET *SeedPacket,\r
IN UINT32 DeleteCount,\r
IN EFI_DHCP4_PACKET_OPTION *AppendList[] OPTIONAL,\r
OUT EFI_DHCP4_PACKET **NewPacket\r
);\r
-; \r
+\r
\r
/**\r
Transmits a DHCP formatted packet and optionally waits for responses.\r
+ \r
+ The TransmitReceive() function is used to transmit a DHCP packet and optionally\r
+ wait for the response from servers. This function does not change the state of\r
+ the EFI DHCPv4 Protocol driver and thus can be used at any time.\r
\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param Token Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.\r
\r
@retval EFI_SUCCESS The packet was successfully queued for transmission.\r
- @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL.\r
+ Token.RemoteAddress is zero.\r
+ Token.Packet is NULL.\r
+ Token.Packet is not a well-formed DHCP packet.\r
+ The transaction ID in Token.Packet is in use by another DHCP process.\r
@retval EFI_NOT_READY The previous call to this function has not finished yet. Try to call\r
this function after collection process completes.\r
@retval EFI_NO_MAPPING The default station address is not available yet.\r
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
+ @retval EFI_UNSUPPORTED The implementation doesn't support this function\r
@retval Others Some other unexpected error occurred.\r
\r
**/\r
-typedef \r
+typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_TRANSMIT_RECEIVE) (\r
+(EFIAPI *EFI_DHCP4_TRANSMIT_RECEIVE)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN *Token\r
- )\r
-;\r
+ );\r
\r
\r
/**\r
Parses the packed DHCP option data.\r
+ \r
+ The Parse() function is used to retrieve the option list from a DHCP packet.\r
+ If *OptionCount isn't zero, and there is enough space for all the DHCP options\r
+ in the Packet, each element of PacketOptionList is set to point to somewhere in\r
+ the Packet->Dhcp4.Option where a new DHCP option begins. If RFC3396 is supported,\r
+ the caller should reassemble the parsed DHCP options to get the final result.\r
+ If *OptionCount is zero or there isn't enough space for all of them, the number\r
+ of DHCP options in the Packet is returned in OptionCount.\r
\r
@param This Pointer to the EFI_DHCP4_PROTOCOL instance.\r
@param Packet Pointer to packet to be parsed.\r
options are not included.\r
\r
@retval EFI_SUCCESS The packet was successfully parsed.\r
- @retval EFI_INVALID_PARAMETER Some parameter is NULL.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ This is NULL.\r
+ Packet is NULL.\r
+ Packet is not a well-formed DHCP packet.\r
+ OptionCount is NULL.\r
@retval EFI_BUFFER_TOO_SMALL One or more of the following conditions is TRUE:\r
1) *OptionCount is smaller than the number of options that\r
were found in the Packet.\r
2) PacketOptionList is NULL.\r
+ @retval EFI_OUT_OF_RESOURCE The packet is failed to parse because of resource shortage.\r
\r
**/\r
typedef\r
EFI_STATUS\r
-(EFIAPI *EFI_DHCP4_PARSE) (\r
+(EFIAPI *EFI_DHCP4_PARSE)(\r
IN EFI_DHCP4_PROTOCOL *This,\r
IN EFI_DHCP4_PACKET *Packet,\r
IN OUT UINT32 *OptionCount,\r
OUT EFI_DHCP4_PACKET_OPTION *PacketOptionList[] OPTIONAL\r
- )\r
-;\r
-\r
+ );\r
\r
+///\r
+/// This protocol is used to collect configuration information for the EFI IPv4 Protocol drivers\r
+/// and to provide DHCPv4 server and PXE boot server discovery services.\r
+///\r
struct _EFI_DHCP4_PROTOCOL {\r
EFI_DHCP4_GET_MODE_DATA GetModeData;\r
EFI_DHCP4_CONFIGURE Configure;\r
projects / mirror_edk2.git / blobdiff