Update comments for Protocol definitions to match UEFI spec.
And add the missing comments for the data structure. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6635 6f19259b-4bc3-4df7-8a09-765794883524
This commit is contained in:
@@ -33,41 +33,69 @@ typedef struct _EFI_DHCP4_PROTOCOL EFI_DHCP4_PROTOCOL;
|
||||
|
||||
#pragma pack(1)
|
||||
typedef struct {
|
||||
///
|
||||
/// DHCP option code.
|
||||
///
|
||||
UINT8 OpCode;
|
||||
///
|
||||
/// Length of the DHCP option data. Not present if OpCode is 0 or 255.
|
||||
///
|
||||
UINT8 Length;
|
||||
///
|
||||
/// Start of the DHCP option data. Not present if OpCode is 0 or 255 or if Length is zero.
|
||||
///
|
||||
UINT8 Data[1];
|
||||
} EFI_DHCP4_PACKET_OPTION;
|
||||
#pragma pack()
|
||||
|
||||
|
||||
#pragma pack(1)
|
||||
///
|
||||
/// EFI_DHCP4_PACKET defines the format of DHCPv4 packets. See RFC 2131 for more information.
|
||||
///
|
||||
typedef struct {
|
||||
UINT8 OpCode;
|
||||
UINT8 HwType;
|
||||
UINT8 HwAddrLen;
|
||||
UINT8 Hops;
|
||||
UINT32 Xid;
|
||||
UINT16 Seconds;
|
||||
UINT16 Reserved;
|
||||
EFI_IPv4_ADDRESS ClientAddr; ///< Client IP address from client
|
||||
EFI_IPv4_ADDRESS YourAddr; ///< Client IP address from server
|
||||
EFI_IPv4_ADDRESS ServerAddr; ///< IP address of next server in bootstrap
|
||||
EFI_IPv4_ADDRESS GatewayAddr; ///< Relay agent IP address
|
||||
UINT8 ClientHwAddr[16]; ///< Client hardware address
|
||||
CHAR8 ServerName[64];
|
||||
CHAR8 BootFileName[128];
|
||||
UINT8 OpCode;
|
||||
UINT8 HwType;
|
||||
UINT8 HwAddrLen;
|
||||
UINT8 Hops;
|
||||
UINT32 Xid;
|
||||
UINT16 Seconds;
|
||||
UINT16 Reserved;
|
||||
EFI_IPv4_ADDRESS ClientAddr; ///< Client IP address from client
|
||||
EFI_IPv4_ADDRESS YourAddr; ///< Client IP address from server
|
||||
EFI_IPv4_ADDRESS ServerAddr; ///< IP address of next server in bootstrap
|
||||
EFI_IPv4_ADDRESS GatewayAddr; ///< Relay agent IP address
|
||||
UINT8 ClientHwAddr[16]; ///< Client hardware address
|
||||
CHAR8 ServerName[64];
|
||||
CHAR8 BootFileName[128];
|
||||
}EFI_DHCP4_HEADER;
|
||||
#pragma pack()
|
||||
|
||||
|
||||
#pragma pack(1)
|
||||
typedef struct {
|
||||
///
|
||||
/// Size of the EFI_DHCP4_PACKET buffer.
|
||||
///
|
||||
UINT32 Size;
|
||||
///
|
||||
/// Length of the EFI_DHCP4_PACKET from the first byte of the Header field
|
||||
/// to the last byte of the Option[] field.
|
||||
///
|
||||
UINT32 Length;
|
||||
|
||||
struct {
|
||||
///
|
||||
/// DHCP packet header.
|
||||
///
|
||||
EFI_DHCP4_HEADER Header;
|
||||
///
|
||||
/// DHCP magik cookie in network byte order.
|
||||
///
|
||||
UINT32 Magik;
|
||||
///
|
||||
/// Start of the DHCP packed option data.
|
||||
///
|
||||
UINT8 Option[1];
|
||||
} Dhcp4;
|
||||
} EFI_DHCP4_PACKET;
|
||||
@@ -75,30 +103,103 @@ typedef struct {
|
||||
|
||||
|
||||
typedef enum {
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver is stopped
|
||||
///
|
||||
Dhcp4Stopped = 0x0,
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver is inactive
|
||||
///
|
||||
Dhcp4Init = 0x1,
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver is collecting DHCP offer packets from DHCP servers.
|
||||
///
|
||||
Dhcp4Selecting = 0x2,
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver has sent the request to the DHCP server and is waiting for a response.
|
||||
///
|
||||
Dhcp4Requesting = 0x3,
|
||||
///
|
||||
/// The DHCP configuration has completed.
|
||||
///
|
||||
Dhcp4Bound = 0x4,
|
||||
///
|
||||
/// The DHCP configuration is being renewed and another request has
|
||||
/// been sent out, but it has not received a response from the server yet.
|
||||
///
|
||||
Dhcp4Renewing = 0x5,
|
||||
///
|
||||
/// The DHCP configuration has timed out and the EFI DHCPv4
|
||||
/// Protocol driver is trying to extend the lease time.
|
||||
///
|
||||
Dhcp4Rebinding = 0x6,
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver is initialized with a previously
|
||||
/// allocated or known IP address.
|
||||
///
|
||||
Dhcp4InitReboot = 0x7,
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver is seeking to reuse the previously
|
||||
/// allocated IP address by sending a request to the DHCP server.
|
||||
///
|
||||
Dhcp4Rebooting = 0x8
|
||||
} EFI_DHCP4_STATE;
|
||||
|
||||
|
||||
typedef enum{
|
||||
///
|
||||
/// A DHCPDISCOVER packet is about to be sent.
|
||||
///
|
||||
Dhcp4SendDiscover = 0x01,
|
||||
///
|
||||
/// A DHCPOFFER packet was just received.
|
||||
///
|
||||
Dhcp4RcvdOffer = 0x02,
|
||||
///
|
||||
/// It is time for Dhcp4Callback to select an offer.
|
||||
///
|
||||
Dhcp4SelectOffer = 0x03,
|
||||
///
|
||||
/// A request packet is about to be sent.
|
||||
///
|
||||
Dhcp4SendRequest = 0x04,
|
||||
///
|
||||
/// A DHCPACK packet was received and will be passed to Dhcp4Callback.
|
||||
///
|
||||
Dhcp4RcvdAck = 0x05,
|
||||
///
|
||||
/// A DHCPNAK packet was received and will be passed to Dhcp4Callback.
|
||||
///
|
||||
Dhcp4RcvdNak = 0x06,
|
||||
///
|
||||
/// A decline packet is about to be sent.
|
||||
///
|
||||
Dhcp4SendDecline = 0x07,
|
||||
///
|
||||
/// The DHCP configuration process has completed. No packet is associated with this event.
|
||||
///
|
||||
Dhcp4BoundCompleted = 0x08,
|
||||
///
|
||||
/// It is time to enter the Dhcp4Renewing state and to contact the server
|
||||
/// that originally issued the network address. No packet is associated with this event.
|
||||
///
|
||||
Dhcp4EnterRenewing = 0x09,
|
||||
///
|
||||
/// It is time to enter the Dhcp4Rebinding state and to contact any server.
|
||||
/// No packet is associated with this event.
|
||||
///
|
||||
Dhcp4EnterRebinding = 0x0a,
|
||||
///
|
||||
/// The configured IP address was lost either because the lease has expired,
|
||||
/// the user released the configuration, or a DHCPNAK packet was received in
|
||||
/// the Dhcp4Renewing or Dhcp4Rebinding state. No packet is associated with this event.
|
||||
///
|
||||
Dhcp4AddressLost = 0x0b,
|
||||
///
|
||||
/// The DHCP process failed because a DHCPNAK packet was received or the user
|
||||
/// aborted the DHCP process at a time when the configuration was not available yet.
|
||||
/// No packet is associated with this event.
|
||||
///
|
||||
Dhcp4Fail = 0x0c
|
||||
} EFI_DHCP4_EVENT;
|
||||
|
||||
@@ -142,51 +243,165 @@ EFI_STATUS
|
||||
OUT EFI_DHCP4_PACKET **NewPacket OPTIONAL
|
||||
);
|
||||
|
||||
|
||||
typedef struct {
|
||||
///
|
||||
/// Number of times to try sending DHCPDISCOVER packets and
|
||||
/// waiting for DHCPOFFER packets before accepting failure.
|
||||
/// Set to zero to use the default try counts and timeout values.
|
||||
///
|
||||
UINT32 DiscoverTryCount;
|
||||
///
|
||||
/// Maximum amount of time (in seconds) to wait for DHCPOFFER packets in each
|
||||
/// of the retries. Timeout values of zero will default to a timeout value
|
||||
/// of one second. Set to NULL to use default timeout values.
|
||||
///
|
||||
UINT32 *DiscoverTimeout;
|
||||
///
|
||||
/// Number of times to try sending DHCPREQUEST packets and waiting for DHCPACK
|
||||
/// packets before accepting failure. Set to zero to use the default try counts and timeout values.
|
||||
///
|
||||
UINT32 RequestTryCount;
|
||||
///
|
||||
/// Maximum amount of time (in seconds) to wait for DHCPACK packets in each of the retries.
|
||||
/// Timeout values of zero will default to a timeout value of one second.
|
||||
/// Set to NULL to use default timeout values.
|
||||
///
|
||||
UINT32 *RequestTimeout;
|
||||
///
|
||||
/// Setting this parameter to the previously allocated IP address will cause
|
||||
/// the EFI DHCPv4 Protocol driver to enter the Dhcp4InitReboot state.
|
||||
/// Set this field to 0.0.0.0 to enter the Dhcp4Init state.
|
||||
///
|
||||
EFI_IPv4_ADDRESS ClientAddress;
|
||||
///
|
||||
/// The callback function to intercept various events that occurred in
|
||||
/// the DHCP configuration process. Set to NULL to ignore all those events.
|
||||
///
|
||||
EFI_DHCP4_CALLBACK Dhcp4Callback;
|
||||
void *CallbackContext;
|
||||
///
|
||||
/// Pointer to the context that will be passed to Dhcp4Callback when it is called.
|
||||
///
|
||||
VOID *CallbackContext;
|
||||
///
|
||||
/// Number of DHCP options in the OptionList.
|
||||
///
|
||||
UINT32 OptionCount;
|
||||
///
|
||||
/// List of DHCP options to be included in every DHCPDISCOVER packet and
|
||||
/// subsequent DHCPREQUEST packet that is generated from DHCPOFFER packets.
|
||||
///
|
||||
EFI_DHCP4_PACKET_OPTION **OptionList;
|
||||
} EFI_DHCP4_CONFIG_DATA;
|
||||
|
||||
|
||||
typedef struct {
|
||||
///
|
||||
/// The EFI DHCPv4 Protocol driver operating state.
|
||||
///
|
||||
EFI_DHCP4_STATE State;
|
||||
///
|
||||
/// The configuration data of the current EFI DHCPv4 Protocol driver instance.
|
||||
///
|
||||
EFI_DHCP4_CONFIG_DATA ConfigData;
|
||||
///
|
||||
/// The client IP address that was acquired from the DHCP server. If it is zero,
|
||||
/// the DHCP acquisition has not completed yet and the following fields in this structure are undefined.
|
||||
///
|
||||
EFI_IPv4_ADDRESS ClientAddress;
|
||||
///
|
||||
/// The local hardware address.
|
||||
///
|
||||
EFI_MAC_ADDRESS ClientMacAddress;
|
||||
///
|
||||
/// The server IP address that is providing the DHCP service to this client.
|
||||
///
|
||||
EFI_IPv4_ADDRESS ServerAddress;
|
||||
///
|
||||
/// The router IP address that was acquired from the DHCP server.
|
||||
/// May be zero if the server does not offer this address.
|
||||
///
|
||||
EFI_IPv4_ADDRESS RouterAddress;
|
||||
///
|
||||
/// The subnet mask of the connected network that was acquired from the DHCP server.
|
||||
///
|
||||
EFI_IPv4_ADDRESS SubnetMask;
|
||||
///
|
||||
/// The lease time (in 1-second units) of the configured IP address.
|
||||
/// The value 0xFFFFFFFF means that the lease time is infinite.
|
||||
/// A default lease of 7 days is used if the DHCP server does not provide a value.
|
||||
///
|
||||
UINT32 LeaseTime;
|
||||
///
|
||||
/// The cached latest DHCPACK or DHCPNAK or BOOTP REPLY packet. May be NULL if no packet is cached.
|
||||
///
|
||||
EFI_DHCP4_PACKET *ReplyPacket;
|
||||
} EFI_DHCP4_MODE_DATA;
|
||||
|
||||
|
||||
typedef struct {
|
||||
///
|
||||
/// Alternate listening address. It can be a unicast, multicast, or broadcast address.
|
||||
///
|
||||
EFI_IPv4_ADDRESS ListenAddress;
|
||||
///
|
||||
/// The subnet mask of above listening unicast/broadcast IP address.
|
||||
/// Ignored if ListenAddress is a multicast address.
|
||||
///
|
||||
EFI_IPv4_ADDRESS SubnetMask;
|
||||
///
|
||||
/// Alternate station source (or listening) port number.
|
||||
/// If zero, then the default station port number (68) will be used.
|
||||
///
|
||||
UINT16 ListenPort;
|
||||
} EFI_DHCP4_LISTEN_POINT;
|
||||
|
||||
|
||||
typedef struct {
|
||||
///
|
||||
/// The completion status of transmitting and receiving.
|
||||
///
|
||||
EFI_STATUS Status;
|
||||
///
|
||||
/// If not NULL, the event that will be signaled when the collection process
|
||||
/// completes. If NULL, this function will busy-wait until the collection process competes.
|
||||
///
|
||||
EFI_EVENT CompletionEvent;
|
||||
///
|
||||
/// Pointer to the server IP address. This address may be a unicast, multicast, or broadcast address.
|
||||
///
|
||||
EFI_IPv4_ADDRESS RemoteAddress;
|
||||
///
|
||||
/// Server listening port number. If zero, the default server listening port number (67) will be used.
|
||||
///
|
||||
UINT16 RemotePort;
|
||||
///
|
||||
/// Pointer to the gateway address to override the existing setting.
|
||||
///
|
||||
EFI_IPv4_ADDRESS GatewayAddress;
|
||||
///
|
||||
/// The number of entries in ListenPoints. If zero, the default station address and port number 68 are used.
|
||||
///
|
||||
UINT32 ListenPointCount;
|
||||
///
|
||||
/// An array of station address and port number pairs that are used as receiving filters.
|
||||
/// The first entry is also used as the source address and source port of the outgoing packet.
|
||||
///
|
||||
EFI_DHCP4_LISTEN_POINT *ListenPoints;
|
||||
///
|
||||
/// Number of seconds to collect responses. Zero is invalid.
|
||||
///
|
||||
UINT32 TimeoutValue;
|
||||
///
|
||||
/// Pointer to the packet to be transmitted.
|
||||
///
|
||||
EFI_DHCP4_PACKET *Packet;
|
||||
///
|
||||
/// Number of received packets.
|
||||
///
|
||||
UINT32 ResponseCount;
|
||||
///
|
||||
/// Pointer to the allocated list of received packets.
|
||||
///
|
||||
EFI_DHCP4_PACKET *ResponseList;
|
||||
} EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN;
|
||||
|
||||
@@ -248,7 +463,12 @@ EFI_STATUS
|
||||
Dhcp4Stopped, Dhcp4Init, Dhcp4InitReboot, or Dhcp4Bound state;
|
||||
Or onother instance of this EFI DHCPv4 Protocol driver is already
|
||||
in a valid configured state.
|
||||
@retval EFI_INVALID_PARAMETER Some parameter is NULL.
|
||||
@retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
|
||||
This is NULL.
|
||||
DiscoverTryCount > 0 and DiscoverTimeout is NULL
|
||||
RequestTryCount > 0 and RequestTimeout is NULL.
|
||||
OptionCount >0 and OptionList is NULL.
|
||||
ClientAddress is not a valid unicast address.
|
||||
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
|
||||
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
|
||||
|
||||
@@ -426,7 +646,15 @@ EFI_STATUS
|
||||
|
||||
@retval EFI_SUCCESS The new packet was built.
|
||||
@retval EFI_OUT_OF_RESOURCES Storage for the new packet could not be allocated.
|
||||
@retval EFI_INVALID_PARAMETER Some parameter is NULL.
|
||||
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
|
||||
This is NULL.
|
||||
SeedPacket is NULL.
|
||||
SeedPacket is not a well-formed DHCP packet.
|
||||
AppendCount is not zero and AppendList is NULL.
|
||||
DeleteCount is not zero and DeleteList is NULL.
|
||||
NewPacket is NULL
|
||||
Both DeleteCount and AppendCount are zero and
|
||||
NewPacket is not NULL.
|
||||
|
||||
**/
|
||||
typedef
|
||||
@@ -453,11 +681,17 @@ EFI_STATUS
|
||||
@param Token Pointer to the EFI_DHCP4_TRANSMIT_RECEIVE_TOKEN structure.
|
||||
|
||||
@retval EFI_SUCCESS The packet was successfully queued for transmission.
|
||||
@retval EFI_INVALID_PARAMETER Some parameter is NULL.
|
||||
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
|
||||
This is NULL.
|
||||
Token.RemoteAddress is zero.
|
||||
Token.Packet is NULL.
|
||||
Token.Packet is not a well-formed DHCP packet.
|
||||
The transaction ID in Token.Packet is in use by another DHCP process.
|
||||
@retval EFI_NOT_READY The previous call to this function has not finished yet. Try to call
|
||||
this function after collection process completes.
|
||||
@retval EFI_NO_MAPPING The default station address is not available yet.
|
||||
@retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
|
||||
@retval EFI_UNSUPPORTED The implementation doesn’t support this function
|
||||
@retval Others Some other unexpected error occurred.
|
||||
|
||||
**/
|
||||
@@ -489,11 +723,16 @@ EFI_STATUS
|
||||
options are not included.
|
||||
|
||||
@retval EFI_SUCCESS The packet was successfully parsed.
|
||||
@retval EFI_INVALID_PARAMETER Some parameter is NULL.
|
||||
@retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
|
||||
This is NULL.
|
||||
Packet is NULL.
|
||||
Packet is not a well-formed DHCP packet.
|
||||
OptionCount is NULL.
|
||||
@retval EFI_BUFFER_TOO_SMALL One or more of the following conditions is TRUE:
|
||||
1) *OptionCount is smaller than the number of options that
|
||||
were found in the Packet.
|
||||
2) PacketOptionList is NULL.
|
||||
@retval EFI_OUT_OF_RESOURCE The packet is failed to parse because of resource shortage.
|
||||
|
||||
**/
|
||||
typedef
|
||||
|
Reference in New Issue
Block a user