NetworkPkg/TcpDxe/TcpMain.h

   1 /** @file
   2   Declaration of protocol interfaces in EFI_TCP4_PROTOCOL and EFI_TCP6_PROTOCOL.
   3   It is the common head file for all Tcp*.c in TCP driver.
   4
   5   Copyright (c) 2009 - 2016, Intel Corporation. All rights reserved.<BR>
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _TCP_MAIN_H_
  12 #define _TCP_MAIN_H_
  13
  14 #include <Protocol/ServiceBinding.h>
  15 #include <Protocol/DriverBinding.h>
  16 #include <Library/IpIoLib.h>
  17 #include <Library/DevicePathLib.h>
  18 #include <Library/PrintLib.h>
  19
  20 #include "Socket.h"
  21 #include "TcpProto.h"
  22 #include "TcpDriver.h"
  23 #include "TcpFunc.h"
  24
  25 extern UINT16                        mTcp4RandomPort;
  26 extern UINT16                        mTcp6RandomPort;
  27 extern CHAR16                        *mTcpStateName[];
  28 extern EFI_COMPONENT_NAME_PROTOCOL   gTcpComponentName;
  29 extern EFI_COMPONENT_NAME2_PROTOCOL  gTcpComponentName2;
  30 extern EFI_UNICODE_STRING_TABLE      *gTcpControllerNameTable;
  31
  32 extern LIST_ENTRY                    mTcpRunQue;
  33 extern LIST_ENTRY                    mTcpListenQue;
  34 extern TCP_SEQNO                     mTcpGlobalIss;
  35 extern UINT32                        mTcpTick;
  36
  37 ///
  38 /// 30 seconds.
  39 ///
  40 #define TCP6_KEEP_NEIGHBOR_TIME    30
  41 ///
  42 /// 5 seconds, since 1 tick equals 200ms.
  43 ///
  44 #define TCP6_REFRESH_NEIGHBOR_TICK 25
  45
  46 #define TCP_EXPIRE_TIME            65535
  47
  48 ///
  49 /// The implementation selects the initial send sequence number and the unit to
  50 /// be added when it is increased.
  51 ///
  52 #define TCP_BASE_ISS               0x4d7e980b
  53 #define TCP_ISS_INCREMENT_1        2048
  54 #define TCP_ISS_INCREMENT_2        100
  55
  56 typedef union {
  57   EFI_TCP4_CONFIG_DATA  Tcp4CfgData;
  58   EFI_TCP6_CONFIG_DATA  Tcp6CfgData;
  59 } TCP_CONFIG_DATA;
  60
  61 typedef union {
  62   EFI_TCP4_ACCESS_POINT  Tcp4Ap;
  63   EFI_TCP6_ACCESS_POINT  Tcp6Ap;
  64 } TCP_ACCESS_POINT;
  65
  66 typedef struct _TCP4_MODE_DATA {
  67   EFI_TCP4_CONNECTION_STATE       *Tcp4State;
  68   EFI_TCP4_CONFIG_DATA            *Tcp4ConfigData;
  69   EFI_IP4_MODE_DATA               *Ip4ModeData;
  70   EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData;
  71   EFI_SIMPLE_NETWORK_MODE         *SnpModeData;
  72 } TCP4_MODE_DATA;
  73
  74 typedef struct _TCP6_MODE_DATA {
  75   EFI_TCP6_CONNECTION_STATE       *Tcp6State;
  76   EFI_TCP6_CONFIG_DATA            *Tcp6ConfigData;
  77   EFI_IP6_MODE_DATA               *Ip6ModeData;
  78   EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData;
  79   EFI_SIMPLE_NETWORK_MODE         *SnpModeData;
  80 } TCP6_MODE_DATA;
  81
  82 typedef struct _TCP4_ROUTE_INFO {
  83   BOOLEAN           DeleteRoute;
  84   EFI_IPv4_ADDRESS  *SubnetAddress;
  85   EFI_IPv4_ADDRESS  *SubnetMask;
  86   EFI_IPv4_ADDRESS  *GatewayAddress;
  87 } TCP4_ROUTE_INFO;
  88
  89 typedef struct {
  90   EFI_SERVICE_BINDING_PROTOCOL  *ServiceBinding;
  91   UINTN                         NumberOfChildren;
  92   EFI_HANDLE                    *ChildHandleBuffer;
  93 } TCP_DESTROY_CHILD_IN_HANDLE_BUF_CONTEXT;
  94
  95 //
  96 // EFI_TCP4_PROTOCOL definitions.
  97 //
  98
  99 /**
 100   Get the current operational status.
 101
 102   @param[in]   This                Pointer to the EFI_TCP4_PROTOCOL instance.
 103   @param[out]  Tcp4State           Pointer to the buffer to receive the current TCP
 104                                    state. Optional parameter that may be NULL.
 105   @param[out]  Tcp4ConfigData      Pointer to the buffer to receive the current TCP
 106                                    configuration. Optional parameter that may be NULL.
 107   @param[out]  Ip4ModeData         Pointer to the buffer to receive the current
 108                                    IPv4 configuration. Optional parameter that may be NULL.
 109   @param[out]  MnpConfigData       Pointer to the buffer to receive the current MNP
 110                                    configuration data indirectly used by the TCPv4
 111                                    Instance. Optional parameter that may be NULL.
 112   @param[out]  SnpModeData         Pointer to the buffer to receive the current SNP
 113                                    configuration data indirectly used by the TCPv4
 114                                    Instance. Optional parameter that may be NULL.
 115
 116   @retval EFI_SUCCESS              The mode data was read.
 117   @retval EFI_NOT_STARTED          No configuration data is available because this
 118                                    instance hasn't been started.
 119   @retval EFI_INVALID_PARAMETER    This is NULL.
 120
 121 **/
 122 EFI_STATUS
 123 EFIAPI
 124 Tcp4GetModeData (
 125   IN   EFI_TCP4_PROTOCOL                  *This,
 126   OUT  EFI_TCP4_CONNECTION_STATE          *Tcp4State      OPTIONAL,
 127   OUT  EFI_TCP4_CONFIG_DATA               *Tcp4ConfigData OPTIONAL,
 128   OUT  EFI_IP4_MODE_DATA                  *Ip4ModeData    OPTIONAL,
 129   OUT  EFI_MANAGED_NETWORK_CONFIG_DATA    *MnpConfigData  OPTIONAL,
 130   OUT  EFI_SIMPLE_NETWORK_MODE            *SnpModeData    OPTIONAL
 131   );
 132
 133 /**
 134   Initialize or brutally reset the operational parameters for
 135   this EFI TCPv4 instance.
 136
 137   @param[in]   This                Pointer to the EFI_TCP4_PROTOCOL instance.
 138   @param[in]   TcpConfigData       Pointer to the configure data to configure the
 139                                    instance. Optional parameter that may be NULL.
 140
 141   @retval EFI_SUCCESS              The operational settings are set, changed, or
 142                                    reset successfully.
 143   @retval EFI_NO_MAPPING           When using a default address, configuration
 144                                    (through DHCP, BOOTP, RARP, etc.) is not
 145                                    finished.
 146   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 147   @retval EFI_ACCESS_DENIED        Configuring the TCP instance when it is already
 148                                    configured.
 149   @retval EFI_DEVICE_ERROR         An unexpected network or system error occurred.
 150   @retval EFI_UNSUPPORTED          One or more of the control options are not
 151                                    supported in the implementation.
 152   @retval EFI_OUT_OF_RESOURCES     Could not allocate enough system resources.
 153
 154 **/
 155 EFI_STATUS
 156 EFIAPI
 157 Tcp4Configure (
 158   IN EFI_TCP4_PROTOCOL        * This,
 159   IN EFI_TCP4_CONFIG_DATA     * TcpConfigData OPTIONAL
 160   );
 161
 162 /**
 163   Add or delete routing entries.
 164
 165   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance.
 166   @param[in]  DeleteRoute          If TRUE, delete the specified route from routing
 167                                    table; if FALSE, add the specified route to
 168                                    routing table.
 169   @param[in]  SubnetAddress        The destination network.
 170   @param[in]  SubnetMask           The subnet mask for the destination network.
 171   @param[in]  GatewayAddress       The gateway address for this route.
 172
 173   @retval EFI_SUCCESS              The operation completed successfully.
 174   @retval EFI_NOT_STARTED          The EFI_TCP4_PROTOCOL instance has not been
 175                                    configured.
 176   @retval EFI_NO_MAPPING           When using a default address, configuration
 177                                    (through DHCP, BOOTP, RARP, etc.) is not
 178                                    finished.
 179   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 180   @retval EFI_OUT_OF_RESOURCES     Could not allocate enough resources to add the
 181                                    entry to the routing table.
 182   @retval EFI_NOT_FOUND            This route is not in the routing table.
 183   @retval EFI_ACCESS_DENIED        This route is already in the routing table.
 184   @retval EFI_UNSUPPORTED          The TCP driver does not support this operation.
 185
 186 **/
 187 EFI_STATUS
 188 EFIAPI
 189 Tcp4Routes (
 190   IN EFI_TCP4_PROTOCOL           *This,
 191   IN BOOLEAN                     DeleteRoute,
 192   IN EFI_IPv4_ADDRESS            *SubnetAddress,
 193   IN EFI_IPv4_ADDRESS            *SubnetMask,
 194   IN EFI_IPv4_ADDRESS            *GatewayAddress
 195   );
 196
 197 /**
 198   Initiate a nonblocking TCP connection request for an active TCP instance.
 199
 200   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance.
 201   @param[in]  ConnectionToken      Pointer to the connection token to return when
 202                                    the TCP three way handshake finishes.
 203
 204   @retval EFI_SUCCESS              The connection request is successfully
 205                                    initiated.
 206   @retval EFI_NOT_STARTED          This EFI_TCP4_PROTOCOL instance hasn't been
 207                                    configured.
 208   @retval EFI_ACCESS_DENIED        The instance is not configured as an active one
 209                                    or it is not in Tcp4StateClosed state.
 210   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 211   @retval EFI_OUT_OF_RESOURCES     The driver can't allocate enough resources to
 212                                    initiate the active open.
 213   @retval EFI_DEVICE_ERROR         An unexpected system or network error occurred.
 214
 215 **/
 216 EFI_STATUS
 217 EFIAPI
 218 Tcp4Connect (
 219   IN EFI_TCP4_PROTOCOL           *This,
 220   IN EFI_TCP4_CONNECTION_TOKEN   *ConnectionToken
 221   );
 222
 223 /**
 224   Listen on the passive instance to accept an incoming connection request.
 225
 226   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance.
 227   @param[in]  ListenToken          Pointer to the listen token to return when
 228                                    operation finishes.
 229
 230   @retval EFI_SUCCESS              The listen token has been queued successfully.
 231   @retval EFI_NOT_STARTED          The EFI_TCP4_PROTOCOL instance hasn't been
 232                                    configured.
 233   @retval EFI_ACCESS_DENIED        The instance is not a passive one or it is not
 234                                    in Tcp4StateListen state, or a same listen token
 235                                    has already existed in the listen token queue of
 236                                    this TCP instance.
 237   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 238   @retval EFI_OUT_OF_RESOURCES     Could not allocate enough resources to finish
 239                                    the operation.
 240   @retval EFI_DEVICE_ERROR         An unexpected system or network error occurred.
 241
 242 **/
 243 EFI_STATUS
 244 EFIAPI
 245 Tcp4Accept (
 246   IN EFI_TCP4_PROTOCOL             *This,
 247   IN EFI_TCP4_LISTEN_TOKEN         *ListenToken
 248   );
 249
 250 /**
 251   Queues outgoing data into the transmit queue
 252
 253   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance
 254   @param[in]  Token                Pointer to the completion token to queue to the
 255                                    transmit queue
 256
 257   @retval EFI_SUCCESS              The data has been queued for transmission
 258   @retval EFI_NOT_STARTED          The EFI_TCP4_PROTOCOL instance hasn't been
 259                                    configured.
 260   @retval EFI_NO_MAPPING           When using a default address, configuration
 261                                    (DHCP, BOOTP, RARP, etc.) is not finished yet.
 262   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid
 263   @retval EFI_ACCESS_DENIED        One or more of the following conditions is TRUE:
 264                                    * A transmit completion token with the same
 265                                    Token-> CompletionToken.Event was already in the
 266                                    transmission queue. * The current instance is in
 267                                    Tcp4StateClosed state * The current instance is
 268                                    a passive one and it is in Tcp4StateListen
 269                                    state. * User has called Close() to disconnect
 270                                    this connection.
 271   @retval EFI_NOT_READY            The completion token could not be queued because
 272                                    the transmit queue is full.
 273   @retval EFI_OUT_OF_RESOURCES     Could not queue the transmit data because of a
 274                                    resource shortage.
 275   @retval EFI_NETWORK_UNREACHABLE  There is no route to the destination network or
 276                                    address.
 277
 278 **/
 279 EFI_STATUS
 280 EFIAPI
 281 Tcp4Transmit (
 282   IN EFI_TCP4_PROTOCOL            *This,
 283   IN EFI_TCP4_IO_TOKEN            *Token
 284   );
 285
 286 /**
 287   Place an asynchronous receive request into the receiving queue.
 288
 289   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance.
 290   @param[in]  Token                Pointer to a token that is associated with the
 291                                    receive data descriptor.
 292
 293   @retval EFI_SUCCESS              The receive completion token was cached.
 294   @retval EFI_NOT_STARTED          The EFI_TCP4_PROTOCOL instance hasn't been
 295                                    configured.
 296   @retval EFI_NO_MAPPING           When using a default address, configuration
 297                                    (DHCP, BOOTP, RARP, etc.) is not finished yet.
 298   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 299   @retval EFI_OUT_OF_RESOURCES     The receive completion token could not be queued
 300                                    due to a lack of system resources.
 301   @retval EFI_DEVICE_ERROR         An unexpected system or network error occurred.
 302   @retval EFI_ACCESS_DENIED        One or more of the following conditions is TRUE:
 303                                    * A receive completion token with the same
 304                                    Token->CompletionToken.Event was already in the
 305                                    receive queue. * The current instance is in
 306                                    Tcp4StateClosed state. * The current instance is
 307                                    a passive one and it is in Tcp4StateListen
 308                                    state. * User has called Close() to disconnect
 309                                    this connection.
 310   @retval EFI_CONNECTION_FIN       The communication peer has closed the connection
 311                                    and there is no buffered data in the receive
 312                                    buffer of this instance.
 313   @retval EFI_NOT_READY            The receive request could not be queued because
 314                                    the receive queue is full.
 315
 316 **/
 317 EFI_STATUS
 318 EFIAPI
 319 Tcp4Receive (
 320   IN EFI_TCP4_PROTOCOL           *This,
 321   IN EFI_TCP4_IO_TOKEN           *Token
 322   );
 323
 324 /**
 325   Disconnecting a TCP connection gracefully or reset a TCP connection.
 326
 327   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance.
 328   @param[in]  CloseToken           Pointer to the close token to return when
 329                                    operation finishes.
 330
 331   @retval EFI_SUCCESS              The operation completed successfully.
 332   @retval EFI_NOT_STARTED          The EFI_TCP4_PROTOCOL instance hasn't been
 333                                    configured.
 334   @retval EFI_ACCESS_DENIED        One or more of the following are TRUE: *
 335                                    Configure() has been called with TcpConfigData
 336                                    set to NULL and this function has not returned.
 337                                    * Previous Close() call on this instance has not
 338                                    finished.
 339   @retval EFI_INVALID_PARAMETER    One ore more parameters are invalid.
 340   @retval EFI_OUT_OF_RESOURCES     Could not allocate enough resources to finish the
 341                                    operation.
 342   @retval EFI_DEVICE_ERROR         Any unexpected error not belonging to the error
 343                                    categories given above.
 344
 345 **/
 346 EFI_STATUS
 347 EFIAPI
 348 Tcp4Close (
 349   IN EFI_TCP4_PROTOCOL           *This,
 350   IN EFI_TCP4_CLOSE_TOKEN        *CloseToken
 351   );
 352
 353 /**
 354   Abort an asynchronous connection, listen, transmission or receive request.
 355
 356   @param  This  The pointer to the EFI_TCP4_PROTOCOL instance.
 357   @param  Token The pointer to a token that has been issued by
 358                 EFI_TCP4_PROTOCOL.Connect(),
 359                 EFI_TCP4_PROTOCOL.Accept(),
 360                 EFI_TCP4_PROTOCOL.Transmit() or
 361                 EFI_TCP4_PROTOCOL.Receive(). If NULL, all pending
 362                 tokens issued by above four functions will be aborted. Type
 363                 EFI_TCP4_COMPLETION_TOKEN is defined in
 364                 EFI_TCP4_PROTOCOL.Connect().
 365
 366   @retval  EFI_SUCCESS             The asynchronous I/O request is aborted and Token->Event
 367                                    is signaled.
 368   @retval  EFI_INVALID_PARAMETER   This is NULL.
 369   @retval  EFI_NOT_STARTED         This instance hasn't been configured.
 370   @retval  EFI_NO_MAPPING          When using the default address, configuration
 371                                    (DHCP, BOOTP,RARP, etc.) hasn't finished yet.
 372   @retval  EFI_NOT_FOUND           The asynchronous I/O request isn't found in the
 373                                    transmission or receive queue. It has either
 374                                    completed or wasn't issued by Transmit() and Receive().
 375
 376 **/
 377 EFI_STATUS
 378 EFIAPI
 379 Tcp4Cancel (
 380   IN EFI_TCP4_PROTOCOL             *This,
 381   IN EFI_TCP4_COMPLETION_TOKEN     *Token OPTIONAL
 382   );
 383
 384 /**
 385   Poll to receive incoming data and transmit outgoing segments.
 386
 387   @param[in]  This                 Pointer to the EFI_TCP4_PROTOCOL instance.
 388
 389   @retval EFI_SUCCESS              Incoming or outgoing data was processed.
 390   @retval EFI_INVALID_PARAMETER    This is NULL.
 391   @retval EFI_DEVICE_ERROR         An unexpected system or network error occurred.
 392   @retval EFI_NOT_READY            No incoming or outgoing data was processed.
 393   @retval EFI_TIMEOUT              Data was dropped out of the transmission or
 394                                    receive queue. Consider increasing the polling
 395                                    rate.
 396
 397 **/
 398 EFI_STATUS
 399 EFIAPI
 400 Tcp4Poll (
 401   IN EFI_TCP4_PROTOCOL        *This
 402   );
 403
 404 //
 405 // EFI_TCP6_PROTOCOL definitions.
 406 //
 407
 408 /**
 409   Get the current operational status.
 410
 411   The GetModeData() function copies the current operational settings of this EFI TCPv6
 412   Protocol instance into user-supplied buffers. This function can also be used to retrieve
 413   the operational setting of underlying drivers such as IPv6, MNP, or SNP.
 414
 415   @param[in]  This              Pointer to the EFI_TCP6_PROTOCOL instance.
 416   @param[out] Tcp6State         The buffer in which the current TCP state is
 417                                 returned. Optional parameter that may be NULL.
 418   @param[out] Tcp6ConfigData    The buffer in which the current TCP configuration
 419                                 is returned. Optional parameter that may be NULL.
 420   @param[out] Ip6ModeData       The buffer in which the current IPv6 configuration
 421                                 data used by the TCP instance is returned.
 422                                 Optional parameter that may be NULL.
 423   @param[out] MnpConfigData     The buffer in which the current MNP configuration
 424                                 data used indirectly by the TCP instance is returned.
 425                                 Optional parameter that may be NULL.
 426   @param[out] SnpModeData       The buffer in which the current SNP mode data
 427                                  used indirectly by the TCP instance is returned.
 428                                 Optional parameter that may be NULL.
 429
 430   @retval EFI_SUCCESS           The mode data was read.
 431   @retval EFI_NOT_STARTED       No configuration data is available because this instance hasn't
 432                                 been started.
 433   @retval EFI_INVALID_PARAMETER This is NULL.
 434
 435 **/
 436 EFI_STATUS
 437 EFIAPI
 438 Tcp6GetModeData (
 439   IN  EFI_TCP6_PROTOCOL                  *This,
 440   OUT EFI_TCP6_CONNECTION_STATE          *Tcp6State      OPTIONAL,
 441   OUT EFI_TCP6_CONFIG_DATA               *Tcp6ConfigData OPTIONAL,
 442   OUT EFI_IP6_MODE_DATA                  *Ip6ModeData    OPTIONAL,
 443   OUT EFI_MANAGED_NETWORK_CONFIG_DATA    *MnpConfigData  OPTIONAL,
 444   OUT EFI_SIMPLE_NETWORK_MODE            *SnpModeData    OPTIONAL
 445   );
 446
 447 /**
 448   Initialize or brutally reset the operational parameters for this EFI TCPv6 instance.
 449
 450   The Configure() function does the following:
 451   - Initialize this TCP instance, i.e., initialize the communication end settings and
 452     specify active open or passive open for an instance.
 453   - Reset this TCP instance brutally, i.e., cancel all pending asynchronous tokens, flush
 454     transmission and receiving buffer directly without informing the communication peer.
 455
 456   No other TCPv6 Protocol operation except Poll() can be executed by this instance until
 457   it is configured properly. For an active TCP instance, after a proper configuration it
 458   may call Connect() to initiates the three-way handshake. For a passive TCP instance,
 459   its state will transit to Tcp6StateListen after configuration, and Accept() may be
 460   called to listen the incoming TCP connection requests. If Tcp6ConfigData is set to NULL,
 461   the instance is reset. Resetting process will be done brutally, the state machine will
 462   be set to Tcp6StateClosed directly, the receive queue and transmit queue will be flushed,
 463   and no traffic is allowed through this instance.
 464
 465   @param[in] This               Pointer to the EFI_TCP6_PROTOCOL instance.
 466   @param[in] Tcp6ConfigData     Pointer to the configure data to configure the instance.
 467                                 If Tcp6ConfigData is set to NULL, the instance is reset.
 468
 469   @retval EFI_SUCCESS           The operational settings were set, changed, or reset
 470                                 successfully.
 471   @retval EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
 472                                 address for this instance, but no source address was available for
 473                                 use.
 474   @retval EFI_INVALID_PARAMETER One or more of the following conditions are TRUE:
 475                                 - This is NULL.
 476                                 - Tcp6ConfigData->AccessPoint.StationAddress is neither zero nor
 477                                   one of the configured IP addresses in the underlying IPv6 driver.
 478                                 - Tcp6ConfigData->AccessPoint.RemoteAddress isn't a valid unicast
 479                                   IPv6 address.
 480                                 - Tcp6ConfigData->AccessPoint.RemoteAddress is zero or
 481                                   Tcp6ConfigData->AccessPoint.RemotePort is zero when
 482                                   Tcp6ConfigData->AccessPoint.ActiveFlag is TRUE.
 483                                 - A same access point has been configured in other TCP
 484                                   instance properly.
 485   @retval EFI_ACCESS_DENIED     Configuring TCP instance when it is configured without
 486                                 calling Configure() with NULL to reset it.
 487   @retval EFI_UNSUPPORTED       One or more of the control options are not supported in
 488                                 the implementation.
 489   @retval EFI_OUT_OF_RESOURCES  Could not allocate enough system resources when
 490                                 executing Configure().
 491   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 492
 493 **/
 494 EFI_STATUS
 495 EFIAPI
 496 Tcp6Configure (
 497   IN EFI_TCP6_PROTOCOL        *This,
 498   IN EFI_TCP6_CONFIG_DATA     *Tcp6ConfigData OPTIONAL
 499   );
 500
 501 /**
 502   Initiate a nonblocking TCP connection request for an active TCP instance.
 503
 504   The Connect() function will initiate an active open to the remote peer configured
 505   in current TCP instance if it is configured active. If the connection succeeds or
 506   fails due to an error, the ConnectionToken->CompletionToken.Event will be signaled,
 507   and ConnectionToken->CompletionToken.Status will be updated accordingly. This
 508   function can only be called for the TCP instance in Tcp6StateClosed state. The
 509   instance will transfer into Tcp6StateSynSent if the function returns EFI_SUCCESS.
 510   If TCP three-way handshake succeeds, its state will become Tcp6StateEstablished;
 511   otherwise, the state will return to Tcp6StateClosed.
 512
 513   @param[in] This                Pointer to the EFI_TCP6_PROTOCOL instance.
 514   @param[in] ConnectionToken     Pointer to the connection token to return when the TCP
 515                                  three-way handshake finishes.
 516
 517   @retval EFI_SUCCESS            The connection request successfully initiated and the state of
 518                                  this TCP instance has been changed to Tcp6StateSynSent.
 519   @retval EFI_NOT_STARTED        This EFI TCPv6 Protocol instance has not been configured.
 520   @retval EFI_ACCESS_DENIED      One or more of the following conditions are TRUE:
 521                                  - This instance is not configured as an active instance.
 522                                  - This instance is not in Tcp6StateClosed state.
 523   @retval EFI_INVALID_PARAMETER  One or more of the following are TRUE:
 524                                  - This is NULL.
 525                                  - ConnectionToken is NULL.
 526                                  - ConnectionToken->CompletionToken.Event is NULL.
 527   @retval EFI_OUT_OF_RESOURCES   The driver can't allocate enough resources to initiate the active open.
 528   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 529
 530 **/
 531 EFI_STATUS
 532 EFIAPI
 533 Tcp6Connect (
 534   IN EFI_TCP6_PROTOCOL           *This,
 535   IN EFI_TCP6_CONNECTION_TOKEN   *ConnectionToken
 536   );
 537
 538 /**
 539   Listen on the passive instance to accept an incoming connection request. This is a
 540   nonblocking operation.
 541
 542   The Accept() function initiates an asynchronous accept request to wait for an incoming
 543   connection on the passive TCP instance. If a remote peer successfully establishes a
 544   connection with this instance, a new TCP instance will be created and its handle will
 545   be returned in ListenToken->NewChildHandle. The newly created instance is configured
 546   by inheriting the passive instance's configuration, and is ready for use upon return.
 547   The new instance is in the Tcp6StateEstablished state.
 548
 549   The ListenToken->CompletionToken.Event will be signaled when a new connection is
 550   accepted, user aborts the listen or connection is reset.
 551
 552   This function only can be called when the current TCP instance is in Tcp6StateListen state.
 553
 554   @param[in] This                Pointer to the EFI_TCP6_PROTOCOL instance.
 555   @param[in] ListenToken         Pointer to the listen token to return when the operation finishes.
 556
 557
 558   @retval EFI_SUCCESS            The listen token was been queued successfully.
 559   @retval EFI_NOT_STARTED        This EFI TCPv6 Protocol instance has not been configured.
 560   @retval EFI_ACCESS_DENIED      One or more of the following are TRUE:
 561                                  - This instance is not a passive instance.
 562                                  - This instance is not in Tcp6StateListen state.
 563                                  - The same listen token has already existed in the listen
 564                                    token queue of this TCP instance.
 565   @retval EFI_INVALID_PARAMETER  One or more of the following are TRUE:
 566                                  - This is NULL.
 567                                  - ListenToken is NULL.
 568                                  - ListenToken->CompletionToken.Event is NULL.
 569   @retval EFI_OUT_OF_RESOURCES   Could not allocate enough resources to finish the operation.
 570   @retval EFI_DEVICE_ERROR       Any unexpected error not belonging to the error
 571                                  categories given above.
 572
 573 **/
 574 EFI_STATUS
 575 EFIAPI
 576 Tcp6Accept (
 577   IN EFI_TCP6_PROTOCOL             *This,
 578   IN EFI_TCP6_LISTEN_TOKEN         *ListenToken
 579   );
 580
 581 /**
 582   Queues outgoing data into the transmit queue.
 583
 584   The Transmit() function queues a sending request to this TCP instance along with the
 585   user data. The status of the token is updated and the event in the token will be
 586   signaled once the data is sent out or some error occurs.
 587
 588   @param[in] This                 Pointer to the EFI_TCP6_PROTOCOL instance.
 589   @param[in] Token                Pointer to the completion token to queue to the transmit queue.
 590
 591   @retval EFI_SUCCESS             The data has been queued for transmission.
 592   @retval EFI_NOT_STARTED         This EFI TCPv6 Protocol instance has not been configured.
 593   @retval EFI_NO_MAPPING          The underlying IPv6 driver was responsible for choosing a
 594                                   source address for this instance, but no source address was
 595                                   available for use.
 596   @retval EFI_INVALID_PARAMETER   One or more of the following are TRUE:
 597                                   - This is NULL.
 598                                   - Token is NULL.
 599                                   - Token->CompletionToken.Event is NULL.
 600                                   - Token->Packet.TxData is NULL.
 601                                   - Token->Packet.FragmentCount is zero.
 602                                   - Token->Packet.DataLength is not equal to the sum of fragment lengths.
 603   @retval EFI_ACCESS_DENIED       One or more of the following conditions are TRUE:
 604                                   - A transmit completion token with the same Token->
 605                                     CompletionToken.Event was already in the
 606                                     transmission queue.
 607                                   - The current instance is in Tcp6StateClosed state.
 608                                   - The current instance is a passive one and it is in
 609                                     Tcp6StateListen state.
 610                                   - User has called Close() to disconnect this connection.
 611   @retval EFI_NOT_READY           The completion token could not be queued because the
 612                                   transmit queue is full.
 613   @retval EFI_OUT_OF_RESOURCES    Could not queue the transmit data because of a resource
 614                                   shortage.
 615   @retval EFI_NETWORK_UNREACHABLE There is no route to the destination network or address.
 616
 617 **/
 618 EFI_STATUS
 619 EFIAPI
 620 Tcp6Transmit (
 621   IN EFI_TCP6_PROTOCOL            *This,
 622   IN EFI_TCP6_IO_TOKEN            *Token
 623   );
 624
 625 /**
 626   Places an asynchronous receive request into the receiving queue.
 627
 628   The Receive() function places a completion token into the receive packet queue. This
 629   function is always asynchronous. The caller must allocate the Token->CompletionToken.Event
 630   and the FragmentBuffer used to receive data. The caller also must fill the DataLength, which
 631   represents the whole length of all FragmentBuffer. When the receive operation completes, the
 632   EFI TCPv6 Protocol driver updates the Token->CompletionToken.Status and Token->Packet.RxData
 633   fields, and the Token->CompletionToken.Event is signaled. If data is obtained, the data and its length
 634   will be copied into the FragmentTable. At the same time the full length of received data will
 635   be recorded in the DataLength fields. Providing a proper notification function and context
 636   for the event enables the user to receive the notification and receiving status. That
 637   notification function is guaranteed to not be re-entered.
 638
 639   @param[in] This               Pointer to the EFI_TCP6_PROTOCOL instance.
 640   @param[in] Token              Pointer to a token that is associated with the receive data
 641                                 descriptor.
 642
 643   @retval EFI_SUCCESS            The receive completion token was cached.
 644   @retval EFI_NOT_STARTED        This EFI TCPv6 Protocol instance has not been configured.
 645   @retval EFI_NO_MAPPING         The underlying IPv6 driver was responsible for choosing a source
 646                                  address for this instance, but no source address was available for use.
 647   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 648                                  - This is NULL.
 649                                  - Token is NULL.
 650                                  - Token->CompletionToken.Event is NULL.
 651                                  - Token->Packet.RxData is NULL.
 652                                  - Token->Packet.RxData->DataLength is 0.
 653                                  - The Token->Packet.RxData->DataLength is not the
 654                                    sum of all FragmentBuffer length in FragmentTable.
 655   @retval EFI_OUT_OF_RESOURCES   The receive completion token could not be queued due to a lack of
 656                                  system resources (usually memory).
 657   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 658                                  The EFI TCPv6 Protocol instance has been reset to startup defaults.
 659   @retval EFI_ACCESS_DENIED      One or more of the following conditions is TRUE:
 660                                  - A receive completion token with the same Token->CompletionToken.Event
 661                                    was already in the receive queue.
 662                                  - The current instance is in Tcp6StateClosed state.
 663                                  - The current instance is a passive one and it is in
 664                                    Tcp6StateListen state.
 665                                  - The user has called Close() to disconnect this connection.
 666   @retval EFI_CONNECTION_FIN     The communication peer has closed the connection, and there is no
 667                                  buffered data in the receive buffer of this instance.
 668   @retval EFI_NOT_READY          The receive request could not be queued because the receive queue is full.
 669
 670 **/
 671 EFI_STATUS
 672 EFIAPI
 673 Tcp6Receive (
 674   IN EFI_TCP6_PROTOCOL           *This,
 675   IN EFI_TCP6_IO_TOKEN           *Token
 676   );
 677
 678 /**
 679   Disconnecting a TCP connection gracefully or reset a TCP connection. This function is a
 680   nonblocking operation.
 681
 682   Initiate an asynchronous close token to the TCP driver. After Close() is called, any buffered
 683   transmission data will be sent by the TCP driver, and the current instance will have a graceful close
 684   working flow described as RFC 793 if AbortOnClose is set to FALSE, otherwise, a rest packet
 685   will be sent by TCP driver to fast disconnect this connection. When the close operation completes
 686   successfully the TCP instance is in Tcp6StateClosed state, all pending asynchronous
 687   operations are signaled, and any buffers used for TCP network traffic are flushed.
 688
 689   @param[in] This                Pointer to the EFI_TCP6_PROTOCOL instance.
 690   @param[in] CloseToken          Pointer to the close token to return when operation finishes.
 691
 692   @retval EFI_SUCCESS            The Close() was called successfully.
 693   @retval EFI_NOT_STARTED        This EFI TCPv6 Protocol instance has not been configured.
 694   @retval EFI_ACCESS_DENIED      One or more of the following are TRUE:
 695                                  - CloseToken or CloseToken->CompletionToken.Event is already in use.
 696                                  - Previous Close() call on this instance has not finished.
 697   @retval EFI_INVALID_PARAMETER  One or more of the following are TRUE:
 698                                  - This is NULL.
 699                                  - CloseToken is NULL.
 700                                  - CloseToken->CompletionToken.Event is NULL.
 701   @retval EFI_OUT_OF_RESOURCES   Could not allocate enough resources to finish the operation.
 702   @retval EFI_DEVICE_ERROR       Any unexpected error not belonging to the error categories given above.
 703
 704 **/
 705 EFI_STATUS
 706 EFIAPI
 707 Tcp6Close (
 708   IN EFI_TCP6_PROTOCOL           *This,
 709   IN EFI_TCP6_CLOSE_TOKEN        *CloseToken
 710   );
 711
 712 /**
 713   Abort an asynchronous connection, listen, transmission or receive request.
 714
 715   The Cancel() function aborts a pending connection, listen, transmit or
 716   receive request.
 717
 718   If Token is not NULL and the token is in the connection, listen, transmission
 719   or receive queue when it is being cancelled, its Token->Status will be set
 720   to EFI_ABORTED and then Token->Event will be signaled.
 721
 722   If the token is not in one of the queues, which usually means that the
 723   asynchronous operation has completed, EFI_NOT_FOUND is returned.
 724
 725   If Token is NULL all asynchronous token issued by Connect(), Accept(),
 726   Transmit() and Receive() will be aborted.
 727
 728   @param[in] This                Pointer to the EFI_TCP6_PROTOCOL instance.
 729   @param[in] Token               Pointer to a token that has been issued by
 730                                  EFI_TCP6_PROTOCOL.Connect(),
 731                                  EFI_TCP6_PROTOCOL.Accept(),
 732                                  EFI_TCP6_PROTOCOL.Transmit() or
 733                                  EFI_TCP6_PROTOCOL.Receive(). If NULL, all pending
 734                                  tokens issued by above four functions will be aborted. Type
 735                                  EFI_TCP6_COMPLETION_TOKEN is defined in
 736                                  EFI_TCP_PROTOCOL.Connect().
 737
 738   @retval EFI_SUCCESS            The asynchronous I/O request is aborted and Token->Event
 739                                  is signaled.
 740   @retval EFI_INVALID_PARAMETER  This is NULL.
 741   @retval EFI_NOT_STARTED        This instance hasn't been configured.
 742   @retval EFI_NOT_FOUND          The asynchronous I/O request isn't found in the transmission or
 743                                  receive queue. It has either completed or wasn't issued by
 744                                  Transmit() and Receive().
 745
 746 **/
 747 EFI_STATUS
 748 EFIAPI
 749 Tcp6Cancel (
 750   IN EFI_TCP6_PROTOCOL           *This,
 751   IN EFI_TCP6_COMPLETION_TOKEN   *Token OPTIONAL
 752   );
 753
 754 /**
 755   Poll to receive incoming data and transmit outgoing segments.
 756
 757   The Poll() function increases the rate that data is moved between the network
 758   and application and can be called when the TCP instance is created successfully.
 759   Its use is optional.
 760
 761   @param[in] This                Pointer to the EFI_TCP6_PROTOCOL instance.
 762
 763   @retval EFI_SUCCESS            Incoming or outgoing data was processed.
 764   @retval EFI_INVALID_PARAMETER  This is NULL.
 765   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 766   @retval EFI_NOT_READY          No incoming or outgoing data is processed.
 767   @retval EFI_TIMEOUT            Data was dropped out of the transmission or receive queue.
 768                                  Consider increasing the polling rate.
 769
 770 **/
 771 EFI_STATUS
 772 EFIAPI
 773 Tcp6Poll (
 774   IN EFI_TCP6_PROTOCOL        *This
 775   );
 776
 777 #endif