mirror of https://github.com/acidanthera/audk.git
updated interface comments per UEFI Spec.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6547 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
jgong5
parent
08a458be1d
commit
faac3f0cfe
|
|
@ -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.
|
||||
|
|
@ -187,6 +194,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
|
||||
|
|
@ -264,6 +311,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
|
||||
the Dhcp4Rebinding state. Otherwise, it sends a unicast
|
||||
|
|
@ -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.
|
||||
|
|
@ -315,6 +384,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.
|
||||
|
||||
@retval EFI_SUCCESS The EFI DHCPv4 Protocol driver is now in the Dhcp4Stopped phase.
|
||||
|
|
@ -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,9 +440,15 @@ 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.
|
||||
|
||||
|
|
@ -386,6 +472,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.
|
||||
@param OptionCount On input, the number of entries in the PacketOptionList.
|
||||
|
|
|
|||
Loading…
Reference in New Issue