MdeModulePkg/Include/Library/UdpIoLib.h

   1 /** @file
   2   This library is used to share code between UEFI network stack modules.
   3   It provides the helper routines to access UDP service. It is used by both DHCP and MTFTP.
   4
   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
  10
  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.
  13
  14 **/
  15
  16 #ifndef _UDP4IO_H_
  17 #define _UDP4IO_H_
  18
  19 #include <Protocol/Udp4.h>
  20
  21 #include <Library/NetLib.h>
  22
  23 typedef struct _UDP_IO_PORT UDP_IO_PORT;
  24
  25 ///
  26 /// Signatures used by UdpIo Library.
  27 ///
  28 typedef enum {
  29   UDP_IO_RX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'R'),
  30   UDP_IO_TX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'T'),
  31   UDP_IO_SIGNATURE    = SIGNATURE_32 ('U', 'D', 'P', 'I')
  32 } UDP_IO_SIGNATURE_TYPE;
  33
  34 ///
  35 /// The Udp4 address pair.
  36 ///
  37 typedef struct {
  38   IP4_ADDR                  LocalAddr;
  39   UINT16                    LocalPort;
  40   IP4_ADDR                  RemoteAddr;
  41   UINT16                    RemotePort;
  42 } UDP_POINTS;
  43
  44 /**
  45   Prototype called when receiving or sending packets to or from a UDP point.
  46
  47   This prototype is used by both receive and sending when calling
  48   UdpIoRecvDatagram() or UdpIoSendDatagram(). When receiving, Netbuf is allocated by the
  49   UDP access point and released by the user. When sending, the user allocates the the NetBuf, which is then
  50   provided to the callback as a reference.
  51
  52   @param[in] Packet       Packet received or sent
  53   @param[in] Points       The Udp4 address pair corresponds to the Udp4 IO
  54   @param[in] IoStatus     Packet receiving or sending status
  55   @param[in] Context      User-defined data when calling UdpIoRecvDatagram() or
  56                           UdpIoSendDatagram()
  57 **/
  58 typedef
  59 VOID
  60 (*UDP_IO_CALLBACK) (
  61   IN NET_BUF                *Packet,
  62   IN UDP_POINTS             *Points,
  63   IN EFI_STATUS             IoStatus,
  64   IN VOID                   *Context
  65   );
  66
  67 ///
  68 /// This structure is used internally by the UdpIo Library.
  69 ///
  70 /// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,
  71 /// the CallBack will be called. Only one receive request is sent to UDP at a
  72 /// time. HeadLen gives the length of the application's header. UDP_IO will
  73 /// make the application's header continuous before delivering up.
  74 ///
  75 typedef struct {
  76   UINT32                    Signature;
  77   UDP_IO_PORT               *UdpIo;
  78
  79   UDP_IO_CALLBACK           CallBack;
  80   VOID                      *Context;
  81
  82   UINT32                    HeadLen;
  83   EFI_UDP4_COMPLETION_TOKEN UdpToken;
  84 } UDP_RX_TOKEN;
  85
  86 ///
  87 /// This structure is used internally by UdpIo Library.
  88 ///
  89 /// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,
  90 /// the CallBack will be called. There can be several transmit requests. All transmit requests
  91 /// are linked in a list.
  92 ///
  93 typedef struct {
  94   UINT32                    Signature;
  95   LIST_ENTRY                Link;
  96   UDP_IO_PORT               *UdpIo;
  97
  98   UDP_IO_CALLBACK           CallBack;
  99   NET_BUF                   *Packet;
 100   VOID                      *Context;
 101
 102   EFI_UDP4_SESSION_DATA     UdpSession;
 103   EFI_IPv4_ADDRESS          Gateway;
 104
 105   EFI_UDP4_COMPLETION_TOKEN UdpToken;
 106   EFI_UDP4_TRANSMIT_DATA    UdpTxData;
 107 } UDP_TX_TOKEN;
 108
 109 ///
 110 /// Type defined as UDP_IO_PORT.
 111 ///
 112 /// This data structure wraps the Udp4 instance and configuration.
 113 /// UdpIo Library uses this structure for all Udp4 operations.
 114 ///
 115 struct _UDP_IO_PORT {
 116   UINT32                    Signature;
 117   LIST_ENTRY                Link;
 118   INTN                      RefCnt;
 119
 120   //
 121   // Handle used to create/destory UDP child
 122   //
 123   EFI_HANDLE                Controller;
 124   EFI_HANDLE                Image;
 125   EFI_HANDLE                UdpHandle;
 126
 127   EFI_UDP4_PROTOCOL         *Udp;           ///< The wrapped Udp4 instance.
 128   EFI_UDP4_CONFIG_DATA      UdpConfig;
 129   EFI_SIMPLE_NETWORK_MODE   SnpMode;
 130
 131   LIST_ENTRY                SentDatagram;   ///< A list of UDP_TX_TOKEN.
 132   UDP_RX_TOKEN              *RecvRequest;
 133 };
 134
 135 /**
 136   Prototype called when UdpIo Library configures a Udp4 instance.
 137
 138   The prototype is set and called when creating a UDP_IO_PORT in UdpIoCreatePort().
 139
 140   @param[in] UdpIo         The UDP_IO_PORT to configure
 141   @param[in] Context       User-defined data when calling UdpIoCreatePort()
 142
 143   @retval EFI_SUCCESS  The configuration succeeded
 144   @retval Others       The UDP_IO_PORT fails to configure indicating
 145                        UdpIoCreatePort() should fail
 146 **/
 147 typedef
 148 EFI_STATUS
 149 (*UDP_IO_CONFIG) (
 150   IN UDP_IO_PORT            *UdpIo,
 151   IN VOID                   *Context
 152   );
 153
 154 /**
 155   The select function to decide whether to cancel the UDP_TX_TOKEN.
 156
 157   @param[in] Token        The UDP_TX_TOKEN to decide whether to cancel
 158   @param[in] Context      User-defined data in UdpIoCancelDgrams()
 159
 160   @retval TRUE        Cancel the UDP_TX_TOKEN
 161   @retval FALSE       Do not cancel this UDP_TX_TOKEN
 162
 163 **/
 164 typedef
 165 BOOLEAN
 166 (*UDP_IO_TO_CANCEL) (
 167   IN UDP_TX_TOKEN           *Token,
 168   IN VOID                   *Context
 169   );
 170
 171 /**
 172   Cancel all sent datagrams selected by the parameter ToCancel.
 173   If ToCancel is NULL, all the datagrams are cancelled.
 174
 175   @param[in]  UdpIo                 The UDP_IO_PORT to cancel packet.
 176   @param[in]  IoStatus              The IoStatus to return to the packet owners.
 177   @param[in]  ToCancel              Sets the criteria for canceling a packet.
 178   @param[in]  Context               The opaque parameter to the ToCancel.
 179
 180 **/
 181 VOID
 182 EFIAPI
 183 UdpIoCancelDgrams (
 184   IN UDP_IO_PORT            *UdpIo,
 185   IN EFI_STATUS             IoStatus,
 186   IN UDP_IO_TO_CANCEL       ToCancel,        OPTIONAL
 187   IN VOID                   *Context
 188   );
 189
 190 /**
 191   Creates a UDP_IO_PORT to access the UDP service. It creates and configures
 192   a UDP child.
 193
 194   This function:
 195   # locates the UDP service binding prototype on the Controller parameter
 196   # uses the UDP service binding prototype to create a UDP child (also known as a UDP instance)
 197   # configures the UDP child by calling Configure function prototype.
 198   Any failures in creating or configuring the UDP child return NULL for failure.
 199
 200   @param[in]  Controller            The controller that has the UDP service binding.
 201                                     protocol installed.
 202   @param[in]  Image                 The image handle for the driver.
 203   @param[in]  Configure             The function to configure the created UDP child.
 204   @param[in]  Context               The opaque parameter for the Configure funtion.
 205
 206   @return Newly-created UDP_IO_PORT or NULL if failed.
 207
 208 **/
 209 UDP_IO_PORT *
 210 EFIAPI
 211 UdpIoCreatePort (
 212   IN  EFI_HANDLE            Controller,
 213   IN  EFI_HANDLE            Image,
 214   IN  UDP_IO_CONFIG         Configure,
 215   IN  VOID                  *Context
 216   );
 217
 218 /**
 219   Free the UDP_IO_PORT and all its related resources.
 220
 221   The function cancels all sent datagrams and receive requests.
 222
 223   @param[in]  UdpIo                 The UDP_IO_PORT to free.
 224
 225   @retval EFI_SUCCESS           The UDP_IO_PORT is freed.
 226
 227 **/
 228 EFI_STATUS
 229 EFIAPI
 230 UdpIoFreePort (
 231   IN  UDP_IO_PORT           *UdpIo
 232   );
 233
 234 /**
 235   Cleans up the UDP_IO_PORT without freeing it. Call this function
 236   if you intend to later re-use the UDP_IO_PORT.
 237
 238   This function releases all transmitted datagrams and receive requests and configures NULL for the UDP instance.
 239
 240   @param[in]  UdpIo                 The UDP_IO_PORT to clean up.
 241
 242 **/
 243 VOID
 244 EFIAPI
 245 UdpIoCleanPort (
 246   IN  UDP_IO_PORT           *UdpIo
 247   );
 248
 249 /**
 250   Sends a packet through the UDP_IO_PORT.
 251
 252   The packet will be wrapped in UDP_TX_TOKEN. The function specific in the CallBack parameter will be called
 253   when the packet is sent. If specified, the optional parameter EndPoint overrides the default
 254   address pair.
 255
 256   @param[in]  UdpIo                 The UDP_IO_PORT to send the packet through.
 257   @param[in]  Packet                The packet to send.
 258   @param[in]  EndPoint              The local and remote access point. Overrides the
 259                                     default address pair set during configuration.
 260   @param[in]  Gateway               The gateway to use.
 261   @param[in]  CallBack              The function being called when packet is
 262                                     transmitted or failed.
 263   @param[in]  Context               The opaque parameter passed to CallBack.
 264
 265   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet.
 266   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for
 267                                 transmission.
 268
 269 **/
 270 EFI_STATUS
 271 EFIAPI
 272 UdpIoSendDatagram (
 273   IN  UDP_IO_PORT           *UdpIo,
 274   IN  NET_BUF               *Packet,
 275   IN  UDP_POINTS            *EndPoint, OPTIONAL
 276   IN  IP4_ADDR              Gateway,
 277   IN  UDP_IO_CALLBACK       CallBack,
 278   IN  VOID                  *Context
 279   );
 280
 281 /**
 282   Cancel a single sent datagram.
 283
 284   @param[in]  UdpIo                 The UDP_IO_PORT from which to cancel the packet
 285   @param[in]  Packet                The packet to cancel
 286
 287 **/
 288 VOID
 289 EFIAPI
 290 UdpIoCancelSentDatagram (
 291   IN  UDP_IO_PORT           *UdpIo,
 292   IN  NET_BUF               *Packet
 293   );
 294
 295 /**
 296   Issue a receive request to the UDP_IO_PORT.
 297
 298   This function is called when upper-layer needs packet from UDP for processing.
 299   Only one receive request is acceptable at a time. Therefore, one common usage model is
 300   to invoke this function inside its Callback function when the former packet
 301   is processed.
 302
 303   @param[in]  UdpIo                 The UDP_IO_PORT to receive the packet from.
 304   @param[in]  CallBack              The call back function to execute when the packet
 305                                     is received.
 306   @param[in]  Context               The opaque context passed to Callback.
 307   @param[in] HeadLen                The length of the upper-layer's protocol header.
 308
 309   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only
 310                                 one receive request is supported at a time.
 311   @retval EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 312   @retval EFI_SUCCESS           The receive request is issued successfully.
 313
 314 **/
 315 EFI_STATUS
 316 EFIAPI
 317 UdpIoRecvDatagram (
 318   IN  UDP_IO_PORT           *UdpIo,
 319   IN  UDP_IO_CALLBACK       CallBack,
 320   IN  VOID                  *Context,
 321   IN  UINT32                HeadLen
 322   );
 323 #endif