MdeModulePkg/Include/Library/UdpIoLib.h

   1 /** @file
   2   The helper routines to access UDP service. It is used by both
   3   DHCP and MTFTP.
   4
   5 Copyright (c) 2006 - 2008, Intel Corporation
   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
   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/UdpIoLib.h>
  22 #include <Library/NetLib.h>
  23
  24 typedef struct _UDP_IO_PORT UDP_IO_PORT;
  25
  26 typedef enum {
  27   UDP_IO_RX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'R'),
  28   UDP_IO_TX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'T'),
  29   UDP_IO_SIGNATURE    = SIGNATURE_32 ('U', 'D', 'P', 'I')
  30 } UDP_IO_SIGNATURE_TYPE;
  31
  32 typedef struct {
  33   IP4_ADDR                  LocalAddr;
  34   UINT16                    LocalPort;
  35   IP4_ADDR                  RemoteAddr;
  36   UINT16                    RemotePort;
  37 } UDP_POINTS;
  38
  39 //
  40 // This prototype is used by both receive and transmission.
  41 // When receiving Netbuf is allocated by UDP access point, and
  42 // released by user. When transmitting, the NetBuf is from user,
  43 // and provided to the callback as a reference.
  44 //
  45 typedef
  46 VOID
  47 (*UDP_IO_CALLBACK) (
  48   IN NET_BUF                *Packet,
  49   IN UDP_POINTS             *Points,
  50   IN EFI_STATUS             IoStatus,
  51   IN VOID                   *Context
  52   );
  53
  54 //
  55 // Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,
  56 // the CallBack will be called. Only one receive request is send to UDP.
  57 // HeadLen gives the length of the application's header. UDP_IO will
  58 // make the application's header continous before delivery up.
  59 //
  60 typedef struct {
  61   UINT32                    Signature;
  62   UDP_IO_PORT               *UdpIo;
  63
  64   UDP_IO_CALLBACK           CallBack;
  65   VOID                      *Context;
  66
  67   UINT32                    HeadLen;
  68   EFI_UDP4_COMPLETION_TOKEN UdpToken;
  69 } UDP_RX_TOKEN;
  70
  71 //
  72 // Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,
  73 // the CallBack will be called. There can be several transmit requests.
  74 //
  75 typedef struct {
  76   UINT32                    Signature;
  77   LIST_ENTRY                Link;
  78   UDP_IO_PORT               *UdpIo;
  79
  80   UDP_IO_CALLBACK           CallBack;
  81   NET_BUF                   *Packet;
  82   VOID                      *Context;
  83
  84   EFI_UDP4_SESSION_DATA     UdpSession;
  85   EFI_IPv4_ADDRESS          Gateway;
  86
  87   EFI_UDP4_COMPLETION_TOKEN UdpToken;
  88   EFI_UDP4_TRANSMIT_DATA    UdpTxData;
  89 } UDP_TX_TOKEN;
  90
  91 struct _UDP_IO_PORT {
  92   UINT32                    Signature;
  93   LIST_ENTRY                Link;
  94   INTN                      RefCnt;
  95
  96   //
  97   // Handle used to create/destory UDP child
  98   //
  99   EFI_HANDLE                Controller;
 100   EFI_HANDLE                Image;
 101   EFI_HANDLE                UdpHandle;
 102
 103   EFI_UDP4_PROTOCOL         *Udp;
 104   EFI_UDP4_CONFIG_DATA      UdpConfig;
 105   EFI_SIMPLE_NETWORK_MODE   SnpMode;
 106
 107   LIST_ENTRY                SentDatagram;
 108   UDP_RX_TOKEN              *RecvRequest;
 109 };
 110
 111 typedef
 112 EFI_STATUS
 113 (*UDP_IO_CONFIG) (
 114   IN UDP_IO_PORT            *UdpIo,
 115   IN VOID                   *Context
 116   );
 117
 118 typedef
 119 BOOLEAN
 120 (*UDP_IO_TO_CANCEL) (
 121   IN UDP_TX_TOKEN           *Token,
 122   IN VOID                   *Context
 123   );
 124
 125 /**
 126   Create a UDP IO port to access the UDP service. It will
 127   create and configure a UDP child.
 128
 129   @param  Controller            The controller that has the UDP service binding
 130                                 protocol installed.
 131   @param  ImageHandle           The image handle for the driver.
 132   @param  Configure             The function to configure the created UDP child
 133   @param  Context               The opaque parameter for the Configure funtion.
 134
 135   @return A point to just created UDP IO port or NULL if failed.
 136
 137 **/
 138 UDP_IO_PORT *
 139 EFIAPI
 140 UdpIoCreatePort (
 141   IN  EFI_HANDLE            Controller,
 142   IN  EFI_HANDLE            ImageHandle,
 143   IN  UDP_IO_CONFIG         Configure,
 144   IN  VOID                  *Context
 145   );
 146
 147 /**
 148   Free the UDP IO port and all its related resources including
 149   all the transmitted packet.
 150
 151   @param  UdpIo                 The UDP IO port to free.
 152
 153   @retval EFI_SUCCESS           The UDP IO port is freed.
 154
 155 **/
 156 EFI_STATUS
 157 EFIAPI
 158 UdpIoFreePort (
 159   IN  UDP_IO_PORT           *UdpIo
 160   );
 161
 162 /**
 163   Clean up the UDP IO port. It will release all the transmitted
 164   datagrams and receive request. It will also configure NULL the
 165   UDP child.
 166
 167   @param  UdpIo                 UDP IO port to clean up.
 168
 169   @return None
 170
 171 **/
 172 VOID
 173 EFIAPI
 174 UdpIoCleanPort (
 175   IN  UDP_IO_PORT           *UdpIo
 176   );
 177
 178 /**
 179   Send a packet through the UDP IO port.
 180
 181   @param  UdpIo                 The UDP IO Port to send the packet through
 182   @param  Packet                The packet to send
 183   @param  EndPoint              The local and remote access point
 184   @param  Gateway               The gateway to use
 185   @param  CallBack              The call back function to call when packet is
 186                                 transmitted or failed.
 187   @param  Context               The opque parameter to the CallBack
 188
 189   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet
 190   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for
 191                                 transmission.
 192
 193 **/
 194 EFI_STATUS
 195 EFIAPI
 196 UdpIoSendDatagram (
 197   IN  UDP_IO_PORT           *UdpIo,
 198   IN  NET_BUF               *Packet,
 199   IN  UDP_POINTS            *EndPoint, OPTIONAL
 200   IN  IP4_ADDR              Gateway,
 201   IN  UDP_IO_CALLBACK       CallBack,
 202   IN  VOID                  *Context
 203   );
 204
 205 /**
 206   Cancel a single sent datagram.
 207
 208   @param  UdpIo                 The UDP IO port to cancel the packet from
 209   @param  Packet                The packet to cancel
 210
 211   @return None
 212
 213 **/
 214 VOID
 215 EFIAPI
 216 UdpIoCancelSentDatagram (
 217   IN  UDP_IO_PORT           *UdpIo,
 218   IN  NET_BUF               *Packet
 219   );
 220
 221 /**
 222   Issue a receive request to the UDP IO port.
 223
 224   @param  UdpIo                 The UDP IO port to recieve the packet from.
 225   @param  CallBack              The call back function to execute when receive
 226                                 finished.
 227   @param  Context               The opque context to the call back
 228   @param  HeadLen               The lenght of the application's header
 229
 230   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only
 231                                 one receive request is supported.
 232   @retval EFI_OUT_OF_RESOURCES  Failed to allocate some resource.
 233   @retval EFI_SUCCESS           The receive request is issued successfully.
 234
 235 **/
 236 EFI_STATUS
 237 EFIAPI
 238 UdpIoRecvDatagram (
 239   IN  UDP_IO_PORT           *UdpIo,
 240   IN  UDP_IO_CALLBACK       CallBack,
 241   IN  VOID                  *Context,
 242   IN  UINT32                HeadLen
 243   );
 244 #endif