/** @file\r
UDP4 Service Binding Protocol as defined in UEFI specification.\r
\r
- The EFI UDPv4 Protocol provides simple packet-oriented services \r
- to transmit and receive UDP packets. \r
+ The EFI UDPv4 Protocol provides simple packet-oriented services\r
+ to transmit and receive UDP packets.\r
\r
- Copyright (c) 2006 - 2009, 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 - 2018, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\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
- @par Revision Reference: \r
- This Protocol is introduced in UEFI Specification 2.0 \r
+ @par Revision Reference:\r
+ This Protocol is introduced in UEFI Specification 2.0.\r
\r
**/\r
\r
0x3ad9df29, 0x4501, 0x478d, {0xb1, 0xf8, 0x7f, 0x7f, 0xe7, 0x0e, 0x50, 0xf3 } \\r
}\r
\r
-typedef struct _EFI_UDP4_PROTOCOL EFI_UDP4_PROTOCOL; \r
- \r
+typedef struct _EFI_UDP4_PROTOCOL EFI_UDP4_PROTOCOL;\r
+\r
+///\r
+/// EFI_UDP4_SERVICE_POINT is deprecated in the UEFI 2.4B and should not be used any more.\r
+/// The definition in here is only present to provide backwards compatability.\r
+///\r
typedef struct {\r
EFI_HANDLE InstanceHandle;\r
EFI_IPv4_ADDRESS LocalAddress;\r
UINT16 LocalPort;\r
EFI_IPv4_ADDRESS RemoteAddress;\r
UINT16 RemotePort;\r
-} EFI_UDP4_SERVICE_POINT; \r
+} EFI_UDP4_SERVICE_POINT;\r
\r
+///\r
+/// EFI_UDP4_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more.\r
+/// The definition in here is only present to provide backwards compatability.\r
+///\r
typedef struct {\r
EFI_HANDLE DriverHandle;\r
UINT32 ServiceCount;\r
EFI_UDP4_SESSION_DATA *UdpSessionData; //OPTIONAL\r
EFI_IPv4_ADDRESS *GatewayAddress; //OPTIONAL\r
UINT32 DataLength;\r
- UINT32 FragmentCount; \r
+ UINT32 FragmentCount;\r
EFI_UDP4_FRAGMENT_DATA FragmentTable[1];\r
} EFI_UDP4_TRANSMIT_DATA;\r
\r
optionally to retrieve the operational mode data of underlying networks or\r
drivers.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
- @param Udp4ConfigData Pointer to the buffer to receive the current configuration data.\r
- @param Ip4ModeData Pointer to the EFI IPv4 Protocol mode data structure.\r
- @param MnpConfigData Pointer to the managed network configuration data structure.\r
- @param SnpModeData Pointer to the simple network mode data structure.\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param Udp4ConfigData The pointer to the buffer to receive the current configuration data.\r
+ @param Ip4ModeData The pointer to the EFI IPv4 Protocol mode data structure.\r
+ @param MnpConfigData The pointer to the managed network configuration data structure.\r
+ @param SnpModeData The pointer to the simple network mode data structure.\r
\r
@retval EFI_SUCCESS The mode data was read.\r
@retval EFI_NOT_STARTED When Udp4ConfigData is queried, no configuration data is\r
OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL,\r
OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL,\r
OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL\r
- ); \r
- \r
+ );\r
+\r
\r
/**\r
Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv4\r
Protocol.\r
- \r
+\r
The Configure() function is used to do the following:\r
* Initialize and start this instance of the EFI UDPv4 Protocol.\r
* Change the filtering rules and operational parameters.\r
With different parameters in UdpConfigData, Configure() can be used to bind\r
this instance to specified port.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
- @param Udp4ConfigData Pointer to the buffer to receive the current configuration data.\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param Udp4ConfigData The pointer to the buffer to receive the current configuration data.\r
\r
@retval EFI_SUCCESS The configuration settings were set, changed, or reset successfully.\r
@retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,\r
RARP, etc.) is not finished yet.\r
- @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:\r
+ @retval EFI_INVALID_PARAMETER This is NULL.\r
+ @retval EFI_INVALID_PARAMETER UdpConfigData.StationAddress is not a valid unicast IPv4 address.\r
+ @retval EFI_INVALID_PARAMETER UdpConfigData.SubnetMask is not a valid IPv4 address mask. The subnet\r
+ mask must be contiguous.\r
+ @retval EFI_INVALID_PARAMETER UdpConfigData.RemoteAddress is not a valid unicast IPv4 address if it\r
+ is not zero.\r
@retval EFI_ALREADY_STARTED The EFI UDPv4 Protocol instance is already started/configured\r
and must be stopped/reset before it can be reconfigured.\r
@retval EFI_ACCESS_DENIED UdpConfigData. AllowDuplicatePort is FALSE\r
@retval EFI_OUT_OF_RESOURCES The EFI UDPv4 Protocol driver cannot allocate memory for this\r
EFI UDPv4 Protocol instance.\r
@retval EFI_DEVICE_ERROR An unexpected network or system error occurred and this instance\r
- was not opened. \r
+ was not opened.\r
\r
**/\r
typedef\r
(EFIAPI *EFI_UDP4_CONFIGURE)(\r
IN EFI_UDP4_PROTOCOL *This,\r
IN EFI_UDP4_CONFIG_DATA *UdpConfigData OPTIONAL\r
- ); \r
+ );\r
\r
/**\r
Joins and leaves multicast groups.\r
- \r
+\r
The Groups() function is used to enable and disable the multicast group\r
filtering. If the JoinFlag is FALSE and the MulticastAddress is NULL, then all\r
currently joined groups are left.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
@param JoinFlag Set to TRUE to join a multicast group. Set to FALSE to leave one\r
or all multicast groups.\r
- @param MulticastAddress Pointer to multicast group address to join or leave.\r
+ @param MulticastAddress The pointer to multicast group address to join or leave.\r
\r
@retval EFI_SUCCESS The operation completed successfully.\r
@retval EFI_NOT_STARTED The EFI UDPv4 Protocol instance has not been started.\r
IN EFI_UDP4_PROTOCOL *This,\r
IN BOOLEAN JoinFlag,\r
IN EFI_IPv4_ADDRESS *MulticastAddress OPTIONAL\r
- ); \r
+ );\r
\r
/**\r
Adds and deletes routing table entries.\r
- \r
+\r
The Routes() function adds a route to or deletes a route from the routing table.\r
Routes are determined by comparing the SubnetAddress with the destination IP\r
address and arithmetically AND-ing it with the SubnetMask. The gateway address\r
copies will be updated automatically whenever the IP driver reconfigures its\r
instances; as a result, the previous modification to these copies will be lost.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
@param DeleteRoute Set to TRUE to delete this route from the routing table.\r
Set to FALSE to add this route to the routing table.\r
@param SubnetAddress The destination network address that needs to be routed.\r
IN EFI_IPv4_ADDRESS *SubnetAddress,\r
IN EFI_IPv4_ADDRESS *SubnetMask,\r
IN EFI_IPv4_ADDRESS *GatewayAddress\r
- ); \r
+ );\r
\r
/**\r
Polls for incoming data packets and processes outgoing data packets.\r
- \r
+\r
The Poll() function can be used by network drivers and applications to increase\r
the rate that data packets are moved between the communications device and the\r
transmit and receive queues.\r
Drivers and applications that are experiencing packet loss should try calling\r
the Poll() function more often.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
\r
@retval EFI_SUCCESS Incoming or outgoing data was processed.\r
@retval EFI_INVALID_PARAMETER This is NULL.\r
EFI_STATUS\r
(EFIAPI *EFI_UDP4_POLL)(\r
IN EFI_UDP4_PROTOCOL *This\r
- ); \r
+ );\r
\r
/**\r
Places an asynchronous receive request into the receiving queue.\r
- \r
+\r
The Receive() function places a completion token into the receive packet queue.\r
This function is always asynchronous.\r
The caller must fill in the Token.Event field in the completion token, and this\r
will enable the user to receive the notification and receiving status. That\r
notification function is guaranteed to not be re-entered.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
- @param Token Pointer to a token that is associated with the receive data\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param Token The pointer to a token that is associated with the receive data\r
descriptor.\r
\r
@retval EFI_SUCCESS The receive completion token was cached.\r
@retval EFI_NOT_STARTED This EFI UDPv4 Protocol instance has not been started.\r
@retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.)\r
is not finished yet.\r
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:\r
+ @retval EFI_INVALID_PARAMETER This is NULL.\r
+ @retval EFI_INVALID_PARAMETER Token is NULL.\r
+ @retval EFI_INVALID_PARAMETER Token.Event is NULL.\r
@retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of system\r
resources (usually memory).\r
@retval EFI_DEVICE_ERROR An unexpected system or network error occurred.\r
(EFIAPI *EFI_UDP4_RECEIVE)(\r
IN EFI_UDP4_PROTOCOL *This,\r
IN EFI_UDP4_COMPLETION_TOKEN *Token\r
- ); \r
+ );\r
\r
/**\r
Queues outgoing data packets into the transmit queue.\r
- \r
+\r
The Transmit() function places a sending request to this instance of the EFI\r
UDPv4 Protocol, alongside the transmit data that was filled by the user. Whenever\r
the packet in the token is sent out or some errors occur, the Token.Event will\r
and context for the event will enable the user to receive the notification and\r
transmitting status.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
- @param Token Pointer to the completion token that will be placed into the\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param Token The pointer to the completion token that will be placed into the\r
transmit queue.\r
\r
@retval EFI_SUCCESS The data has been queued for transmission.\r
(EFIAPI *EFI_UDP4_TRANSMIT)(\r
IN EFI_UDP4_PROTOCOL *This,\r
IN EFI_UDP4_COMPLETION_TOKEN *Token\r
- ); \r
+ );\r
\r
/**\r
Aborts an asynchronous transmit or receive request.\r
- \r
+\r
The Cancel() function is used to abort a pending transmit or receive request.\r
If the token is in the transmit or receive request queues, after calling this\r
function, Token.Status will be set to EFI_ABORTED and then Token.Event will be\r
the asynchronous operation has completed, this function will not signal the\r
token and EFI_NOT_FOUND is returned.\r
\r
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.\r
- @param Token Pointer to a token that has been issued by\r
+ @param This The pointer to the EFI_UDP4_PROTOCOL instance.\r
+ @param Token The pointer to a token that has been issued by\r
EFI_UDP4_PROTOCOL.Transmit() or\r
EFI_UDP4_PROTOCOL.Receive().If NULL, all pending\r
tokens are aborted.\r
(EFIAPI *EFI_UDP4_CANCEL)(\r
IN EFI_UDP4_PROTOCOL *This,\r
IN EFI_UDP4_COMPLETION_TOKEN *Token OPTIONAL\r
- ); \r
+ );\r
\r
///\r
-/// The EFI_UDP4_PROTOCOL defines an EFI UDPv4 Protocol session that can be used \r
-/// by any network drivers, applications, or daemons to transmit or receive UDP packets. \r
-/// This protocol instance can either be bound to a specified port as a service or \r
-/// connected to some remote peer as an active client. Each instance has its own settings, \r
+/// The EFI_UDP4_PROTOCOL defines an EFI UDPv4 Protocol session that can be used\r
+/// by any network drivers, applications, or daemons to transmit or receive UDP packets.\r
+/// This protocol instance can either be bound to a specified port as a service or\r
+/// connected to some remote peer as an active client. Each instance has its own settings,\r
/// such as the routing table and group table, which are independent from each other.\r
///\r
struct _EFI_UDP4_PROTOCOL {\r