X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=MdePkg%2FInclude%2FProtocol%2FTcp4.h;h=e27581b1d87d622c25472f51b6c2699a15cc42db;hp=715c581e6d4bc4c269519dd2e5a7452775cf5e22;hb=58fe27722dad2e6313101e232ff9004b51cac77f;hpb=8b13229b469f05ec22d76098b052bd6e943fecee diff --git a/MdePkg/Include/Protocol/Tcp4.h b/MdePkg/Include/Protocol/Tcp4.h index 715c581e6d..e27581b1d8 100644 --- a/MdePkg/Include/Protocol/Tcp4.h +++ b/MdePkg/Include/Protocol/Tcp4.h @@ -1,17 +1,20 @@ /** @file - EFI TCPv4 Protocol Definition + EFI TCPv4(Transmission Control Protocol version 4) Protocol Definition The EFI TCPv4 Service Binding Protocol is used to locate EFI TCPv4 Protocol drivers to create and destroy child of the driver to communicate with other host using TCP protocol. The EFI TCPv4 Protocol provides services to send and receive data stream. - Copyright (c) 2006, Intel Corporation - All rights reserved. This program and the accompanying materials - are licensed and made available under the terms and conditions of the BSD License - which accompanies this distribution. The full text of the license may be found at - http://opensource.org/licenses/bsd-license.php +Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.
+This program and the accompanying materials are licensed and made available under +the terms and conditions of the BSD License that accompanies this distribution. +The full text of the license may be found at +http://opensource.org/licenses/bsd-license.php. + +THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, +WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. - THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, - WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + @par Revision Reference: + This Protocol is introduced in UEFI Specification 2.0. **/ @@ -32,14 +35,22 @@ typedef struct _EFI_TCP4_PROTOCOL EFI_TCP4_PROTOCOL; +/// +/// EFI_TCP4_SERVICE_POINT is deprecated in the UEFI 2.4B and should not be used any more. +/// The definition in here is only present to provide backwards compatability. +/// typedef struct { - EFI_HANDLE InstanceHandle; + EFI_HANDLE InstanceHandle; EFI_IPv4_ADDRESS LocalAddress; UINT16 LocalPort; EFI_IPv4_ADDRESS RemoteAddress; UINT16 RemotePort; } EFI_TCP4_SERVICE_POINT; +/// +/// EFI_TCP4_VARIABLE_DATA is deprecated in the UEFI 2.4B and should not be used any more. +/// The definition in here is only present to provide backwards compatability. +/// typedef struct { EFI_HANDLE DriverHandle; UINT32 ServiceCount; @@ -92,6 +103,9 @@ typedef struct { EFI_TCP4_OPTION *ControlOption; } EFI_TCP4_CONFIG_DATA; +/// +/// TCP4 connnection state +/// typedef enum { Tcp4StateClosed = 0, Tcp4StateListen = 1, @@ -112,6 +126,32 @@ typedef struct { } EFI_TCP4_COMPLETION_TOKEN; typedef struct { + /// + /// The Status in the CompletionToken will be set to one of + /// the following values if the active open succeeds or an unexpected + /// error happens: + /// EFI_SUCCESS: The active open succeeds and the instance's + /// state is Tcp4StateEstablished. + /// EFI_CONNECTION_RESET: The connect fails because the connection is reset + /// either by instance itself or the communication peer. + /// EFI_CONNECTION_REFUSED: The connect fails because this connection is initiated with + /// an active open and the connection is refused. + /// EFI_ABORTED: The active open is aborted. + /// EFI_TIMEOUT: The connection establishment timer expires and + /// no more specific information is available. + /// EFI_NETWORK_UNREACHABLE: The active open fails because + /// an ICMP network unreachable error is received. + /// EFI_HOST_UNREACHABLE: The active open fails because an + /// ICMP host unreachable error is received. + /// EFI_PROTOCOL_UNREACHABLE: The active open fails + /// because an ICMP protocol unreachable error is received. + /// EFI_PORT_UNREACHABLE: The connection establishment + /// timer times out and an ICMP port unreachable error is received. + /// EFI_ICMP_ERROR: The connection establishment timer timeout and some other ICMP + /// error is received. + /// EFI_DEVICE_ERROR: An unexpected system or network error occurred. + /// EFI_NO_MEDIA: There was a media error. + /// EFI_TCP4_COMPLETION_TOKEN CompletionToken; } EFI_TCP4_CONNECTION_TOKEN; @@ -141,9 +181,42 @@ typedef struct { } EFI_TCP4_TRANSMIT_DATA; typedef struct { + /// + /// When transmission finishes or meets any unexpected error it will + /// be set to one of the following values: + /// EFI_SUCCESS: The receiving or transmission operation + /// completes successfully. + /// EFI_CONNECTION_FIN: The receiving operation fails because the communication peer + /// has closed the connection and there is no more data in the + /// receive buffer of the instance. + /// EFI_CONNECTION_RESET: The receiving or transmission operation fails + /// because this connection is reset either by instance + /// itself or the communication peer. + /// EFI_ABORTED: The receiving or transmission is aborted. + /// EFI_TIMEOUT: The transmission timer expires and no more + /// specific information is available. + /// EFI_NETWORK_UNREACHABLE: The transmission fails + /// because an ICMP network unreachable error is received. + /// EFI_HOST_UNREACHABLE: The transmission fails because an + /// ICMP host unreachable error is received. + /// EFI_PROTOCOL_UNREACHABLE: The transmission fails + /// because an ICMP protocol unreachable error is received. + /// EFI_PORT_UNREACHABLE: The transmission fails and an + /// ICMP port unreachable error is received. + /// EFI_ICMP_ERROR: The transmission fails and some other + /// ICMP error is received. + /// EFI_DEVICE_ERROR: An unexpected system or network error occurs. + /// EFI_NO_MEDIA: There was a media error. + /// EFI_TCP4_COMPLETION_TOKEN CompletionToken; union { + /// + /// When this token is used for receiving, RxData is a pointer to EFI_TCP4_RECEIVE_DATA. + /// EFI_TCP4_RECEIVE_DATA *RxData; + /// + /// When this token is used for transmitting, TxData is a pointer to EFI_TCP4_TRANSMIT_DATA. + /// EFI_TCP4_TRANSMIT_DATA *TxData; } Packet; } EFI_TCP4_IO_TOKEN; @@ -160,14 +233,14 @@ typedef struct { /** Get the current operational status. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param Tcp4State Pointer to the buffer to receive the current TCP state. - @param Tcp4ConfigData Pointer to the buffer to receive the current TCP configuration. - @param Ip4ModeData Pointer to the buffer to receive the current IPv4 configuration + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param Tcp4State The pointer to the buffer to receive the current TCP state. + @param Tcp4ConfigData The pointer to the buffer to receive the current TCP configuration. + @param Ip4ModeData The pointer to the buffer to receive the current IPv4 configuration data used by the TCPv4 instance. - @param MnpConfigData Pointer to the buffer to receive the current MNP configuration + @param MnpConfigData The pointer to the buffer to receive the current MNP configuration data used indirectly by the TCPv4 instance. - @param SnpModeData Pointer to the buffer to receive the current SNP configuration + @param SnpModeData The pointer to the buffer to receive the current SNP configuration data used indirectly by the TCPv4 instance. @retval EFI_SUCCESS The mode data was read. @@ -179,20 +252,19 @@ typedef struct { typedef EFI_STATUS (EFIAPI *EFI_TCP4_GET_MODE_DATA)( - IN CONST EFI_TCP4_PROTOCOL *This, - OUT EFI_TCP4_CONNECTION_STATE *Tcp4State OPTIONAL, - OUT EFI_TCP4_CONFIG_DATA *Tcp4ConfigData OPTIONAL, - OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL, - OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, - OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL - ) -; + IN EFI_TCP4_PROTOCOL *This, + OUT EFI_TCP4_CONNECTION_STATE *Tcp4State OPTIONAL, + OUT EFI_TCP4_CONFIG_DATA *Tcp4ConfigData OPTIONAL, + OUT EFI_IP4_MODE_DATA *Ip4ModeData OPTIONAL, + OUT EFI_MANAGED_NETWORK_CONFIG_DATA *MnpConfigData OPTIONAL, + OUT EFI_SIMPLE_NETWORK_MODE *SnpModeData OPTIONAL + ); /** Initialize or brutally reset the operational parameters for this EFI TCPv4 instance. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param Tcp4ConfigData Pointer to the configure data to configure the instance. + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param Tcp4ConfigData The pointer to the configure data to configure the instance. @retval EFI_SUCCESS The operational settings are set, changed, or reset successfully. @@ -213,14 +285,13 @@ EFI_STATUS (EFIAPI *EFI_TCP4_CONFIGURE)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_CONFIG_DATA *TcpConfigData OPTIONAL - ) -; + ); /** Add or delete a route entry to the route table - @param This Pointer to the EFI_TCP4_PROTOCOL instance. + @param This The pointer to the EFI_TCP4_PROTOCOL instance. @param DeleteRoute Set it to TRUE to delete this route from the routing table. Set it to FALSE to add this route to the routing table. DestinationAddress and SubnetMask are used as the @@ -258,19 +329,17 @@ EFI_STATUS IN EFI_IPv4_ADDRESS *SubnetAddress, IN EFI_IPv4_ADDRESS *SubnetMask, IN EFI_IPv4_ADDRESS *GatewayAddress - ) -; + ); /** Initiate a nonblocking TCP connection request for an active TCP instance. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param ConnectionToken Pointer to the connection token to return when the TCP three + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param ConnectionToken The pointer to the connection token to return when the TCP three way handshake finishes. @retval EFI_SUCCESS The connection request is successfully initiated and the state - - of this TCPv4 instance has been changed to - - Tcp4StateSynSent. + of this TCPv4 instance has been changed to Tcp4StateSynSent. @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured. @retval EFI_ACCESS_DENIED One or more of the following conditions are TRUE: - This instance is not configured as an active one. @@ -279,7 +348,7 @@ EFI_STATUS - This is NULL. - ConnectionToken is NULL. - ConnectionToken->CompletionToken.Event is NULL. - @retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resource to initiate the activeopen. + @retval EFI_OUT_OF_RESOURCES The driver can't allocate enough resource to initiate the activ eopen. @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. **/ @@ -288,15 +357,14 @@ EFI_STATUS (EFIAPI *EFI_TCP4_CONNECT)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_CONNECTION_TOKEN *ConnectionToken - ) -; + ); /** Listen on the passive instance to accept an incoming connection request. This is a nonblocking operation. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param ListenToken Pointer to the listen token to return when operation finishes. + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param ListenToken The pointer to the listen token to return when operation finishes. @retval EFI_SUCCESS The listen token has been queued successfully. @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured. @@ -318,14 +386,13 @@ EFI_STATUS (EFIAPI *EFI_TCP4_ACCEPT)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_LISTEN_TOKEN *ListenToken - ) -; + ); /** Queues outgoing data into the transmit queue. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param Token Pointer to the completion token to queue to the transmit queue. + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param Token The pointer to the completion token to queue to the transmit queue. @retval EFI_SUCCESS The data has been queued for transmission. @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured. @@ -357,15 +424,14 @@ EFI_STATUS (EFIAPI *EFI_TCP4_TRANSMIT)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_IO_TOKEN *Token - ) -; + ); /** Places an asynchronous receive request into the receiving queue. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param Token Pointer to a token that is associated with the receive data + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param Token The pointer to a token that is associated with the receive data descriptor. @retval EFI_SUCCESS The receive completion token was cached. @@ -401,15 +467,14 @@ EFI_STATUS (EFIAPI *EFI_TCP4_RECEIVE)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_IO_TOKEN *Token - ) -; + ); /** Disconnecting a TCP connection gracefully or reset a TCP connection. This function is a nonblocking operation. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param CloseToken Pointer to the close token to return when operation finishes. + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param CloseToken The pointer to the close token to return when operation finishes. @retval EFI_SUCCESS The Close() is called successfully. @retval EFI_NOT_STARTED This EFI TCPv4 Protocol instance has not been configured. @@ -432,14 +497,13 @@ EFI_STATUS (EFIAPI *EFI_TCP4_CLOSE)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_CLOSE_TOKEN *CloseToken - ) -; + ); /** Abort an asynchronous connection, listen, transmission or receive request. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. - @param Token Pointer to a token that has been issued by + @param This The pointer to the EFI_TCP4_PROTOCOL instance. + @param Token The pointer to a token that has been issued by EFI_TCP4_PROTOCOL.Connect(), EFI_TCP4_PROTOCOL.Accept(), EFI_TCP4_PROTOCOL.Transmit() or @@ -448,12 +512,16 @@ EFI_STATUS EFI_TCP4_COMPLETION_TOKEN is defined in EFI_TCP4_PROTOCOL.Connect(). - @retval EFI_SUCCESS Incoming or outgoing data was processed. - @retval EFI_INVALID_PARAMETER This is NULL. - @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. - @retval EFI_NOT_READY No incoming or outgoing data is processed. - @retval EFI_TIMEOUT Data was dropped out of the transmission or receive queue. - Consider increasing the polling rate. + @retval EFI_SUCCESS The asynchronous I/O request is aborted and Token->Event + is signaled. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_NOT_STARTED This instance hasn't been configured. + @retval EFI_NO_MAPPING When using the default address, configuration + (DHCP, BOOTP,RARP, etc.) hasn't finished yet. + @retval EFI_NOT_FOUND The asynchronous I/O request isn't found in the + transmission or receive queue. It has either + completed or wasn't issued by Transmit() and Receive(). + @retval EFI_UNSUPPORTED The implementation does not support this function. **/ typedef @@ -461,14 +529,13 @@ EFI_STATUS (EFIAPI *EFI_TCP4_CANCEL)( IN EFI_TCP4_PROTOCOL *This, IN EFI_TCP4_COMPLETION_TOKEN *Token OPTIONAL - ) -; + ); /** Poll to receive incoming data and transmit outgoing segments. - @param This Pointer to the EFI_TCP4_PROTOCOL instance. + @param This The pointer to the EFI_TCP4_PROTOCOL instance. @retval EFI_SUCCESS Incoming or outgoing data was processed. @retval EFI_INVALID_PARAMETER This is NULL. @@ -482,9 +549,15 @@ typedef EFI_STATUS (EFIAPI *EFI_TCP4_POLL)( IN EFI_TCP4_PROTOCOL *This - ) -; - + ); + +/// +/// The EFI_TCP4_PROTOCOL defines the EFI TCPv4 Protocol child to be used by +/// any network drivers or applications to send or receive data stream. +/// It can either listen on a specified port as a service or actively connected +/// to remote peer as a client. Each instance has its own independent settings, +/// such as the routing table. +/// struct _EFI_TCP4_PROTOCOL { EFI_TCP4_GET_MODE_DATA GetModeData; EFI_TCP4_CONFIGURE Configure; @@ -498,10 +571,6 @@ struct _EFI_TCP4_PROTOCOL { EFI_TCP4_POLL Poll; }; -#define EFI_CONNECTION_FIN EFIERR (104) -#define EFI_CONNECTION_RESET EFIERR (105) -#define EFI_CONNECTION_REFUSED EFIERR (106) - extern EFI_GUID gEfiTcp4ServiceBindingProtocolGuid; extern EFI_GUID gEfiTcp4ProtocolGuid;