nl::Weave::WeaveConnection

#include <src/lib/core/WeaveMessageLayer.h>

The definition of the Weave Connection class.

Summary

It represents a TCP or BLE connection to another Weave node.

Public types
`@58{ kGetPeerDescription_MaxLength = nl::Weave::kWeavePeerDescription_MaxLength }`	enum
`ConnectionClosedFunct)(WeaveConnection *con, WEAVE_ERROR conErr)`	typedef `void(*` This function is the application callback that is invoked when a connection is closed.
`ConnectionCompleteFunct)(WeaveConnection *con, WEAVE_ERROR conErr)`	typedef `void(*` This function is the application callback that is invoked when a connection setup is complete.
`MessageReceiveFunct)(WeaveConnection con, WeaveMessageInfo msgInfo, PacketBuffer *msgBuf)`	typedef `void(*` This function is the application callback that is invoked when a message is received over a Weave connection.
`NetworkType{ kNetworkType_Unassigned = 0, kNetworkType_IP = 1, kNetworkType_BLE = 2 }`	enum The network type of the Weave connection object.
`ReceiveErrorFunct)(WeaveConnection *con, WEAVE_ERROR err)`	typedef `void(*` This function is the application callback invoked upon encountering an error when receiving a Weave message.
`State{ kState_ReadyToConnect = 0, kState_Resolving = 1, kState_Connecting = 2, kState_EstablishingSession = 3, kState_Connected = 4, kState_SendShutdown = 5, kState_Closed = 6 }`	enum The State of the Weave connection object.
`TunneledMsgReceiveFunct)(WeaveConnection con, const WeaveMessageInfo msgInfo, PacketBuffer *msgBuf)`	typedef `void(*` This function is the application callback that is invoked upon receipt of a Tunneled data packet over the Weave connection.

Public attributes
`AppState`	`void *` A pointer to the application-specific state object.
`AuthMode`	`WeaveAuthMode` [READ ONLY] The authentication mode used to establish the default encryption keys for the connection.
`DefaultEncryptionType`	`uint8_t` The default encryption type for messages.
`DefaultKeyId`	`uint16_t` The default encryption key to use when sending messages.
`MessageLayer`	`WeaveMessageLayer *` [READ ONLY] The associated WeaveMessageLayer object.
`NetworkType`	`uint8_t` [READ ONLY] The network type of the associated end point.
`OnConnectionClosed`	`ConnectionClosedFunct`
`OnConnectionComplete`	`ConnectionCompleteFunct`
`OnMessageReceived`	`MessageReceiveFunct`
`OnReceiveError`	`ReceiveErrorFunct`
`OnTunneledMessageReceived`	`TunneledMsgReceiveFunct`
`PeerAddr`	`IPAddress` [READ ONLY] The IP address of the peer node.
`PeerNodeId`	`uint64_t` [READ ONLY] The node identifier of the peer.
`PeerPort`	`uint16_t` [READ ONLY] The port number of the peer node.
`ReceiveEnabled`	`bool` [READ ONLY] True if receiving is enabled, false otherwise.
`SendDestNodeId`	`bool` True if all messages sent via this connection must include an explicitly encoded destination node identifier, false otherwise.
`SendSourceNodeId`	`bool` True if all messages sent via this connection must include an explicitly encoded source node identifier, false otherwise.
`State`	`uint8_t` [READ ONLY] The state of the WeaveConnection object.

Public functions
`Abort(void)`	`void` Performs an un-graceful close of the TCP- or BLE-based WeaveConnection, discarding any data that might be in flight to or from the peer.
`AddRef(void)`	`void` Reserve a reference to the WeaveConnection object.
`Close(void)`	`WEAVE_ERROR` Performs a non-blocking graceful close of the TCP- or BLE-based WeaveConnection, delivering any remaining outgoing data before politely informing the remote host that we have reset the connection.
`Close(bool suppressCloseLog)`	`WEAVE_ERROR` Performs a non-blocking graceful close of the TCP- or BLE-based WeaveConnection, delivering any remaining outgoing data before politely informing the remote host that we have reset the connection.
`Connect(uint64_t peerNodeId)`	`WEAVE_ERROR` Connect to a Weave node using a fabric IP address derived from the specified node identifier.
`Connect(uint64_t peerNodeId, const IPAddress & peerAddr, uint16_t peerPort)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or an IP address.
`Connect(uint64_t peerNodeId, WeaveAuthMode authMode, const IPAddress & peerAddr, uint16_t peerPort, InterfaceId intf)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or an IP address on a specific interface.
`Connect(uint64_t peerNodeId, WeaveAuthMode authMode, const char *peerAddr, uint16_t defaultPort)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or a string host name.
`Connect(uint64_t peerNodeId, WeaveAuthMode authMode, const char *peerAddr, uint16_t peerAddrLen, uint16_t defaultPort)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or a string peer address.
`Connect(uint64_t peerNodeId, WeaveAuthMode authMode, const char *peerAddr, uint16_t peerAddrLen, uint8_t dnsOptions, uint16_t defaultPort)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or a string peer address.
`Connect(uint64_t peerNodeId, WeaveAuthMode authMode, HostPortList hostPortList, InterfaceId intf)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or a list of hostname and ports.
`Connect(uint64_t peerNodeId, WeaveAuthMode authMode, HostPortList hostPortList, uint8_t dnsOptions, InterfaceId intf)`	`WEAVE_ERROR` Connect to a Weave node using a node identifier and/or a list of hostname and ports.
`DisableKeepAlive(void)`	`WEAVE_ERROR` WeaveConnection::DisableKeepAlive.
`DisableReceive(void)`	`void` Disable receiving over this WeaveConnection.
`EnableKeepAlive(uint16_t interval, uint16_t timeoutCount)`	`WEAVE_ERROR` WeaveConnection::EnableKeepAlive.
`EnableReceive(void)`	`void` Enable receiving over this WeaveConnection.
`GetPeerAddressInfo(IPPacketInfo & addrInfo)`	`WEAVE_ERROR` Get the IP address information of the peer.
`GetPeerDescription(char *buf, size_t bufSize) const`	`void` Constructs a string describing the peer node associated with the connection.
`GetTCPEndPoint(void) const`	`TCPEndPoint *`
`IsIncoming(void) const`	`bool`
`LogId(void) const`	`uint16_t`
`Release(void)`	`void` Decrement the reference count on the WeaveConnection object.
`ResetUserTimeout(void)`	`WEAVE_ERROR` WeaveConnection::ResetUserTimeout.
`SendMessage(WeaveMessageInfo msgInfo, PacketBuffer msgBuf)`	`WEAVE_ERROR` Send a Weave message over an established connection.
`SendTunneledMessage(WeaveMessageInfo msgInfo, PacketBuffer msgBuf)`	`WEAVE_ERROR` Function to send a Tunneled packet over a Weave connection.
`SetConnectTimeout(const uint32_t connTimeoutMsecs)`	`void` Set timeout for Connect to succeed or return an error.
`SetIdleTimeout(uint32_t timeoutMS)`	`WEAVE_ERROR` Set the idle timeout on the underlying network layer connection.
`SetIncoming(bool val)`	`void`
`SetUserTimeout(uint32_t userTimeoutMillis)`	`WEAVE_ERROR` WeaveConnection::SetUserTimeout.
`Shutdown(void)`	`WEAVE_ERROR` Performs a graceful TCP send-shutdown, ensuring all outgoing data has been sent and received by the peer's TCP stack.

Public types

@58

@58

Properties
`kGetPeerDescription_MaxLength`	Maximum length of string (including NUL character) returned by GetPeerDescription().

ConnectionClosedFunct

void(* ConnectionClosedFunct)(WeaveConnection *con, WEAVE_ERROR conErr)

This function is the application callback that is invoked when a connection is closed.

Details

Parameters

`[in] con`	A pointer to the WeaveConnection object.
`[in] conErr`	The WEAVE_ERROR encountered when the connection was closed.

ConnectionCompleteFunct

void(* ConnectionCompleteFunct)(WeaveConnection *con, WEAVE_ERROR conErr)

This function is the application callback that is invoked when a connection setup is complete.

Details

Parameters

`[in] con`	A pointer to the WeaveConnection object.
`[in] conErr`	The WEAVE_ERROR encountered during connection setup.

MessageReceiveFunct

void(* MessageReceiveFunct)(WeaveConnection *con, WeaveMessageInfo *msgInfo, PacketBuffer *msgBuf)

This function is the application callback that is invoked when a message is received over a Weave connection.

Details

Parameters

`[in] con`	A pointer to the WeaveConnection object.
`[in] msgInfo`	A pointer to a WeaveMessageInfo structure containing information about the message.
`[in] msgBuf`	A pointer to the PacketBuffer object holding the message.

NetworkType

 NetworkType

The network type of the Weave connection object.

Properties
`kNetworkType_BLE`	BLE network type.
`kNetworkType_IP`	TCP/IP network type.
`kNetworkType_Unassigned`	Unassigned network type.

ReceiveErrorFunct

void(* ReceiveErrorFunct)(WeaveConnection *con, WEAVE_ERROR err)

This function is the application callback invoked upon encountering an error when receiving a Weave message.

Details

Parameters

`[in] con`	A pointer to the WeaveConnection object.
`[in] err`	The WEAVE_ERROR encountered when receiving data over the connection.

State

 State

The State of the Weave connection object.

Properties
`kState_Closed`	State when the connection is closed.
`kState_Connected`	State when the connection has been established.
`kState_Connecting`	State when connection is being attempted.
`kState_EstablishingSession`	State when a secure session is being established.
`kState_ReadyToConnect`	State after initialization of the Weave connection.
`kState_Resolving`	State when DNS name resolution is being performed.
`kState_SendShutdown`	State when the connection is being shut down.

TunneledMsgReceiveFunct

void(* TunneledMsgReceiveFunct)(WeaveConnection *con, const WeaveMessageInfo *msgInfo, PacketBuffer *msgBuf)

This function is the application callback that is invoked upon receipt of a Tunneled data packet over the Weave connection.

Details

Parameters

`[in] con`	A pointer to the WeaveConnection object.
`[in] msgInfo`	A pointer to the WeaveMessageInfo object.
`[in] msgBuf`	A pointer to the PacketBuffer object containing the tunneled packet received.

Public attributes

AppState

void * AppState

A pointer to the application-specific state object.

AuthMode

WeaveAuthMode AuthMode

[READ ONLY] The authentication mode used to establish the default encryption keys for the connection.

DefaultEncryptionType

uint8_t DefaultEncryptionType

The default encryption type for messages.

DefaultKeyId

uint16_t DefaultKeyId

The default encryption key to use when sending messages.

MessageLayer

WeaveMessageLayer * MessageLayer

[READ ONLY] The associated WeaveMessageLayer object.

NetworkType

uint8_t NetworkType

[READ ONLY] The network type of the associated end point.

OnConnectionClosed

ConnectionClosedFunct OnConnectionClosed

OnConnectionComplete

ConnectionCompleteFunct OnConnectionComplete

OnMessageReceived

MessageReceiveFunct OnMessageReceived

OnReceiveError

ReceiveErrorFunct OnReceiveError

OnTunneledMessageReceived

TunneledMsgReceiveFunct OnTunneledMessageReceived

PeerAddr

IPAddress PeerAddr

[READ ONLY] The IP address of the peer node.

PeerNodeId

uint64_t PeerNodeId

[READ ONLY] The node identifier of the peer.

PeerPort

uint16_t PeerPort

[READ ONLY] The port number of the peer node.

ReceiveEnabled

bool ReceiveEnabled

[READ ONLY] True if receiving is enabled, false otherwise.

SendDestNodeId

bool SendDestNodeId

True if all messages sent via this connection must include an explicitly encoded destination node identifier, false otherwise.

SendSourceNodeId

bool SendSourceNodeId

True if all messages sent via this connection must include an explicitly encoded source node identifier, false otherwise.

State

uint8_t State

[READ ONLY] The state of the WeaveConnection object.

Public functions

Abort

void Abort(
  void
)

Performs an un-graceful close of the TCP- or BLE-based WeaveConnection, discarding any data that might be in flight to or from the peer.

A call to Abort() immediately terminates the underlying connection. After this point, the WeaveConnection object can no longer be used for further communication.

Calling Abort() decrements the reference count associated with the WeaveConnection object, whether or not the connection is open/active at the time the method is called. If this results in the reference count reaching zero, the resources associated with the connection object are freed. When this happens, the application must have no further interactions with the object.

See also:
Shutdown(), Abort(), AddRef() and Release().

AddRef

void AddRef(
  void
)

Reserve a reference to the WeaveConnection object.

The AddRef() method increments the reference count associated with the WeaveConnection object. For every call to AddRef(), the application is responsible for making a corresponding call to either Release(), Close() or Abort().

Close

WEAVE_ERROR Close(
  void
)

Performs a non-blocking graceful close of the TCP- or BLE-based WeaveConnection, delivering any remaining outgoing data before politely informing the remote host that we have reset the connection.

This method provides no strong guarantee that any outgoing message not acknowledged at the application protocol level has been received by the remote peer. For both TCP and BLE, the underlying protocol stack will make a best-effort to deliver any pending outgoing data before resetting the connection. For TCP, Shutdown() should be used before Close() if a transport-layer message receipt confirmation is required before closing the connection. BLE connections provide no Shutdown() equivalent.

For BLE-based connections, Close() closes the WeaveConnection and returns immediately, but may cause the underlying BLEEndPoint object to linger until all outgoing data has been sent. This is a side effect of the Weave over BLE transport protocol implementation existing within the Weave BleLayer.

Once Close() has been called, the WeaveConnection object can no longer be used for further communication.

Calling Close() decrements the reference count associated with the WeaveConnection object, whether or not the connection is open/active at the time the method is called. If this results in the reference count reaching zero, the resources associated with the connection object are freed. When this happens, the application must have no further interactions with the object.

Details
Returns	WEAVE_NO_ERROR unconditionally.

See also:
Shutdown(), Abort(), AddRef() and Release().

Close

WEAVE_ERROR Close(
  bool suppressCloseLog
)

Performs a non-blocking graceful close of the TCP- or BLE-based WeaveConnection, delivering any remaining outgoing data before politely informing the remote host that we have reset the connection.

Once Close() has been called, the WeaveConnection object can no longer be used for further communication.

Details

Parameters

[in] suppressCloseLog

true if logs need to be suppressed, false otherwise.

Returns

WEAVE_NO_ERROR unconditionally.

See also:
Shutdown(), Abort(), AddRef() and Release().

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId
)

Connect to a Weave node using a fabric IP address derived from the specified node identifier.

Details

Parameters

[in] peerNodeId

The node identifier of the peer.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  const IPAddress & peerAddr,
  uint16_t peerPort
)

Connect to a Weave node using a node identifier and/or an IP address.

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer, kNodeIdNotSpecified or 0 if not known.
`[in] peerAddr`	The IP address of the peer, IPAddress::Any if not known.
`[in] peerPort`	The optional port of the peer, default to WEAVE_PORT.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  WeaveAuthMode authMode,
  const IPAddress & peerAddr,
  uint16_t peerPort,
  InterfaceId intf
)

Connect to a Weave node using a node identifier and/or an IP address on a specific interface.

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer, kNodeIdNotSpecified or 0 if not known.
`[in] authMode`	The desired authenticate mode for the peer. Only CASE, PASE and Unauthenticated modes are supported.
`[in] peerAddr`	The IP address of the peer, IPAddress::Any if not known.
`[in] peerPort`	The optional port of the peer, default to WEAVE_PORT.
`[in] intf`	The optional interface to use to connect to the peer node, default to INET_NULL_INTERFACEID.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node identifier.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  WeaveAuthMode authMode,
  const char *peerAddr,
  uint16_t defaultPort
)

Connect to a Weave node using a node identifier and/or a string host name.

If supplied, peerAddr can be any of:


:

:

[]:

Note: If is not supplied, defaultPort is used. If defaultPort is 0, the default WEAVE_PORT is used. If peerAddr is null, the node's fabric IP address will be derived from the peerNodeId field. If peerNodeId is kNodeIdNotSpecified (0), the node's identifier will be derived (if possible) from the peer's IP address.

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer, kNodeIdNotSpecified or 0 if not known.
`[in] authMode`	The desired authenticate mode for the peer. Only CASE, PASE and Unauthenticated modes are supported.
`[in] peerAddr`	The address or hostname of the peer as a NULL-terminated C string.
`[in] defaultPort`	The optional default port to use for the connection if not supplied in the peerAddr string.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  WeaveAuthMode authMode,
  const char *peerAddr,
  uint16_t peerAddrLen,
  uint16_t defaultPort
)

Connect to a Weave node using a node identifier and/or a string peer address.

If supplied, peerAddr can be any of:


:

:

[]:

Note: If is not supplied, defaultPort is used. If defaultPort is 0, the default Weave port is used. If peerAddr is null, the node's fabric IP address will be derived from the peerNodeId field. If peerNodeId is kNodeIdNotSpecified (0), the node's identifier will be derived (if possible) from the peer's IP address.

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer, kNodeIdNotSpecified or 0 if not known.
`[in] authMode`	The desired authenticate mode for the peer. Only CASE, PASE and Unauthenticated modes are supported.
`[in] peerAddr`	The address or hostname of the peer as a non-NULL-terminated C string.
`[in] peerAddrLen`	The length of the peerAddr string.
`[in] defaultPort`	The optional default port to use for the connection if not supplied in the peerAddr string.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  WeaveAuthMode authMode,
  const char *peerAddr,
  uint16_t peerAddrLen,
  uint8_t dnsOptions,
  uint16_t defaultPort
)

Connect to a Weave node using a node identifier and/or a string peer address.

If supplied, peerAddr can be any of:


:

:

[]:

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer, kNodeIdNotSpecified or 0 if not known.
`[in] authMode`	The desired authenticate mode for the peer. Only CASE, PASE and Unauthenticated modes are supported.
`[in] peerAddr`	The address or hostname of the peer as a non-NULL-terminated C string.
`[in] peerAddrLen`	The length of the peerAddr string.
`[in] dnsOptions`	An integer value controlling how host name resolution is performed. Value should be the OR of one or more values from from the #::nl::Inet::DNSOptions enumeration.
`[in] defaultPort`	The optional default port to use for the connection if not supplied in the peerAddr string.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  WeaveAuthMode authMode,
  HostPortList hostPortList,
  InterfaceId intf
)

Connect to a Weave node using a node identifier and/or a list of hostname and ports.

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer.
`[in] authMode`	The authentication mode used for the connection.
`[in] hostPortList`	The list of hostnames and ports.
`[in] intf`	The optional interface to use to connect to the peer node, default to INET_NULL_INTERFACEID.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

Connect

WEAVE_ERROR Connect(
  uint64_t peerNodeId,
  WeaveAuthMode authMode,
  HostPortList hostPortList,
  uint8_t dnsOptions,
  InterfaceId intf
)

Connect to a Weave node using a node identifier and/or a list of hostname and ports.

Details

Parameters

`[in] peerNodeId`	The node identifier of the peer.
`[in] authMode`	The authentication mode used for the connection.
`[in] hostPortList`	The list of hostnames and ports.
`[in] dnsOptions`	An integer value controlling how host name resolution is performed. Value should be the OR of one or more values from from the #::nl::Inet::DNSOptions enumeration.
`[in] intf`	The optional interface to use to connect to the peer node, default to INET_NULL_INTERFACEID.

Return Values

`WEAVE_NO_ERROR`	on successful initiation of the connection to the peer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection state is incorrect.
`WEAVE_ERROR_UNSUPPORTED_AUTH_MODE`	if the requested authentication mode is not supported.
`WEAVE_ERROR_INVALID_ADDRESS`	if the destination address cannot be deduced from the node id.
`other`	Inet layer errors generated by the TCPEndPoint connect operations.

DisableKeepAlive

WEAVE_ERROR DisableKeepAlive(
  void
)

WeaveConnection::DisableKeepAlive.

Disable TCP keepalive probes on the underlying TCP connection.

Note:This method can only be called on a Weave connection backed by a TCP connection. This method can only be called when the connection is in a state that allows sending.

This method does nothing if keepalives have not been enabled on the connection.

Details

Return Values

`WEAVE_NO_ERROR`	on successful disabling of TCP keepalive probes on the connection.
`WEAVE_ERROR_NOT_IMPLEMENTED`	if this function is invoked for an incompatible endpoint (e.g., BLE) in the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for sending messages.
`other`	Inet layer errors related to the TCP endpoint enable keepalive operation.

DisableReceive

void DisableReceive(
  void
)

Disable receiving over this WeaveConnection.

This method is used by the application to indicate that it is not ready to receive any arrived data over the TCP connection. In order to re-enable receiving, the application needs to call EnableReceive() to allow WeaveConnection to hand over any received data by invoking the approrpiate callbacks.

See also:
EnableReceive()

EnableKeepAlive

WEAVE_ERROR EnableKeepAlive(
  uint16_t interval,
  uint16_t timeoutCount
)

WeaveConnection::EnableKeepAlive.

Enable TCP keepalive probes on the underlying TCP connection.

Note:-This method can only be called on a Weave connection backed by a TCP connection. -This method can only be called when the connection is in a state that allows sending.

Details

Parameters

`[in] 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.
`[in] timeoutCount`	The maximum number of unacknowledged probes before the connection will be deemed to have failed.

-This method can be called multiple times to adjust the keepalive interval or timeout count.

Details

Return Values

`WEAVE_NO_ERROR`	on successful enabling of TCP keepalive probes on the connection.
`WEAVE_ERROR_NOT_IMPLEMENTED`	if this function is invoked for an incompatible endpoint (e.g., BLE) in the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for sending messages.
`other`	Inet layer errors related to the TCP endpoint enable keepalive operation.

EnableReceive

void EnableReceive(
  void
)

Enable receiving over this WeaveConnection.

This method is used by the application to indicate to the WeaveConnection object that it is ready to receive any data that arrives over the TCP connection.

See also:
DisableReceive()

GetPeerAddressInfo

WEAVE_ERROR GetPeerAddressInfo(
  IPPacketInfo & addrInfo
)

Get the IP address information of the peer.

Details

Parameters

[out] addrInfo

A reference to the IPPacketInfo object.

Return Values

`WEAVE_NO_ERROR`	On success.
`WEAVE_ERROR_NOT_IMPLEMENTED`	If this function is invoked for an incompatible endpoint (e.g., BLE) in the network layer.

GetPeerDescription

void GetPeerDescription(
  char *buf,
  size_t bufSize
) const

Constructs a string describing the peer node associated with the connection.

Details

Parameters

`[in] buf`	A pointer to a buffer into which the string should be written. The supplied buffer should be at least as big as kGetPeerDescription_MaxLength. If a smaller buffer is given the string will be truncated to fit. The output will include a NUL termination character in all cases.
`[in] bufSize`	The size of the buffer pointed at by buf.

GetTCPEndPoint

TCPEndPoint * GetTCPEndPoint(
  void
) const

IsIncoming

bool IsIncoming(
  void
) const

LogId

uint16_t LogId(
  void
) const

Release

void Release(
  void
)

Decrement the reference count on the WeaveConnection object.

The Release() method decrements the reference count associated with the WeaveConnection object. If this results in the reference count reaching zero, the connection is closed and the connection object is freed. When this happens, the application must have no further interactions with the object.

ResetUserTimeout

WEAVE_ERROR ResetUserTimeout(
  void
)

WeaveConnection::ResetUserTimeout.

Reset the TCP user timeout socket option to the system default.

Note:-This method can only be called on a Weave connection backed by a TCP connection. -This method can only be called when the connection is in a state that allows sending.

-This method does nothing if user timeout has not been set on the connection.

Details

Return Values

`WEAVE_NO_ERROR`	on successful resetting of TCP user timeout on the connection.
`WEAVE_ERROR_NOT_IMPLEMENTED`	if this function is invoked for an incompatible endpoint (e.g., BLE) in the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for sending messages.
`other`	Inet layer errors related to the TCP endpoint resetting of the TCP user timeout.

SendMessage

WEAVE_ERROR SendMessage(
  WeaveMessageInfo *msgInfo,
  PacketBuffer *msgBuf
)

Send a Weave message over an established connection.

Details

Parameters

`[in] msgInfo`	A pointer to a WeaveMessageInfo object.
`[in] msgBuf`	A pointer to the PacketBuffer object holding the packet to send.

Return Values

`WEAVE_NO_ERROR`	on successfully sending the message down to the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for sending messages.
`WEAVE_ERROR_INVALID_DESTINATION_NODE_ID`	if the destination node identifier is unspecified.
`WEAVE_ERROR_SENDING_BLOCKED`	if the message is too long to be sent.
`other`	Inet layer errors related to the specific endpoint send operations.

SendTunneledMessage

WEAVE_ERROR SendTunneledMessage(
  WeaveMessageInfo *msgInfo,
  PacketBuffer *msgBuf
)

Function to send a Tunneled packet over a Weave connection.

Send a tunneled Weave message over an established connection.

Details

Parameters

`[in] msgInfo`	A pointer to a WeaveMessageInfo object.
`[in] msgBuf`	A pointer to the PacketBuffer object holding the packet to send.

Return Values

`WEAVE_NO_ERROR`	on successfully sending the message down to the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for sending messages.
`WEAVE_ERROR_INVALID_DESTINATION_NODE_ID`	if the destination node identifier is unspecified.
`WEAVE_ERROR_SENDING_BLOCKED`	if the message is too long to be sent.
`other`	Inet layer errors related to the specific endpoint send operations.

SetConnectTimeout

void SetConnectTimeout(
  const uint32_t connTimeoutMsecs
)

Set timeout for Connect to succeed or return an error.

Details

Parameters

[in] connTimeoutMsecs

SetIdleTimeout

WEAVE_ERROR SetIdleTimeout(
  uint32_t timeoutMS
)

Set the idle timeout on the underlying network layer connection.

Details

Parameters

[in] timeoutMS

the timeout in milliseconds.

Return Values

`WEAVE_NO_ERROR`	on successful setting of the idle timeout for the connection.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for receiving messages.

SetIncoming

void SetIncoming(
  bool val
)

SetUserTimeout

WEAVE_ERROR SetUserTimeout(
  uint32_t userTimeoutMillis
)

WeaveConnection::SetUserTimeout.

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.

Details

Parameters

[in] userTimeoutMillis

Tcp user timeout value in milliseconds.

Note:-This method can only be called on a Weave connection backed by a TCP connection. -This method can only be called when the connection is in a state that allows sending.

-This method can be called multiple times to adjust the TCP user timeout.

Details

Return Values

`WEAVE_NO_ERROR`	on successful setting of TCP user timeout on the connection.
`WEAVE_ERROR_NOT_IMPLEMENTED`	if this function is invoked for an incompatible endpoint (e.g., BLE) in the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state for sending messages.
`other`	Inet layer errors related to the TCP endpoint setting of the TCP user timeout.

Shutdown

WEAVE_ERROR Shutdown(
  void
)

Performs a graceful TCP send-shutdown, ensuring all outgoing data has been sent and received by the peer's TCP stack.

With most (but not all) TCP implementations, receipt of a send-shutdown will cause the remote host to shutdown their side of the connection as well, resulting in a connection close. A subsequent call to Close() would terminate the WeaveConnection.

Details

Return Values

`WEAVE_NO_ERROR`	on successful shutdown of the tcp connection.
`WEAVE_ERROR_NOT_IMPLEMENTED`	if this function is invoked for an incompatible endpoint (e.g., BLE) in the network layer.
`WEAVE_ERROR_INCORRECT_STATE`	if the WeaveConnection object is not in the correct state before initiating a shutdown.
`other`	Inet layer errors related to the specific endpoint shutdown operations.

See also:
Close() and Abort().