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