MdeModulePkg/Include/Library/UdpIoLib.h

   1 /** @file
   2   Ihis library is only intended to be used by 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 from/to 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
  49   UDP access point, and released by user. When sending, the NetBuf is from user,
  50   and 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 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 and they
  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 /// The data structure wraps Udp4 instance and its configuration. It is used by
 113 /// UdpIo Library to do 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 configure process succeeds
 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        To 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 the sent datagram that pass the selection criteria of 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              The select funtion to test whether to cancel this
 178                                     packet or not.
 179   @param[in]  Context               The opaque parameter to the ToCancel.
 180
 181 **/
 182 VOID
 183 EFIAPI
 184 UdpIoCancelDgrams (
 185   IN UDP_IO_PORT            *UdpIo,
 186   IN EFI_STATUS             IoStatus,
 187   IN UDP_IO_TO_CANCEL       ToCancel,        OPTIONAL
 188   IN VOID                   *Context
 189   );
 190
 191 /**
 192   Create a UDP_IO_PORT to access the UDP service. It will create and configure
 193   a UDP child.
 194
 195   The function will locate the UDP service binding prototype on the Controller
 196   parameter and use it to create a UDP child (aka Udp instance). Then the UDP
 197   child will be configured by calling Configure function prototype. Any failures
 198   in creating or configure the UDP child will lead to the failure of UDP_IO_PORT
 199   creation.
 200
 201   @param[in]  Controller            The controller that has the UDP service binding.
 202                                     protocol installed.
 203   @param[in]  Image                 The image handle for the driver.
 204   @param[in]  Configure             The function to configure the created UDP child.
 205   @param[in]  Context               The opaque parameter for the Configure funtion.
 206
 207   @return Newly-created UDP_IO_PORT or NULL if failed.
 208
 209 **/
 210 UDP_IO_PORT *
 211 EFIAPI
 212 UdpIoCreatePort (
 213   IN  EFI_HANDLE            Controller,
 214   IN  EFI_HANDLE            Image,
 215   IN  UDP_IO_CONFIG         Configure,
 216   IN  VOID                  *Context
 217   );
 218
 219 /**
 220   Free the UDP_IO_PORT and all its related resources.
 221
 222   The function will cancel all sent datagram and receive request.
 223
 224   @param[in]  UdpIo                 The UDP_IO_PORT to free.
 225
 226   @retval EFI_SUCCESS           The UDP_IO_PORT is freed.
 227
 228 **/
 229 EFI_STATUS
 230 EFIAPI
 231 UdpIoFreePort (
 232   IN  UDP_IO_PORT           *UdpIo
 233   );
 234
 235 /**
 236   Clean up the UDP_IO_PORT without freeing it. The function is called when
 237   user wants to re-use the UDP_IO_PORT later.
 238
 239   It will release all the transmitted datagrams and receive request. It will
 240   also configure NULL for the UDP instance.
 241
 242   @param[in]  UdpIo                 The UDP_IO_PORT to clean up.
 243
 244 **/
 245 VOID
 246 EFIAPI
 247 UdpIoCleanPort (
 248   IN  UDP_IO_PORT           *UdpIo
 249   );
 250
 251 /**
 252   Send a packet through the UDP_IO_PORT.
 253
 254   The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called
 255   when the packet is sent. The optional parameter EndPoint overrides the default
 256   address pair if specified.
 257
 258   @param[in]  UdpIo                 The UDP_IO_PORT to send the packet through.
 259   @param[in]  Packet                The packet to send.
 260   @param[in]  EndPoint              The local and remote access point. Override the
 261                                     default address pair set during configuration.
 262   @param[in]  Gateway               The gateway to use.
 263   @param[in]  CallBack              The function being called when packet is
 264                                     transmitted or failed.
 265   @param[in]  Context               The opaque parameter passed to CallBack.
 266
 267   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet.
 268   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for
 269                                 transmission.
 270
 271 **/
 272 EFI_STATUS
 273 EFIAPI
 274 UdpIoSendDatagram (
 275   IN  UDP_IO_PORT           *UdpIo,
 276   IN  NET_BUF               *Packet,
 277   IN  UDP_POINTS            *EndPoint, OPTIONAL
 278   IN  IP4_ADDR              Gateway,
 279   IN  UDP_IO_CALLBACK       CallBack,
 280   IN  VOID                  *Context
 281   );
 282
 283 /**
 284   Cancel a single sent datagram.
 285
 286   @param[in]  UdpIo                 The UDP_IO_PORT to cancel the packet from
 287   @param[in]  Packet                The packet to cancel
 288
 289 **/
 290 VOID
 291 EFIAPI
 292 UdpIoCancelSentDatagram (
 293   IN  UDP_IO_PORT           *UdpIo,
 294   IN  NET_BUF               *Packet
 295   );
 296
 297 /**
 298   Issue a receive request to the UDP_IO_PORT.
 299
 300   This function is called when upper-layer needs packet from UDP for processing.
 301   Only one receive request is acceptable at a time so a common usage model is
 302   to invoke this function inside its Callback function when the former packet
 303   is processed.
 304
 305   @param[in]  UdpIo                 The UDP_IO_PORT to receive the packet from.
 306   @param[in]  CallBack              The call back function to execute when the packet
 307                                     is received.
 308   @param[in]  Context               The opaque context passed to Callback.
 309   @param[in] HeadLen                The length of the upper-layer's protocol header.
 310
 311   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only
 312                                 one receive request is supported at a time.
 313   @retval EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.
 314   @retval EFI_SUCCESS           The receive request is issued successfully.
 315
 316 **/
 317 EFI_STATUS
 318 EFIAPI
 319 UdpIoRecvDatagram (
 320   IN  UDP_IO_PORT           *UdpIo,
 321   IN  UDP_IO_CALLBACK       CallBack,
 322   IN  VOID                  *Context,
 323   IN  UINT32                HeadLen
 324   );
 325 #endif