From 30c99a724cc3fda9ee853157e07af72335c3f7e3 Mon Sep 17 00:00:00 2001 From: jgong5 Date: Thu, 13 Nov 2008 06:26:27 +0000 Subject: [PATCH] Updated protocol function header per UEFI Spec. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6485 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/Udp4.h | 70 ++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/MdePkg/Include/Protocol/Udp4.h b/MdePkg/Include/Protocol/Udp4.h index b7409f220c..6ba49a7d27 100644 --- a/MdePkg/Include/Protocol/Udp4.h +++ b/MdePkg/Include/Protocol/Udp4.h @@ -125,6 +125,11 @@ typedef struct { /** Reads the current operational settings. + The GetModeData() function copies the current operational settings of this EFI + UDPv4 Protocol instance into user-supplied buffers. This function is used + optionally to retrieve the operational mode data of underlying networks or + drivers. + @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param Udp4ConfigData Pointer to the buffer to receive the current configuration data. @param Ip4ModeData Pointer to the EFI IPv4 Protocol mode data structure. @@ -151,6 +156,17 @@ EFI_STATUS /** Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv4 Protocol. + + The Configure() function is used to do the following: + * Initialize and start this instance of the EFI UDPv4 Protocol. + * Change the filtering rules and operational parameters. + * Reset this instance of the EFI UDPv4 Protocol. + Until these parameters are initialized, no network traffic can be sent or + received by this instance. This instance can be also reset by calling Configure() + with UdpConfigData set to NULL. Once reset, the receiving queue and transmitting + queue are flushed and no traffic is allowed through this instance. + With different parameters in UdpConfigData, Configure() can be used to bind + this instance to specified port. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param Udp4ConfigData Pointer to the buffer to receive the current configuration data. @@ -179,6 +195,10 @@ EFI_STATUS /** Joins and leaves multicast groups. + + The Groups() function is used to enable and disable the multicast group + filtering. If the JoinFlag is FALSE and the MulticastAddress is NULL, then all + currently joined groups are left. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param JoinFlag Set to TRUE to join a multicast group. Set to FALSE to leave one @@ -212,6 +232,24 @@ EFI_STATUS /** Adds and deletes routing table entries. + + The Routes() function adds a route to or deletes a route from the routing table. + Routes are determined by comparing the SubnetAddress with the destination IP + address and arithmetically AND-ing it with the SubnetMask. The gateway address + must be on the same subnet as the configured station address. + The default route is added with SubnetAddress and SubnetMask both set to 0.0.0.0. + The default route matches all destination IP addresses that do not match any + other routes. + A zero GatewayAddress is a nonroute. Packets are sent to the destination IP + address if it can be found in the Address Resolution Protocol (ARP) cache or + on the local subnet. One automatic nonroute entry will be inserted into the + routing table for outgoing packets that are addressed to a local subnet + (gateway address of 0.0.0.0). + Each instance of the EFI UDPv4 Protocol has its own independent routing table. + Instances of the EFI UDPv4 Protocol that use the default IP address will also + have copies of the routing table provided by the EFI_IP4_CONFIG_PROTOCOL. These + copies will be updated automatically whenever the IP driver reconfigures its + instances; as a result, the previous modification to these copies will be lost. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param DeleteRoute Set to TRUE to delete this route from the routing table. @@ -242,6 +280,15 @@ EFI_STATUS /** Polls for incoming data packets and processes outgoing data packets. + + The Poll() function can be used by network drivers and applications to increase + the rate that data packets are moved between the communications device and the + transmit and receive queues. + In some systems, the periodic timer event in the managed network driver may not + poll the underlying communications device fast enough to transmit and/or receive + all data packets without missing incoming packets or dropping outgoing packets. + Drivers and applications that are experiencing packet loss should try calling + the Poll() function more often. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @@ -259,6 +306,15 @@ EFI_STATUS /** Places an asynchronous receive request into the receiving queue. + + The Receive() function places a completion token into the receive packet queue. + This function is always asynchronous. + The caller must fill in the Token.Event field in the completion token, and this + field cannot be NULL. When the receive operation completes, the EFI UDPv4 Protocol + driver updates the Token.Status and Token.Packet.RxData fields and the Token.Event + is signaled. Providing a proper notification function and context for the event + will enable the user to receive the notification and receiving status. That + notification function is guaranteed to not be re-entered. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param Token Pointer to a token that is associated with the receive data @@ -286,6 +342,13 @@ EFI_STATUS /** Queues outgoing data packets into the transmit queue. + + The Transmit() function places a sending request to this instance of the EFI + UDPv4 Protocol, alongside the transmit data that was filled by the user. Whenever + the packet in the token is sent out or some errors occur, the Token.Event will + be signaled and Token.Status is updated. Providing a proper notification function + and context for the event will enable the user to receive the notification and + transmitting status. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param Token Pointer to the completion token that will be placed into the @@ -316,6 +379,13 @@ EFI_STATUS /** Aborts an asynchronous transmit or receive request. + + The Cancel() function is used to abort a pending transmit or receive request. + If the token is in the transmit or receive request queues, after calling this + function, Token.Status will be set to EFI_ABORTED and then Token.Event will be + signaled. If the token is not in one of the queues, which usually means that + the asynchronous operation has completed, this function will not signal the + token and EFI_NOT_FOUND is returned. @param This Pointer to the EFI_UDP4_PROTOCOL instance. @param Token Pointer to a token that has been issued by -- 2.39.2