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