From faac3f0cfe132548f9aabdd37dc0947cf9025d60 Mon Sep 17 00:00:00 2001 From: jgong5 Date: Fri, 14 Nov 2008 09:15:28 +0000 Subject: updated interface comments per UEFI Spec. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6547 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/Dhcp4.h | 96 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 95 insertions(+), 1 deletion(-) (limited to 'MdePkg/Include') diff --git a/MdePkg/Include/Protocol/Dhcp4.h b/MdePkg/Include/Protocol/Dhcp4.h index cefa8de73a..b02918d7c4 100644 --- a/MdePkg/Include/Protocol/Dhcp4.h +++ b/MdePkg/Include/Protocol/Dhcp4.h @@ -103,7 +103,14 @@ typedef enum{ } EFI_DHCP4_EVENT; /** - Callback routine + Callback routine. + + EFI_DHCP4_CALLBACK is provided by the consumer of the EFI DHCPv4 Protocol driver + to intercept events that occurred in the configuration process. This structure + provides advanced control of each state transition of the DHCP process. The + returned status code determines the behavior of the EFI DHCPv4 Protocol driver. + There are three possible returned values, which are described in the following + table. @param This Pointer to the EFI DHCPv4 Protocol instance that is used to configure this callback function. @@ -186,6 +193,9 @@ typedef struct { /** Returns the current operating mode and cached data packet for the EFI DHCPv4 Protocol driver. + + The GetModeData() function returns the current operating mode and cached data + packet for the EFI DHCPv4 Protocol driver. @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param Dhcp4ModeData Pointer to storage for the EFI_DHCP4_MODE_DATA structure. @@ -204,6 +214,29 @@ EFI_STATUS /** Initializes, changes, or resets the operational settings for the EFI DHCPv4 Protocol driver. + The Configure() function is used to initialize, change, or reset the operational + settings of the EFI DHCPv4 Protocol driver for the communication device on which + the EFI DHCPv4 Service Binding Protocol is installed. This function can be + successfully called only if both of the following are true: + * This instance of the EFI DHCPv4 Protocol driver is in the Dhcp4Stopped, Dhcp4Init, + Dhcp4InitReboot, or Dhcp4Bound states. + * No other EFI DHCPv4 Protocol driver instance that is controlled by this EFI + DHCPv4 Service Binding Protocol driver instance has configured this EFI DHCPv4 + Protocol driver. + When this driver is in the Dhcp4Stopped state, it can transfer into one of the + following two possible initial states: + * Dhcp4Init + * Dhcp4InitReboot + The driver can transfer into these states by calling Configure() with a non-NULL + Dhcp4CfgData. The driver will transfer into the appropriate state based on the + supplied client network address in the ClientAddress parameter and DHCP options + in the OptionList parameter as described in RFC 2131. + When Configure() is called successfully while Dhcp4CfgData is set to NULL, the + default configuring data will be reset in the EFI DHCPv4 Protocol driver and + the state of the EFI DHCPv4 Protocol driver will not be changed. If one instance + wants to make it possible for another instance to configure the EFI DHCPv4 Protocol + driver, it must call this function with Dhcp4CfgData set to NULL. + @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param Dhcp4CfgData Pointer to the EFI_DHCP4_CONFIG_DATA. @@ -231,6 +264,20 @@ EFI_STATUS /** Starts the DHCP configuration process. + The Start() function starts the DHCP configuration process. This function can + be called only when the EFI DHCPv4 Protocol driver is in the Dhcp4Init or + Dhcp4InitReboot state. + If the DHCP process completes successfully, the state of the EFI DHCPv4 Protocol + driver will be transferred through Dhcp4Selecting and Dhcp4Requesting to the + Dhcp4Bound state. The CompletionEvent will then be signaled if it is not NULL. + If the process aborts, either by the user or by some unexpected network error, + the state is restored to the Dhcp4Init state. The Start() function can be called + again to restart the process. + Refer to RFC 2131 for precise state transitions during this process. At the + time when each event occurs in this process, the callback function that was set + by EFI_DHCP4_PROTOCOL.Configure() will be called and the user can take this + opportunity to control the process. + @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param CompletionEvent If not NULL, indicates the event that will be signaled when the EFI DHCPv4 Protocol driver is transferred into the @@ -263,6 +310,18 @@ EFI_STATUS /** Extends the lease time by sending a request packet. + + The RenewRebind() function is used to manually extend the lease time when the + EFI DHCPv4 Protocol driver is in the Dhcp4Bound state and the lease time has + not expired yet. This function will send a request packet to the previously + found server (or to any server when RebindRequest is TRUE) and transfer the + state into the Dhcp4Renewing state (or Dhcp4Rebinding when RebindingRequest is + TRUE). When a response is received, the state is returned to Dhcp4Bound. + If no response is received before the try count is exceeded (the RequestTryCount + field that is specified in EFI_DHCP4_CONFIG_DATA) but before the lease time that + was issued by the previous server expires, the driver will return to the Dhcp4Bound + state and the previous configuration is restored. The outgoing and incoming packets + can be captured by the EFI_DHCP4_CALLBACK function. @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param RebindRequest If TRUE, this function broadcasts the request packets and enters @@ -298,6 +357,16 @@ EFI_STATUS /** Releases the current address configuration. + The Release() function releases the current configured IP address by doing either + of the following: + * Sending a DHCPRELEASE packet when the EFI DHCPv4 Protocol driver is in the + Dhcp4Bound state + * Setting the previously assigned IP address that was provided with the + EFI_DHCP4_PROTOCOL.Configure() function to 0.0.0.0 when the driver is in + Dhcp4InitReboot state + After a successful call to this function, the EFI DHCPv4 Protocol driver returns + to the Dhcp4Init state and any subsequent incoming packets will be discarded silently. + @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Init phase. @@ -314,6 +383,12 @@ EFI_STATUS /** Stops the current address configuration. + + The Stop() function is used to stop the DHCP configuration process. After this + function is called successfully, the EFI DHCPv4 Protocol driver is transferred + into the Dhcp4Stopped state. EFI_DHCP4_PROTOCOL.Configure() needs to be called + before DHCP configuration process can be started again. This function can be + called when the EFI DHCPv4 Protocol driver is in any state. @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @@ -330,6 +405,11 @@ EFI_STATUS /** Builds a DHCP packet, given the options to be appended or deleted or replaced. + The Build() function is used to assemble a new packet from the original packet + by replacing or deleting existing options or appending new options. This function + does not change any state of the EFI DHCPv4 Protocol driver and can be used at + any time. + @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param SeedPacket Initial packet to be used as a base for building new packet. @param DeleteCount Number of opcodes in the DeleteList. @@ -360,8 +440,14 @@ EFI_STATUS IN EFI_DHCP4_PACKET_OPTION *AppendList[] OPTIONAL, OUT EFI_DHCP4_PACKET **NewPacket ); + + /** Transmits a DHCP formatted packet and optionally waits for responses. + + The TransmitReceive() function is used to transmit a DHCP packet and optionally + wait for the response from servers. This function does not change the state of + the EFI DHCPv4 Protocol driver and thus can be used at any time. @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param Token Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure. @@ -385,6 +471,14 @@ EFI_STATUS /** Parses the packed DHCP option data. + + The Parse() function is used to retrieve the option list from a DHCP packet. + If *OptionCount isn’t zero, and there is enough space for all the DHCP options + in the Packet, each element of PacketOptionList is set to point to somewhere in + the Packet->Dhcp4.Option where a new DHCP option begins. If RFC3396 is supported, + the caller should reassemble the parsed DHCP options to get the finial result. + If *OptionCount is zero or there isn’t enough space for all of them, the number + of DHCP options in the Packet is returned in OptionCount. @param This Pointer to the EFI_DHCP4_PROTOCOL instance. @param Packet Pointer to packet to be parsed. -- cgit v1.2.3