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`	`OnAcceptErrorFunct` The endpoint's connection acceptance event handling function delegate.
`OnConnectComplete`	`OnConnectCompleteFunct` The endpoint's connection establishment event handling function delegate.
`OnConnectionClosed`	`OnConnectionClosedFunct` The endpoint's close event handling function delegate.
`OnConnectionReceived`	`OnConnectionReceivedFunct` The endpoint's connection receive event handling function delegate.
`OnDataReceived`	`OnDataReceivedFunct` The endpoint's message text reception event handling function delegate.
`OnDataSent`	`OnDataSentFunct` The endpoint's message text transmission event handling function delegate.
`OnPeerClose`	`OnPeerCloseFunct` The endpoint's half-close receive event handling function delegate.
`OnTCPSendIdleChanged`	`OnTCPSendIdleChangedFunct` 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)`	`INET_ERROR` Acknowledge receipt of message text.
`Bind(IPAddressType addrType, IPAddress addr, uint16_t port, bool reuseAddr)`	`INET_ERROR` Bind the endpoint to an interface IP address.
`Close(void)`	`INET_ERROR` Initiate TCP full close, in other words, finished with both send and receive.
`Connect(IPAddress addr, uint16_t port, InterfaceId intf)`	`INET_ERROR` Initiate a TCP connection.
`DisableKeepAlive(void)`	`INET_ERROR` Disable the TCP "keep-alive" option.
`DisableReceive(void)`	`void` Disable reception.
`EnableKeepAlive(uint16_t interval, uint16_t timeoutCount)`	`INET_ERROR` Enable the TCP "keep-alive" option.
`EnableNoDelay(void)`	`INET_ERROR` EnableNoDelay.
`EnableReceive(void)`	`void` Enable reception.
`Free(void)`	`void` Initiate (or continue) TCP full close, ignoring errors.
`GetLocalInfo(IPAddress retAddr, uint16_t retPort)`	`INET_ERROR` Extract IP address and TCP port of local endpoint.
`GetPeerInfo(IPAddress retAddr, uint16_t retPort) const`	`INET_ERROR` Extract IP address and TCP port of remote endpoint.
`IsConnected(void) const`	`bool` Extract whether TCP connection is established.
`Listen(uint16_t backlog)`	`INET_ERROR` 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)`	`INET_ERROR` Push message text back to the head of the receive queue.
`Send(Weave::System::PacketBuffer *data, bool push)`	`INET_ERROR` 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)`	`INET_ERROR` Set the TCP TCP_USER_TIMEOUT socket option.
`Shutdown(void)`	`INET_ERROR` 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.

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