nl::Inet::TCPEndPoint

#include <src/inet/TCPEndPoint.h>

Objects of this class represent TCP transport endpoints.

Summary

Nest Inet Layer encapsulates methods for interacting with TCP transport endpoints (SOCK_STREAM sockets on Linux and BSD-derived systems) or LwIP TCP protocol control blocks, as the system is configured accordingly.

Inheritance

Inherits from: nl::Inet::EndPointBasis

Public types

@10{
  kState_Ready = kBasisState_Closed,
  kState_Bound = 1,
  kState_Listening = 2,
  kState_Connecting = 3,
  kState_Connected = 4,
  kState_SendShutdown = 5,
  kState_ReceiveShutdown = 6,
  kState_Closing = 7,
  kState_Closed = 8
}
enum
Basic dynamic state of the underlying endpoint.
OnAcceptErrorFunct)(TCPEndPoint *endPoint, INET_ERROR err) typedef
void(*
Type of connection acceptance error event handling function.
OnConnectCompleteFunct)(TCPEndPoint *endPoint, INET_ERROR err) typedef
void(*
Type of connection establishment event handling function.
OnConnectionClosedFunct)(TCPEndPoint *endPoint, INET_ERROR err) typedef
void(*
Type of connection establishment event handling function.
OnConnectionReceivedFunct)(TCPEndPoint *listeningEndPoint, TCPEndPoint *conEndPoint, const IPAddress &peerAddr, uint16_t peerPort) typedef
void(*
Type of connection received event handling function.
OnDataReceivedFunct)(TCPEndPoint *endPoint, Weave::System::PacketBuffer *data) typedef
void(*
Type of data reception event handling function.
OnDataSentFunct)(TCPEndPoint *endPoint, uint16_t len) typedef
void(*
Type of data transmission event handling function.
OnPeerCloseFunct)(TCPEndPoint *endPoint) typedef
void(*
Type of half-close reception event handling function.
OnTCPSendIdleChangedFunct)(TCPEndPoint *endPoint, bool isIdle) typedef
void(*
Type of TCP SendIdle changed signal handling function.

Public attributes

OnAcceptError
The endpoint's connection acceptance event handling function delegate.
OnConnectComplete
The endpoint's connection establishment event handling function delegate.
OnConnectionClosed
The endpoint's close event handling function delegate.
OnConnectionReceived
The endpoint's connection receive event handling function delegate.
OnDataReceived
The endpoint's message text reception event handling function delegate.
OnDataSent
The endpoint's message text transmission event handling function delegate.
OnPeerClose
The endpoint's half-close receive event handling function delegate.
OnTCPSendIdleChanged
The event handling function delegate of the endpoint signaling when the idleness of the TCP connection's send channel changes.
ReceiveEnabled
bool
Control switch indicating whether the application is receiving data.
State
enum nl::Inet::TCPEndPoint::@10
Basic dynamic state of the underlying endpoint.

Public functions

Abort(void)
void
Abortively close the endpoint, in other words, send RST packets.
AckReceive(uint16_t len)
Acknowledge receipt of message text.
Bind(IPAddressType addrType, IPAddress addr, uint16_t port, bool reuseAddr)
Bind the endpoint to an interface IP address.
Close(void)
Initiate TCP full close, in other words, finished with both send and receive.
Connect(IPAddress addr, uint16_t port, InterfaceId intf)
Initiate a TCP connection.
DisableKeepAlive(void)
Disable the TCP "keep-alive" option.
DisableReceive(void)
void
Disable reception.
EnableKeepAlive(uint16_t interval, uint16_t timeoutCount)
Enable the TCP "keep-alive" option.
EnableNoDelay(void)
EnableNoDelay.
EnableReceive(void)
void
Enable reception.
Free(void)
void
Initiate (or continue) TCP full close, ignoring errors.
GetLocalInfo(IPAddress *retAddr, uint16_t *retPort)
Extract IP address and TCP port of local endpoint.
GetPeerInfo(IPAddress *retAddr, uint16_t *retPort) const
Extract IP address and TCP port of remote endpoint.
IsConnected(void) const
bool
Extract whether TCP connection is established.
Listen(uint16_t backlog)
Prepare the endpoint to receive TCP messages.
LogId(void)
uint16_t
Obtain an identifier for the endpoint.
MarkActive(void)
void
Note activity, in other words, reset the idle timer.
PendingReceiveLength(void)
uint32_t
Extract the length of the unacknowledged receive data.
PendingSendLength(void)
uint32_t
Extract the length of the data awaiting first transmit.
PutBackReceivedData(Weave::System::PacketBuffer *data)
Push message text back to the head of the receive queue.
Send(Weave::System::PacketBuffer *data, bool push)
Send message text on TCP connection.
SetConnectTimeout(const uint32_t connTimeoutMsecs)
void
Set timeout for Connect to succeed or return an error.
SetUserTimeout(uint32_t userTimeoutMillis)
Set the TCP TCP_USER_TIMEOUT socket option.
Shutdown(void)
Initiate TCP half close, in other words, finished with sending.

Public types

@10

 @10

Basic dynamic state of the underlying endpoint.

Objects are initialized in the "ready" state, proceed to subsequent states corresponding to a simplification of the states of the TCP transport state machine.

Note:The kBasisState_Closed state enumeration is mapped to kState_Ready for historical binary-compatibility reasons. The existing kState_Closed exists to identify separately the distinction between "not opened yet" and "previously opened now closed" that existed previously in the kState_Ready and kState_Closed states.

Properties
kState_Bound

Endpoint bound, but not listening.

kState_Closed

Endpoint closed, ready for release.

kState_Closing

Endpoint closing bidirectionally.

kState_Connected

Endpoint connected, ready for tx/rx.

kState_Connecting

Endpoint attempting to connect.

kState_Listening

Endpoint receiving connections.

kState_Ready

Endpoint initialized, but not bound.

kState_ReceiveShutdown

Endpoint responded to half-close.

kState_SendShutdown

Endpoint initiated its half-close.

OnAcceptErrorFunct

void(* OnAcceptErrorFunct)(TCPEndPoint *endPoint, INET_ERROR err)

Type of connection acceptance error event handling function.

Provide a function of this type to the OnAcceptError delegate member to process connection acceptance error events on endPoint. The err argument provides specific detail about the type of the error.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.
[in] err
The reason for the error.

OnConnectCompleteFunct

void(* OnConnectCompleteFunct)(TCPEndPoint *endPoint, INET_ERROR err)

Type of connection establishment event handling function.

Provide a function of this type to the OnConnectComplete delegate member to process connection establishment events on endPoint. The err argument distinguishes successful connections from failures.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.
[in] err
INET_NO_ERROR if success, else another code.

OnConnectionClosedFunct

void(* OnConnectionClosedFunct)(TCPEndPoint *endPoint, INET_ERROR err)

Type of connection establishment event handling function.

Provide a function of this type to the OnConnectionClosed delegate member to process connection termination events on endPoint. The err argument distinguishes successful terminations from failures.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.
[in] err
INET_NO_ERROR if success, else another code.

OnConnectionReceivedFunct

void(* OnConnectionReceivedFunct)(TCPEndPoint *listeningEndPoint, TCPEndPoint *conEndPoint, const IPAddress &peerAddr, uint16_t peerPort)

Type of connection received event handling function.

Provide a function of this type to the OnConnectionReceived delegate member to process connection reception events on listeningEndPoint. The newly received endpoint conEndPoint is located at IP address peerAddr and TCP port peerPort.

Details
Parameters
[in] listeningEndPoint
The listening TCP endpoint.
[in] conEndPoint
The newly received TCP endpoint.
[in] peerAddr
The IP address of the remote peer.
[in] peerPort
The TCP port of the remote peer.

OnDataReceivedFunct

void(* OnDataReceivedFunct)(TCPEndPoint *endPoint, Weave::System::PacketBuffer *data)

Type of data reception event handling function.

Provide a function of this type to the OnDataReceived delegate member to process data reception events on endPoint where data is the message text received.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.
[in] data
The data received.

A data reception event handler must acknowledge data processed using the AckReceive method. The Free method on the data buffer must also be invoked unless the PutBackReceivedData is used instead.

OnDataSentFunct

void(* OnDataSentFunct)(TCPEndPoint *endPoint, uint16_t len)

Type of data transmission event handling function.

Provide a function of this type to the OnDataSent delegate member to process data transmission events on endPoint where len is the length of the message text added to the TCP transmit window, which are eligible for sending by the underlying network stack.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.
[in] len
Number of bytes added to the transmit window.

OnPeerCloseFunct

void(* OnPeerCloseFunct)(TCPEndPoint *endPoint)

Type of half-close reception event handling function.

Provide a function of this type to the OnPeerClose delegate member to process connection termination events on endPoint.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.

OnTCPSendIdleChangedFunct

void(* OnTCPSendIdleChangedFunct)(TCPEndPoint *endPoint, bool isIdle)

Type of TCP SendIdle changed signal handling function.

Provide a function of this type to the OnTCPSendIdleChanged delegate member to process the event of the send channel of the TCPEndPoint changing state between being idle and not idle.

Details
Parameters
[in] endPoint
The TCP endpoint associated with the event.
[in] isIdle
True if the send channel of the TCP endpoint is Idle, otherwise false.

Public attributes

OnAcceptError

OnAcceptErrorFunct OnAcceptError

The endpoint's connection acceptance event handling function delegate.

OnConnectComplete

OnConnectCompleteFunct OnConnectComplete

The endpoint's connection establishment event handling function delegate.

OnConnectionClosed

OnConnectionClosedFunct OnConnectionClosed

The endpoint's close event handling function delegate.

OnConnectionReceived

OnConnectionReceivedFunct OnConnectionReceived

The endpoint's connection receive event handling function delegate.

OnDataReceived

OnDataReceivedFunct OnDataReceived

The endpoint's message text reception event handling function delegate.

OnDataSent

OnDataSentFunct OnDataSent

The endpoint's message text transmission event handling function delegate.

OnPeerClose

OnPeerCloseFunct OnPeerClose

The endpoint's half-close receive event handling function delegate.

OnTCPSendIdleChanged

OnTCPSendIdleChangedFunct OnTCPSendIdleChanged

The event handling function delegate of the endpoint signaling when the idleness of the TCP connection's send channel changes.

This is utilized by upper layers to take appropriate actions based on whether sent data has been reliably delivered to the peer.

ReceiveEnabled

bool ReceiveEnabled

Control switch indicating whether the application is receiving data.

State

enum nl::Inet::TCPEndPoint::@10 State

Basic dynamic state of the underlying endpoint.

Objects are initialized in the "ready" state, proceed to subsequent states corresponding to a simplification of the states of the TCP transport state machine.

Note:The kBasisState_Closed state enumeration is mapped to kState_Ready for historical binary-compatibility reasons. The existing kState_Closed exists to identify separately the distinction between "not opened yet" and "previously opened now closed" that existed previously in the kState_Ready and kState_Closed states.

Public functions

Abort

void Abort(
  void
)

Abortively close the endpoint, in other words, send RST packets.

AckReceive

INET_ERROR AckReceive(
  uint16_t len
)

Acknowledge receipt of message text.

Use this method to acknowledge reception of all or part of the data received. The operational semantics are undefined if len is larger than the total outstanding unacknowledged received data.

Details
Parameters
[in] len
number of bytes to acknowledge.
Return Values
INET_NO_ERROR
success: reception acknowledged.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
INET_ERROR_CONNECTION_ABORTED
TCP connection no longer open.

Bind

INET_ERROR Bind(
  IPAddressType addrType,
  IPAddress addr,
  uint16_t port,
  bool reuseAddr
)

Bind the endpoint to an interface IP address.

Binds the endpoint to the specified network interface IP address.

Details
Parameters
[in] addrType
the protocol version of the IP address
[in] addr
the IP address (must be an interface address)
[in] port
the TCP port
[in] reuseAddr
option to share binding with other endpoints
Return Values
INET_NO_ERROR
success: endpoint bound to address
INET_ERROR_INCORRECT_STATE
endpoint has been bound previously
INET_NO_MEMORY
insufficient memory for endpoint
INET_ERROR_WRONG_PROTOCOL_TYPE
addrType does not match IPVer.
INET_ERROR_WRONG_ADDRESS_TYPE
addrType is kIPAddressType_Any, or the type of addr is not equal to addrType.
other
another system or platform error

On LwIP, this method must not be called with the LwIP stack lock already acquired.

Close

INET_ERROR Close(
  void
)

Initiate TCP full close, in other words, finished with both send and receive.

Details
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
other
another system or platform error

Connect

INET_ERROR Connect(
  IPAddress addr,
  uint16_t port,
  InterfaceId intf
)

Initiate a TCP connection.

 If possible, then this method initiates a TCP connection to the
 destination \c addr (with \c intf used as the scope
 identifier for IPv6 link-local destinations) and \c port.

Details
Parameters
[in] addr
the destination IP address
[in] port
the destination TCP port
[in] intf
an optional network interface indicator
Return Values
INET_NO_ERROR
success: msg is queued for transmit.
INET_ERROR_NOT_IMPLEMENTED
system implementation not complete.
INET_ERROR_WRONG_ADDRESS_TYPE
the destination address and the bound interface address do not have matching protocol versions or address type, or the destination address is an IPv6 link-local address and intf is not specified.
other
another system or platform error

DisableKeepAlive

INET_ERROR DisableKeepAlive(
  void
)

Disable the TCP "keep-alive" option.

TCPEndPoint::DisableKeepAlive.

Disable TCP keepalive probes on the associated TCP connection.

Details
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
INET_ERROR_CONNECTION_ABORTED
TCP connection no longer open.
INET_ERROR_NOT_IMPLEMENTED
system implementation not complete.
other
another system or platform error

Note:This method can only be called when the endpoint is in one of the connected states. This method does nothing if keepalives have not been enabled on the endpoint.

DisableReceive

void DisableReceive(
  void
)

Disable reception.

Disable all event handlers. Data sent to an endpoint that disables reception will be acknowledged until the receive window is exhausted.

EnableKeepAlive

INET_ERROR EnableKeepAlive(
  uint16_t interval,
  uint16_t timeoutCount
)

Enable the TCP "keep-alive" option.

TCPEndPoint::EnableKeepAlive.

Start automatically transmitting TCP "keep-alive" probe segments every interval seconds. The connection will abort automatically after receiving a negative response, or after sending timeoutCount probe segments without receiving a positive response.

Details
Parameters
[in] interval
time in seconds between probe requests.
[in] timeoutCount
number of probes to send before timeout.
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
INET_ERROR_CONNECTION_ABORTED
TCP connection no longer open.
INET_ERROR_NOT_IMPLEMENTED
system implementation not complete.
other
another system or platform error

See RFC 1122, section 4.2.3.6 for specification details.

Enable TCP keepalive probes on the associated TCP connection.

Note:This method can only be called when the endpoint is in one of the connected states. This method can be called multiple times to adjust the keepalive interval or timeout count.

Details
Parameters
interval
The interval (in seconds) between keepalive probes. This value also controls the time between last data packet sent and the transmission of the first keepalive probe.
timeoutCount
The maximum number of unacknowledged probes before the connection will be deemed to have failed.

EnableNoDelay

INET_ERROR EnableNoDelay(
  void
)

EnableNoDelay.

TCPEndPoint::EnableNoDelay.

Switch off nagle buffering algorithm in TCP by setting the TCP_NODELAY socket options.

EnableReceive

void EnableReceive(
  void
)

Enable reception.

Enable all event handlers. Data sent to an endpoint that disables reception will be acknowledged until the receive window is exhausted.

Free

void Free(
  void
)

Initiate (or continue) TCP full close, ignoring errors.

The object is returned to the free pool, and all remaining user references are subsequently invalid.

GetLocalInfo

INET_ERROR GetLocalInfo(
  IPAddress *retAddr,
  uint16_t *retPort
)

Extract IP address and TCP port of local endpoint.

Do not use NULL pointer values for either argument.

Details
Parameters
[out] retAddr
IP address of local endpoint.
[out] retPort
TCP port of local endpoint.
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
INET_ERROR_CONNECTION_ABORTED
TCP connection no longer open.

GetPeerInfo

INET_ERROR GetPeerInfo(
  IPAddress *retAddr,
  uint16_t *retPort
) const 

Extract IP address and TCP port of remote endpoint.

Do not use NULL pointer values for either argument.

Details
Parameters
[out] retAddr
IP address of remote endpoint.
[out] retPort
TCP port of remote endpoint.
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
INET_ERROR_CONNECTION_ABORTED
TCP connection no longer open.

IsConnected

bool IsConnected(
  void
) const 

Extract whether TCP connection is established.

Listen

INET_ERROR Listen(
  uint16_t backlog
)

Prepare the endpoint to receive TCP messages.

If State is already kState_Listening, then no operation is performed, otherwise the State is set to kState_Listening and the endpoint is prepared to received TCP messages, according to the semantics of the platform.

Details
Parameters
[in] backlog
maximum depth of connection acceptance queue
Return Values
INET_NO_ERROR
success: endpoint ready to receive messages.
INET_ERROR_INCORRECT_STATE
endpoint is already listening.

On some platforms, the backlog argument is not used (the depth of the queue is fixed; only one connection may be accepted at a time).

On LwIP systems, this method must not be called with the LwIP stack lock already acquired

LogId

uint16_t LogId(
  void
)

Obtain an identifier for the endpoint.

Details
Returns
Returns an opaque unique identifier for use logs.

MarkActive

void MarkActive(
  void
)

Note activity, in other words, reset the idle timer.

Reset the idle timer to zero.

PendingReceiveLength

uint32_t PendingReceiveLength(
  void
)

Extract the length of the unacknowledged receive data.

Details
Returns
Number of bytes in the receive queue that have not yet been acknowledged with AckReceive(uint16_t len).

PendingSendLength

uint32_t PendingSendLength(
  void
)

Extract the length of the data awaiting first transmit.

Details
Returns
Number of untransmitted bytes in the transmit queue.

PutBackReceivedData

INET_ERROR PutBackReceivedData(
  Weave::System::PacketBuffer *data
)

Push message text back to the head of the receive queue.

This method may only be called by data reception event handlers to put an unacknowledged portion of data back on the receive queue. The operational semantics are undefined if the caller is outside the scope of a data reception event handler, data is not the Weave::System::PacketBuffer provided to the handler, or data does not contain the unacknowledged portion remaining after the bytes acknowledged by a prior call to the AckReceive(uint16_t len) method.

Details
Parameters
[out] data
Message text to push.
Return Values
INET_NO_ERROR
success: reception acknowledged.
INET_ERROR_INCORRECT_STATE
TCP connection not established.

Send

INET_ERROR Send(
  Weave::System::PacketBuffer *data,
  bool push
)

Send message text on TCP connection.

The Weave::System::PacketBuffer::Free method is called on the data argument regardless of whether the transmission is successful or failed.

Details
Parameters
[out] data
Message text to send.
[out] push
If true, then send immediately, otherwise queue.
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.

SetConnectTimeout

void SetConnectTimeout(
  const uint32_t connTimeoutMsecs
)

Set timeout for Connect to succeed or return an error.

Details
Parameters
[in] connTimeoutMsecs

SetUserTimeout

INET_ERROR SetUserTimeout(
  uint32_t userTimeoutMillis
)

Set the TCP TCP_USER_TIMEOUT socket option.

TCPEndPoint::SetUserTimeout.

When the value is greater than 0, it specifies the maximum amount of time in milliseconds that transmitted data may remain unacknowledged before TCP will forcibly close the corresponding connection. If the option value is specified as 0, TCP will to use the system default. See RFC 5482, for further details.

Details
Parameters
[in] userTimeoutMillis
Tcp user timeout value in milliseconds.
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_NOT_IMPLEMENTED
system implementation not complete.
other
another system or platform error

Set the TCP user timeout socket option.

When the value is greater than 0, it specifies the maximum amount of time in milliseconds that transmitted data may remain unacknowledged before TCP will forcibly close the corresponding connection. If the option value is specified as 0, TCP will use the system default. See RFC 5482, for further details.

Note:This method can only be called when the endpoint is in one of the connected states. This method can be called multiple times to adjust the keepalive interval or timeout count.

Shutdown

INET_ERROR Shutdown(
  void
)

Initiate TCP half close, in other words, finished with sending.

Details
Return Values
INET_NO_ERROR
success: address and port extracted.
INET_ERROR_INCORRECT_STATE
TCP connection not established.
other
another system or platform error