/** @file\r
- Ihis library is only intended to be used by UEFI network stack modules.\r
+ This library is used to share code between UEFI network stack modules.\r
It provides the helper routines to access UDP service. It is used by both DHCP and MTFTP.\r
\r
Copyright (c) 2006 - 2008, Intel Corporation.<BR>\r
} UDP_POINTS;\r
\r
/**\r
- Prototype called when receiving or sending packets from/to a UDP point.\r
+ Prototype called when receiving or sending packets to or from a UDP point.\r
\r
This prototype is used by both receive and sending when calling\r
- UdpIoRecvDatagram() or UdpIoSendDatagram(). When receiving, Netbuf is allocated by\r
- UDP access point, and released by user. When sending, the NetBuf is from user,\r
- and provided to the callback as a reference.\r
+ UdpIoRecvDatagram() or UdpIoSendDatagram(). When receiving, Netbuf is allocated by the\r
+ UDP access point and released by the user. When sending, the user allocates the the NetBuf, which is then\r
+ provided to the callback as a reference.\r
\r
@param[in] Packet Packet received or sent\r
@param[in] Points The Udp4 address pair corresponds to the Udp4 IO\r
);\r
\r
///\r
-/// This structure is used internally by UdpIo Library.\r
+/// This structure is used internally by the UdpIo Library.\r
///\r
/// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,\r
/// the CallBack will be called. Only one receive request is sent to UDP at a\r
/// This structure is used internally by UdpIo Library.\r
///\r
/// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,\r
-/// the CallBack will be called. There can be several transmit requests and they\r
+/// the CallBack will be called. There can be several transmit requests. All transmit requests\r
/// are linked in a list.\r
///\r
typedef struct {\r
///\r
/// Type defined as UDP_IO_PORT.\r
///\r
-/// The data structure wraps Udp4 instance and its configuration. It is used by\r
-/// UdpIo Library to do all Udp4 operations.\r
+/// This data structure wraps the Udp4 instance and configuration. \r
+/// UdpIo Library uses this structure for all Udp4 operations.\r
///\r
struct _UDP_IO_PORT {\r
UINT32 Signature;\r
@param[in] UdpIo The UDP_IO_PORT to configure\r
@param[in] Context User-defined data when calling UdpIoCreatePort()\r
\r
- @retval EFI_SUCCESS The configure process succeeds\r
+ @retval EFI_SUCCESS The configuration succeeded\r
@retval Others The UDP_IO_PORT fails to configure indicating\r
UdpIoCreatePort() should fail\r
**/\r
@param[in] Token The UDP_TX_TOKEN to decide whether to cancel\r
@param[in] Context User-defined data in UdpIoCancelDgrams()\r
\r
- @retval TRUE To cancel the UDP_TX_TOKEN\r
+ @retval TRUE Cancel the UDP_TX_TOKEN\r
@retval FALSE Do not cancel this UDP_TX_TOKEN\r
\r
**/\r
);\r
\r
/**\r
- Cancel all the sent datagram that pass the selection criteria of ToCancel.\r
+ Cancel all sent datagrams selected by the parameter ToCancel.\r
If ToCancel is NULL, all the datagrams are cancelled.\r
\r
@param[in] UdpIo The UDP_IO_PORT to cancel packet.\r
@param[in] IoStatus The IoStatus to return to the packet owners.\r
- @param[in] ToCancel The select funtion to test whether to cancel this\r
- packet or not.\r
+ @param[in] ToCancel Sets the criteria for canceling a packet. \r
@param[in] Context The opaque parameter to the ToCancel.\r
\r
**/\r
);\r
\r
/**\r
- Create a UDP_IO_PORT to access the UDP service. It will create and configure\r
+ Creates a UDP_IO_PORT to access the UDP service. It creates and configures\r
a UDP child.\r
\r
- The function will locate the UDP service binding prototype on the Controller\r
- parameter and use it to create a UDP child (aka Udp instance). Then the UDP\r
- child will be configured by calling Configure function prototype. Any failures\r
- in creating or configure the UDP child will lead to the failure of UDP_IO_PORT\r
- creation.\r
+ This function:\r
+ # locates the UDP service binding prototype on the Controller parameter\r
+ # uses the UDP service binding prototype to create a UDP child (also known as a UDP instance)\r
+ # configures the UDP child by calling Configure function prototype. \r
+ Any failures in creating or configuring the UDP child return NULL for failure. \r
\r
@param[in] Controller The controller that has the UDP service binding.\r
protocol installed.\r
/**\r
Free the UDP_IO_PORT and all its related resources.\r
\r
- The function will cancel all sent datagram and receive request.\r
+ The function cancels all sent datagrams and receive requests.\r
\r
@param[in] UdpIo The UDP_IO_PORT to free.\r
\r
);\r
\r
/**\r
- Clean up the UDP_IO_PORT without freeing it. The function is called when\r
- user wants to re-use the UDP_IO_PORT later.\r
+ Cleans up the UDP_IO_PORT without freeing it. Call this function \r
+ if you intend to later re-use the UDP_IO_PORT.\r
\r
- It will release all the transmitted datagrams and receive request. It will\r
- also configure NULL for the UDP instance.\r
+ This function releases all transmitted datagrams and receive requests and configures NULL for the UDP instance.\r
\r
@param[in] UdpIo The UDP_IO_PORT to clean up.\r
\r
);\r
\r
/**\r
- Send a packet through the UDP_IO_PORT.\r
+ Sends a packet through the UDP_IO_PORT.\r
\r
- The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called\r
- when the packet is sent. The optional parameter EndPoint overrides the default\r
- address pair if specified.\r
+ The packet will be wrapped in UDP_TX_TOKEN. The function specific in the CallBack parameter will be called\r
+ when the packet is sent. If specified, the optional parameter EndPoint overrides the default\r
+ address pair.\r
\r
@param[in] UdpIo The UDP_IO_PORT to send the packet through.\r
@param[in] Packet The packet to send.\r
- @param[in] EndPoint The local and remote access point. Override the\r
+ @param[in] EndPoint The local and remote access point. Overrides the\r
default address pair set during configuration.\r
@param[in] Gateway The gateway to use.\r
@param[in] CallBack The function being called when packet is\r
/**\r
Cancel a single sent datagram.\r
\r
- @param[in] UdpIo The UDP_IO_PORT to cancel the packet from\r
+ @param[in] UdpIo The UDP_IO_PORT from which to cancel the packet \r
@param[in] Packet The packet to cancel\r
\r
**/\r
Issue a receive request to the UDP_IO_PORT.\r
\r
This function is called when upper-layer needs packet from UDP for processing.\r
- Only one receive request is acceptable at a time so a common usage model is\r
+ Only one receive request is acceptable at a time. Therefore, one common usage model is\r
to invoke this function inside its Callback function when the former packet\r
is processed.\r
\r
projects / mirror_edk2.git / blobdiff