MdePkg/Include/Protocol/Udp6.h

   1 /** @file
   2   The EFI UDPv6 (User Datagram Protocol version 6) Protocol Definition, which is built upon
   3   the EFI IPv6 Protocol and provides simple packet-oriented services to transmit and receive
   4   UDP packets.
   5
   6   Copyright (c) 2008 - 2014, Intel Corporation. All rights reserved.<BR>
   7   This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15   @par Revision Reference:
  16   This Protocol is introduced in UEFI Specification 2.2
  17
  18 **/
  19
  20 #ifndef __EFI_UDP6_PROTOCOL_H__
  21 #define __EFI_UDP6_PROTOCOL_H__
  22
  23 #include <Protocol/Ip6.h>
  24
  25 #define EFI_UDP6_SERVICE_BINDING_PROTOCOL_GUID \
  26   { \
  27     0x66ed4721, 0x3c98, 0x4d3e, {0x81, 0xe3, 0xd0, 0x3d, 0xd3, 0x9a, 0x72, 0x54 } \
  28   }
  29
  30 #define EFI_UDP6_PROTOCOL_GUID \
  31   { \
  32     0x4f948815, 0xb4b9, 0x43cb, {0x8a, 0x33, 0x90, 0xe0, 0x60, 0xb3, 0x49, 0x55 } \
  33   }
  34
  35 ///
  36 /// EFI_UDP6_SERVICE_POINT is deprecated in the UEFI 2.4B and should not be used any more.
  37 /// The definition in here is only present to provide backwards compatability.
  38 ///
  39 typedef struct {
  40   ///
  41   /// The EFI UDPv6 Protocol instance handle that is using this address/port pair.
  42   ///
  43   EFI_HANDLE          InstanceHandle;
  44   ///
  45   /// The IPv6 address to which this instance of the EFI UDPv6 Protocol is bound.
  46   /// Set to 0::/128, if this instance is used to listen all packets from any
  47   /// source address.
  48   ///
  49   EFI_IPv6_ADDRESS    LocalAddress;
  50   ///
  51   /// The port number in host byte order on which the service is listening.
  52   ///
  53   UINT16              LocalPort;
  54   ///
  55   /// The IPv6 address of the remote host. May be 0::/128 if it is not connected
  56   /// to any remote host or connected with more than one remote host.
  57   ///
  58   EFI_IPv6_ADDRESS    RemoteAddress;
  59   ///
  60   /// The port number in host byte order on which the remote host is
  61   /// listening. Maybe zero if it is not connected to any remote host.
  62   ///
  63   UINT16              RemotePort;
  64 } EFI_UDP6_SERVICE_POINT;
  65
  66 ///
  67 /// EFI_UDP6_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more.
  68 /// The definition in here is only present to provide backwards compatability.
  69 ///
  70 typedef struct {
  71   ///
  72   /// The handle of the driver that creates this entry.
  73   ///
  74   EFI_HANDLE              DriverHandle;
  75   ///
  76   /// The number of address/port pairs that follow this data structure.
  77   ///
  78   UINT32                  ServiceCount;
  79   ///
  80   /// List of address/port pairs that are currently in use.
  81   ///
  82   EFI_UDP6_SERVICE_POINT  Services[1];
  83 } EFI_UDP6_VARIABLE_DATA;
  84
  85 typedef struct _EFI_UDP6_PROTOCOL EFI_UDP6_PROTOCOL;
  86
  87 ///
  88 /// EFI_UDP6_FRAGMENT_DATA allows multiple receive or transmit buffers to be specified.
  89 /// The purpose of this structure is to avoid copying the same packet multiple times.
  90 ///
  91 typedef struct {
  92   UINT32        FragmentLength;  ///< Length of the fragment data buffer.
  93   VOID          *FragmentBuffer; ///< Pointer to the fragment data buffer.
  94 } EFI_UDP6_FRAGMENT_DATA;
  95
  96 ///
  97 /// The EFI_UDP6_SESSION_DATA is used to retrieve the settings when receiving packets or
  98 /// to override the existing settings (only DestinationAddress and DestinationPort can
  99 /// be overridden) of this EFI UDPv6 Protocol instance when sending packets.
 100 ///
 101 typedef struct {
 102   ///
 103   /// Address from which this packet is sent. This field should not be used when
 104   /// sending packets.
 105   ///
 106   EFI_IPv6_ADDRESS   SourceAddress;
 107   ///
 108   /// Port from which this packet is sent. It is in host byte order. This field should
 109   /// not be used when sending packets.
 110   ///
 111   UINT16             SourcePort;
 112   ///
 113   /// Address to which this packet is sent. When sending packet, it'll be ignored
 114   /// if it is zero.
 115   ///
 116   EFI_IPv6_ADDRESS   DestinationAddress;
 117   ///
 118   /// Port to which this packet is sent. When sending packet, it'll be
 119   /// ignored if it is zero.
 120   ///
 121   UINT16             DestinationPort;
 122 } EFI_UDP6_SESSION_DATA;
 123
 124 typedef struct {
 125   ///
 126   /// Set to TRUE to accept UDP packets that are sent to any address.
 127   ///
 128   BOOLEAN           AcceptPromiscuous;
 129   ///
 130   /// Set to TRUE to accept UDP packets that are sent to any port.
 131   ///
 132   BOOLEAN           AcceptAnyPort;
 133   ///
 134   /// Set to TRUE to allow this EFI UDPv6 Protocol child instance to open a port number
 135   /// that is already being used by another EFI UDPv6 Protocol child instance.
 136   ///
 137   BOOLEAN           AllowDuplicatePort;
 138   ///
 139   /// TrafficClass field in transmitted IPv6 packets.
 140   ///
 141   UINT8             TrafficClass;
 142   ///
 143   /// HopLimit field in transmitted IPv6 packets.
 144   ///
 145   UINT8             HopLimit;
 146   ///
 147   /// The receive timeout value (number of microseconds) to be associated with each
 148   /// incoming packet. Zero means do not drop incoming packets.
 149   ///
 150   UINT32            ReceiveTimeout;
 151   ///
 152   /// The transmit timeout value (number of microseconds) to be associated with each
 153   /// outgoing packet. Zero means do not drop outgoing packets.
 154   ///
 155   UINT32            TransmitTimeout;
 156   ///
 157   /// The station IP address that will be assigned to this EFI UDPv6 Protocol instance.
 158   /// The EFI UDPv6 and EFI IPv6 Protocol drivers will only deliver incoming packets
 159   /// whose destination matches this IP address exactly. Address 0::/128 is also accepted
 160   /// as a special case. Under this situation, underlying IPv6 driver is responsible for
 161   /// binding a source address to this EFI IPv6 protocol instance according to source
 162   /// address selection algorithm. Only incoming packet from the selected source address
 163   /// is delivered. This field can be set and changed only when the EFI IPv6 driver is
 164   /// transitioning from the stopped to the started states. If no address is available
 165   /// for selecting, the EFI IPv6 Protocol driver will use EFI_IP6_CONFIG_PROTOCOL to
 166   /// retrieve the IPv6 address.
 167   EFI_IPv6_ADDRESS  StationAddress;
 168   ///
 169   /// The port number to which this EFI UDPv6 Protocol instance is bound. If a client
 170   /// of the EFI UDPv6 Protocol does not care about the port number, set StationPort
 171   /// to zero. The EFI UDPv6 Protocol driver will assign a random port number to transmitted
 172   /// UDP packets. Ignored it if AcceptAnyPort is TRUE.
 173   ///
 174   UINT16            StationPort;
 175   ///
 176   /// The IP address of remote host to which this EFI UDPv6 Protocol instance is connecting.
 177   /// If RemoteAddress is not 0::/128, this EFI UDPv6 Protocol instance will be connected to
 178   /// RemoteAddress; i.e., outgoing packets of this EFI UDPv6 Protocol instance will be sent
 179   /// to this address by default and only incoming packets from this address will be delivered
 180   /// to client. Ignored for incoming filtering if AcceptPromiscuous is TRUE.
 181   EFI_IPv6_ADDRESS  RemoteAddress;
 182   ///
 183   /// The port number of the remote host to which this EFI UDPv6 Protocol instance is connecting.
 184   /// If it is not zero, outgoing packets of this EFI UDPv6 Protocol instance will be sent to
 185   /// this port number by default and only incoming packets from this port will be delivered
 186   /// to client. Ignored if RemoteAddress is 0::/128 and ignored for incoming filtering if
 187   /// AcceptPromiscuous is TRUE.
 188   UINT16            RemotePort;
 189 } EFI_UDP6_CONFIG_DATA;
 190
 191 ///
 192 /// The EFI UDPv6 Protocol client must fill this data structure before sending a packet.
 193 /// The packet may contain multiple buffers that may be not in a continuous memory location.
 194 ///
 195 typedef struct {
 196   ///
 197   /// If not NULL, the data that is used to override the transmitting settings.Only the two
 198   /// filed UdpSessionData.DestinationAddress and UdpSessionData.DestionPort can be used as
 199   /// the transmitting setting filed.
 200   ///
 201   EFI_UDP6_SESSION_DATA     *UdpSessionData;
 202   ///
 203   /// Sum of the fragment data length. Must not exceed the maximum UDP packet size.
 204   ///
 205   UINT32                    DataLength;
 206   ///
 207   /// Number of fragments.
 208   ///
 209   UINT32                    FragmentCount;
 210   ///
 211   /// Array of fragment descriptors.
 212   ///
 213   EFI_UDP6_FRAGMENT_DATA    FragmentTable[1];
 214 } EFI_UDP6_TRANSMIT_DATA;
 215
 216 ///
 217 /// EFI_UDP6_RECEIVE_DATA is filled by the EFI UDPv6 Protocol driver when this EFI UDPv6
 218 /// Protocol instance receives an incoming packet. If there is a waiting token for incoming
 219 /// packets, the CompletionToken.Packet.RxData field is updated to this incoming packet and
 220 /// the CompletionToken.Event is signaled. The EFI UDPv6 Protocol client must signal the
 221 /// RecycleSignal after processing the packet.
 222 /// FragmentTable could contain multiple buffers that are not in the continuous memory locations.
 223 /// The EFI UDPv6 Protocol client might need to combine two or more buffers in FragmentTable to
 224 /// form their own protocol header.
 225 ///
 226 typedef struct {
 227   ///
 228   /// Time when the EFI UDPv6 Protocol accepted the packet.
 229   ///
 230   EFI_TIME                  TimeStamp;
 231   ///
 232   /// Indicates the event to signal when the received data has been processed.
 233   ///
 234   EFI_EVENT                 RecycleSignal;
 235   ///
 236   /// The UDP session data including SourceAddress, SourcePort, DestinationAddress,
 237   /// and DestinationPort.
 238   ///
 239   EFI_UDP6_SESSION_DATA     UdpSession;
 240   ///
 241   /// The sum of the fragment data length.
 242   ///
 243   UINT32                    DataLength;
 244   ///
 245   /// Number of fragments. Maybe zero.
 246   ///
 247   UINT32                    FragmentCount;
 248   ///
 249   /// Array of fragment descriptors. Maybe zero.
 250   ///
 251   EFI_UDP6_FRAGMENT_DATA    FragmentTable[1];
 252 } EFI_UDP6_RECEIVE_DATA;
 253
 254 ///
 255 /// The EFI_UDP6_COMPLETION_TOKEN structures are used for both transmit and receive operations.
 256 /// When used for transmitting, the Event and TxData fields must be filled in by the EFI UDPv6
 257 /// Protocol client. After the transmit operation completes, the Status field is updated by the
 258 /// EFI UDPv6 Protocol and the Event is signaled.
 259 /// When used for receiving, only the Event field must be filled in by the EFI UDPv6 Protocol
 260 /// client. After a packet is received, RxData and Status are filled in by the EFI UDPv6 Protocol
 261 /// and the Event is signaled.
 262 ///
 263 typedef struct {
 264   ///
 265   /// This Event will be signaled after the Status field is updated by the EFI UDPv6 Protocol
 266   /// driver. The type of Event must be EVT_NOTIFY_SIGNAL.
 267   ///
 268   EFI_EVENT                             Event;
 269   ///
 270   /// Will be set to one of the following values:
 271   ///   - EFI_SUCCESS: The receive or transmit operation completed successfully.
 272   ///   - EFI_ABORTED: The receive or transmit was aborted.
 273   ///   - EFI_TIMEOUT: The transmit timeout expired.
 274   ///   - EFI_NETWORK_UNREACHABLE: The destination network is unreachable. RxData is set to
 275   ///     NULL in this situation.
 276   ///   - EFI_HOST_UNREACHABLE: The destination host is unreachable. RxData is set to NULL in
 277   ///     this situation.
 278   ///   - EFI_PROTOCOL_UNREACHABLE: The UDP protocol is unsupported in the remote system.
 279   ///     RxData is set to NULL in this situation.
 280   ///   - EFI_PORT_UNREACHABLE: No service is listening on the remote port. RxData is set to
 281   ///     NULL in this situation.
 282   ///   - EFI_ICMP_ERROR: Some other Internet Control Message Protocol (ICMP) error report was
 283   ///     received. For example, packets are being sent too fast for the destination to receive them
 284   ///     and the destination sent an ICMP source quench report. RxData is set to NULL in this situation.
 285   ///   - EFI_DEVICE_ERROR: An unexpected system or network error occurred.
 286   ///   - EFI_SECURITY_VIOLATION: The transmit or receive was failed because of IPsec policy check.
 287   ///   - EFI_NO_MEDIA: There was a media error.
 288   ///
 289   EFI_STATUS                            Status;
 290   union {
 291     ///
 292     /// When this token is used for receiving, RxData is a pointer to EFI_UDP6_RECEIVE_DATA.
 293     ///
 294     EFI_UDP6_RECEIVE_DATA               *RxData;
 295     ///
 296     /// When this token is used for transmitting, TxData is a pointer to EFI_UDP6_TRANSMIT_DATA.
 297     ///
 298     EFI_UDP6_TRANSMIT_DATA              *TxData;
 299   } Packet;
 300 } EFI_UDP6_COMPLETION_TOKEN;
 301
 302 /**
 303   Read the current operational settings.
 304
 305   The GetModeData() function copies the current operational settings of this EFI UDPv6 Protocol
 306   instance into user-supplied buffers. This function is used optionally to retrieve the operational
 307   mode data of underlying networks or drivers.
 308
 309   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 310   @param[out]  Udp6ConfigData   The buffer in which the current UDP configuration data is returned.
 311   @param[out]  Ip6ModeData      The buffer in which the current EFI IPv6 Protocol mode data is returned.
 312   @param[out]  MnpConfigData    The buffer in which the current managed network configuration data is
 313                                 returned.
 314   @param[out]  SnpModeData      The buffer in which the simple network mode data is returned.
 315
 316   @retval EFI_SUCCESS           The mode data was read.
 317   @retval EFI_NOT_STARTED       When Udp6ConfigData is queried, no configuration data is available
 318                                 because this instance has not been started.
 319   @retval EFI_INVALID_PARAMETER This is NULL.
 320
 321 **/
 322 typedef
 323 EFI_STATUS
 324 (EFIAPI *EFI_UDP6_GET_MODE_DATA)(
 325   IN EFI_UDP6_PROTOCOL                 *This,
 326   OUT EFI_UDP6_CONFIG_DATA             *Udp6ConfigData OPTIONAL,
 327   OUT EFI_IP6_MODE_DATA                *Ip6ModeData    OPTIONAL,
 328   OUT EFI_MANAGED_NETWORK_CONFIG_DATA  *MnpConfigData  OPTIONAL,
 329   OUT EFI_SIMPLE_NETWORK_MODE          *SnpModeData    OPTIONAL
 330 );
 331
 332 /**
 333   Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv6
 334   Protocol.
 335
 336   The Configure() function is used to do the following:
 337   - Initialize and start this instance of the EFI UDPv6 Protocol.
 338   - Change the filtering rules and operational parameters.
 339   - Reset this instance of the EFI UDPv6 Protocol.
 340
 341   Until these parameters are initialized, no network traffic can be sent or received by this instance.
 342   This instance can be also reset by calling Configure() with UdpConfigData set to NULL.
 343   Once reset, the receiving queue and transmitting queue are flushed and no traffic is allowed through
 344   this instance.
 345
 346   With different parameters in UdpConfigData, Configure() can be used to bind this instance to specified
 347   port.
 348
 349   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 350   @param[in]   UdpConfigData    Pointer to the buffer contained the configuration data.
 351
 352   @retval EFI_SUCCESS           The configuration settings were set, changed, or reset successfully.
 353   @retval EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
 354                                 address for this instance, but no source address was available for use.
 355   @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
 356                                 - This is NULL.
 357                                 - UdpConfigData.StationAddress neither zero nor one of the configured IP
 358                                   addresses in the underlying IPv6 driver.
 359                                 - UdpConfigData.RemoteAddress is not a valid unicast IPv6 address if it
 360                                   is not zero.
 361   @retval EFI_ALREADY_STARTED   The EFI UDPv6 Protocol instance is already started/configured and must be
 362                                 stopped/reset before it can be reconfigured. Only TrafficClass, HopLimit,
 363                                 ReceiveTimeout, and TransmitTimeout can be reconfigured without stopping
 364                                 the current instance of the EFI UDPv6 Protocol.
 365   @retval EFI_ACCESS_DENIED     UdpConfigData.AllowDuplicatePort is FALSE and UdpConfigData.StationPort
 366                                 is already used by other instance.
 367   @retval EFI_OUT_OF_RESOURCES  The EFI UDPv6 Protocol driver cannot allocate memory for this EFI UDPv6
 368                                 Protocol instance.
 369   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred and this instance was not
 370                                 opened.
 371
 372 **/
 373 typedef
 374 EFI_STATUS
 375 (EFIAPI *EFI_UDP6_CONFIGURE)(
 376   IN EFI_UDP6_PROTOCOL     *This,
 377   IN EFI_UDP6_CONFIG_DATA  *UdpConfigData OPTIONAL
 378 );
 379
 380 /**
 381   Joins and leaves multicast groups.
 382
 383   The Groups() function is used to join or leave one or more multicast group.
 384   If the JoinFlag is FALSE and the MulticastAddress is NULL, then all currently joined groups are left.
 385
 386   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 387   @param[in]   JoinFlag         Set to TRUE to join a multicast group. Set to FALSE to leave one
 388                                 or all multicast groups.
 389   @param[in]   MulticastAddress Pointer to multicast group address to join or leave.
 390
 391   @retval EFI_SUCCESS           The operation completed successfully.
 392   @retval EFI_NOT_STARTED       The EFI UDPv6 Protocol instance has not been started.
 393   @retval EFI_OUT_OF_RESOURCES  Could not allocate resources to join the group.
 394   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 395                                 - This is NULL.
 396                                 - JoinFlag is TRUE and MulticastAddress is NULL.
 397                                 - JoinFlag is TRUE and *MulticastAddress is not a valid multicast address.
 398   @retval EFI_ALREADY_STARTED   The group address is already in the group table (when JoinFlag is TRUE).
 399   @retval EFI_NOT_FOUND         The group address is not in the group table (when JoinFlag is FALSE).
 400   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 401
 402 **/
 403 typedef
 404 EFI_STATUS
 405 (EFIAPI *EFI_UDP6_GROUPS)(
 406   IN EFI_UDP6_PROTOCOL  *This,
 407   IN BOOLEAN            JoinFlag,
 408   IN EFI_IPv6_ADDRESS   *MulticastAddress OPTIONAL
 409 );
 410
 411 /**
 412   Queues outgoing data packets into the transmit queue.
 413
 414   The Transmit() function places a sending request to this instance of the EFI UDPv6 Protocol,
 415   alongside the transmit data that was filled by the user. Whenever the packet in the token is
 416   sent out or some errors occur, the Token.Event will be signaled and Token.Status is updated.
 417   Providing a proper notification function and context for the event will enable the user to
 418   receive the notification and transmitting status.
 419
 420   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 421   @param[in]   Token            Pointer to the completion token that will be placed into the
 422                                 transmit queue.
 423
 424   @retval EFI_SUCCESS           The data has been queued for transmission.
 425   @retval EFI_NOT_STARTED       This EFI UDPv6 Protocol instance has not been started.
 426   @retval EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
 427                                 address for this instance, but no source address was available
 428                                 for use.
 429   @retval EFI_INVALID_PARAMETER One or more of the following are TRUE:
 430                                 - This is NULL.
 431                                 - Token is NULL.
 432                                 - Token.Event is NULL.
 433                                 - Token.Packet.TxData is NULL.
 434                                 - Token.Packet.TxData.FragmentCount is zero.
 435                                 - Token.Packet.TxData.DataLength is not equal to the sum of fragment
 436                                   lengths.
 437                                 - One or more of the Token.Packet.TxData.FragmentTable[].FragmentLength
 438                                   fields is zero.
 439                                 - One or more of the Token.Packet.TxData.FragmentTable[].FragmentBuffer
 440                                   fields is NULL.
 441                                 - Token.Packet.TxData.UdpSessionData.DestinationAddress is not zero
 442                                   and is not valid unicast Ipv6 address if UdpSessionData is not NULL.
 443                                 - Token.Packet.TxData.UdpSessionData is NULL and this instance's
 444                                   UdpConfigData.RemoteAddress is unspecified.
 445                                 - Token.Packet.TxData.UdpSessionData.DestinationAddress is non-zero
 446                                   when DestinationAddress is configured as non-zero when doing Configure()
 447                                   for this EFI Udp6 protocol instance.
 448                                 - Token.Packet.TxData.UdpSesionData.DestinationAddress is zero when
 449                                   DestinationAddress is unspecified when doing Configure() for this
 450                                   EFI Udp6 protocol instance.
 451   @retval EFI_ACCESS_DENIED     The transmit completion token with the same Token.Event was already
 452                                 in the transmit queue.
 453   @retval EFI_NOT_READY         The completion token could not be queued because the transmit queue
 454                                 is full.
 455   @retval EFI_OUT_OF_RESOURCES  Could not queue the transmit data.
 456   @retval EFI_NOT_FOUND         There is no route to the destination network or address.
 457   @retval EFI_BAD_BUFFER_SIZE   The data length is greater than the maximum UDP packet size.
 458
 459 **/
 460 typedef
 461 EFI_STATUS
 462 (EFIAPI *EFI_UDP6_TRANSMIT)(
 463   IN EFI_UDP6_PROTOCOL          *This,
 464   IN EFI_UDP6_COMPLETION_TOKEN  *Token
 465 );
 466
 467 /**
 468   Places an asynchronous receive request into the receiving queue.
 469
 470   The Receive() function places a completion token into the receive packet queue. This function is
 471   always asynchronous.
 472   The caller must fill in the Token.Event field in the completion token, and this field cannot be
 473   NULL. When the receive operation completes, the EFI UDPv6 Protocol driver updates the Token.Status
 474   and Token.Packet.RxData fields and the Token.Event is signaled.
 475   Providing a proper notification function and context for the event will enable the user to receive
 476   the notification and receiving status. That notification function is guaranteed to not be re-entered.
 477
 478   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 479   @param[in]   Token            Pointer to a token that is associated with the receive data descriptor.
 480
 481   @retval EFI_SUCCESS           The receive completion token was cached.
 482   @retval EFI_NOT_STARTED       This EFI UDPv6 Protocol instance has not been started.
 483   @retval EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
 484                                 address for this instance, but no source address was available
 485                                 for use.
 486   @retval EFI_INVALID_PARAMETER One or more of the following is TRUE:
 487                                 - This is NULL.
 488                                 - Token is NULL.
 489                                 - Token.Event is NULL.
 490   @retval EFI_OUT_OF_RESOURCES  The receive completion token could not be queued due to a lack of system
 491                                 resources (usually memory).
 492   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI UDPv6 Protocol
 493                                 instance has been reset to startup defaults.
 494   @retval EFI_ACCESS_DENIED     A receive completion token with the same Token.Event was already in
 495                                 the receive queue.
 496   @retval EFI_NOT_READY         The receive request could not be queued because the receive queue is full.
 497
 498 **/
 499 typedef
 500 EFI_STATUS
 501 (EFIAPI *EFI_UDP6_RECEIVE)(
 502   IN EFI_UDP6_PROTOCOL          *This,
 503   IN EFI_UDP6_COMPLETION_TOKEN  *Token
 504 );
 505
 506 /**
 507   Aborts an asynchronous transmit or receive request.
 508
 509   The Cancel() function is used to abort a pending transmit or receive request. If the token is in the
 510   transmit or receive request queues, after calling this function, Token.Status will be set to
 511   EFI_ABORTED and then Token.Event will be signaled. If the token is not in one of the queues,
 512   which usually means that the asynchronous operation has completed, this function will not signal the
 513   token and EFI_NOT_FOUND is returned.
 514
 515   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 516   @param[in]   Token            Pointer to a token that has been issued by EFI_UDP6_PROTOCOL.Transmit()
 517                                 or EFI_UDP6_PROTOCOL.Receive().If NULL, all pending tokens are aborted.
 518
 519   @retval EFI_SUCCESS           The asynchronous I/O request was aborted and Token.Event was signaled.
 520                                 When Token is NULL, all pending requests are aborted and their events
 521                                 are signaled.
 522   @retval EFI_INVALID_PARAMETER This is NULL.
 523   @retval EFI_NOT_STARTED       This instance has not been started.
 524   @retval EFI_NOT_FOUND         When Token is not NULL, the asynchronous I/O request was not found in
 525                                 the transmit or receive queue. It has either completed or was not issued
 526                                 by Transmit() and Receive().
 527
 528 **/
 529 typedef
 530 EFI_STATUS
 531 (EFIAPI *EFI_UDP6_CANCEL)(
 532   IN EFI_UDP6_PROTOCOL          *This,
 533   IN EFI_UDP6_COMPLETION_TOKEN  *Token OPTIONAL
 534 );
 535
 536 /**
 537   Polls for incoming data packets and processes outgoing data packets.
 538
 539   The Poll() function can be used by network drivers and applications to increase the rate that data
 540   packets are moved between the communications device and the transmit and receive queues.
 541   In some systems, the periodic timer event in the managed network driver may not poll the underlying
 542   communications device fast enough to transmit and/or receive all data packets without missing incoming
 543   packets or dropping outgoing packets. Drivers and applications that are experiencing packet loss should
 544   try calling the Poll() function more often.
 545
 546   @param[in]   This             Pointer to the EFI_UDP6_PROTOCOL instance.
 547
 548   @retval EFI_SUCCESS           Incoming or outgoing data was processed.
 549   @retval EFI_INVALID_PARAMETER This is NULL.
 550   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred.
 551   @retval EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
 552                                 Consider increasing the polling rate.
 553
 554 **/
 555 typedef
 556 EFI_STATUS
 557 (EFIAPI *EFI_UDP6_POLL)(
 558   IN EFI_UDP6_PROTOCOL  *This
 559 );
 560
 561 ///
 562 /// The EFI_UDP6_PROTOCOL defines an EFI UDPv6 Protocol session that can be used by any network drivers,
 563 /// applications, or daemons to transmit or receive UDP packets. This protocol instance can either be
 564 /// bound to a specified port as a service or connected to some remote peer as an active client.
 565 /// Each instance has its own settings, such as group table, that are independent from each other.
 566 ///
 567 struct _EFI_UDP6_PROTOCOL {
 568   EFI_UDP6_GET_MODE_DATA  GetModeData;
 569   EFI_UDP6_CONFIGURE      Configure;
 570   EFI_UDP6_GROUPS         Groups;
 571   EFI_UDP6_TRANSMIT       Transmit;
 572   EFI_UDP6_RECEIVE        Receive;
 573   EFI_UDP6_CANCEL         Cancel;
 574   EFI_UDP6_POLL           Poll;
 575 };
 576
 577 extern EFI_GUID gEfiUdp6ServiceBindingProtocolGuid;
 578 extern EFI_GUID gEfiUdp6ProtocolGuid;
 579
 580 #endif