2 The helper routines to access UDP service. It is used by both
5 Copyright (c) 2006 - 2008, Intel Corporation.<BR>
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at<BR>
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19 #include <Protocol/Udp4.h>
21 #include <Library/UdpIoLib.h>
22 #include <Library/NetLib.h>
24 typedef struct _UDP_IO_PORT UDP_IO_PORT
;
27 /// Signatures used by UdpIo Library.
30 UDP_IO_RX_SIGNATURE
= SIGNATURE_32 ('U', 'D', 'P', 'R'),
31 UDP_IO_TX_SIGNATURE
= SIGNATURE_32 ('U', 'D', 'P', 'T'),
32 UDP_IO_SIGNATURE
= SIGNATURE_32 ('U', 'D', 'P', 'I')
33 } UDP_IO_SIGNATURE_TYPE
;
36 /// The Udp4 address pair.
46 Prototype called when receiving or sending packets from/to a UDP point.
48 This prototype is used by both receive and sending when calling
49 UdpIoRecvDatagram or UdpIoSendDatagram. When receiving, Netbuf is allocated by
50 UDP access point, and released by user. When sending, the NetBuf is from user,
51 and provided to the callback as a reference.
53 @param Packet Packet received or sent
54 @param Points The Udp4 address pair corresponds to the Udp4 IO
55 @param IoStatus Packet receiving or sending status
56 @param Context User-defined data when calling UdpIoRecvDatagram or
63 (EFIAPI
*UDP_IO_CALLBACK
) (
65 IN UDP_POINTS
*Points
,
66 IN EFI_STATUS IoStatus
,
71 /// This structure is used internally by UdpIo Library.
73 /// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,
74 /// the CallBack will be called. Only one receive request is sent to UDP at a
75 /// time. HeadLen gives the length of the application's header. UDP_IO will
76 /// make the application's header continuous before delivering up.
82 UDP_IO_CALLBACK CallBack
;
86 EFI_UDP4_COMPLETION_TOKEN UdpToken
;
90 /// This structure is used internally by UdpIo Library.
92 /// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,
93 /// the CallBack will be called. There can be several transmit requests and they
94 /// are linked in a list.
101 UDP_IO_CALLBACK CallBack
;
105 EFI_UDP4_SESSION_DATA UdpSession
;
106 EFI_IPv4_ADDRESS Gateway
;
108 EFI_UDP4_COMPLETION_TOKEN UdpToken
;
109 EFI_UDP4_TRANSMIT_DATA UdpTxData
;
113 /// Type defined as UDP_IO_PORT.
115 /// The data structure wraps Udp4 instance and its configuration. It is used by
116 /// UdpIo Library to do all Udp4 operations.
118 struct _UDP_IO_PORT
{
124 // Handle used to create/destory UDP child
126 EFI_HANDLE Controller
;
128 EFI_HANDLE UdpHandle
;
130 EFI_UDP4_PROTOCOL
*Udp
; ///< The wrapped Udp4 instance.
131 EFI_UDP4_CONFIG_DATA UdpConfig
;
132 EFI_SIMPLE_NETWORK_MODE SnpMode
;
134 LIST_ENTRY SentDatagram
; ///< A list of UDP_TX_TOKEN.
135 UDP_RX_TOKEN
*RecvRequest
;
139 Prototype called when UdpIo Library configures a Udp4 instance.
141 The prototype is set and called when creating a UDP_IO_PORT in UdpIoCreatePort.
143 @param UdpIo The UDP_IO_PORT to configure
144 @param Context User-defined data when calling UdpIoCreatePort
146 @retval EFI_SUCCESS The configure process succeeds
147 @retval Others The UDP_IO_PORT fails to configure indicating
148 UdpIoCreatePort should fail
152 (EFIAPI
*UDP_IO_CONFIG
) (
153 IN UDP_IO_PORT
*UdpIo
,
158 The select function to decide whether to cancel the UDP_TX_TOKEN. It is used
160 @param Token The UDP_TX_TOKEN to decide whether to cancel
161 @param Context User-defined data in UdpIoCancelDgrams
163 @retval TRUE To cancel the UDP_TX_TOKEN
164 @retval FALSE Do not cancel this UDP_TX_TOKEN
169 (*UDP_IO_TO_CANCEL
) (
170 IN UDP_TX_TOKEN
*Token
,
175 Create a UDP_IO_PORT to access the UDP service. It will create and configure
178 The function will locate the UDP service binding prototype on the Controller
179 parameter and use it to create a UDP child (aka Udp instance). Then the UDP
180 child will be configured by calling Configure function prototype. Any failures
181 in creating or configure the UDP child will lead to the failure of UDP_IO_PORT
184 @param Controller The controller that has the UDP service binding
186 @param Image The image handle for the driver.
187 @param Configure The function to configure the created UDP child
188 @param Context The opaque parameter for the Configure funtion.
190 @return Newly-created UDP_IO_PORT or NULL if failed.
196 IN EFI_HANDLE Controller
,
198 IN UDP_IO_CONFIG Configure
,
203 Free the UDP_IO_PORT and all its related resources.
205 The function will cancel all sent datagram and receive request.
207 @param UdpIo The UDP_IO_PORT to free.
209 @retval EFI_SUCCESS The UDP_IO_PORT is freed.
215 IN UDP_IO_PORT
*UdpIo
219 Clean up the UDP_IO_PORT without freeing it. The function is called when
220 user wants to re-use the UDP_IO_PORT later.
222 It will release all the transmitted datagrams and receive request. It will
223 also configure NULL for the UDP instance.
225 @param UdpIo The UDP_IO_PORT to clean up.
231 IN UDP_IO_PORT
*UdpIo
235 Send a packet through the UDP_IO_PORT.
237 The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called
238 when the packet is sent. The optional parameter EndPoint overrides the default
239 address pair if specified.
241 @param UdpIo The UDP_IO_PORT to send the packet through
242 @param Packet The packet to send
243 @param EndPoint The local and remote access point. Override the
244 default address pair set during configuration.
245 @param Gateway The gateway to use
246 @param CallBack The function being called when packet is
247 transmitted or failed.
248 @param Context The opaque parameter passed to CallBack
250 @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the packet
251 @retval EFI_SUCCESS The packet is successfully delivered to UDP for
258 IN UDP_IO_PORT
*UdpIo
,
260 IN UDP_POINTS
*EndPoint OPTIONAL
,
262 IN UDP_IO_CALLBACK CallBack
,
267 Cancel a single sent datagram.
269 @param UdpIo The UDP_IO_PORT to cancel the packet from
270 @param Packet The packet to cancel
275 UdpIoCancelSentDatagram (
276 IN UDP_IO_PORT
*UdpIo
,
281 Issue a receive request to the UDP_IO_PORT.
283 This function is called when upper-layer needs packet from UDP for processing.
284 Only one receive request is acceptable at a time so a common usage model is
285 to invoke this function inside its Callback function when the former packet
288 @param UdpIo The UDP_IO_PORT to receive the packet from.
289 @param CallBack The call back function to execute when the packet
291 @param Context The opaque context passed to Callback
292 @param HeadLen The length of the upper-layer's protocol header
294 @retval EFI_ALREADY_STARTED There is already a pending receive request. Only
295 one receive request is supported at a time.
296 @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.
297 @retval EFI_SUCCESS The receive request is issued successfully.
303 IN UDP_IO_PORT
*UdpIo
,
304 IN UDP_IO_CALLBACK CallBack
,