nl::Weave::Binding::Configuration

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

Provides a declarative-style interface for configuring and preparing a Binding object.

Summary

When configuring a Binding, applications must call at least one method from each of the following configuration groups: Target, Transport, and Security. Other methods may be called as needed to override default behavior.

If mutually exclusive configurations are invoked (e.g., Transport_TCP() followed by Transport_UDP()), the last one to be called wins.

Public functions

ConfigureFromMessage(const WeaveMessageInfo *aMsgInfo, const Inet::IPPacketInfo *aPacketInfo)
Configure the binding to allow communication with the sender of a received message.
DNS_Options(uint8_t dnsOptions)
When resolving the host name of the peer, use the specified DNS options.
Exchange_ResponseTimeoutMsec(uint32_t aResponseTimeoutMsec)
Set default response timeout for exchange contexts created from this Binding object.
GetError(void) const
Return any error that has occurred while configuring the Binding.
PrepareBinding(void)
Being the process of preparing the Binding for communication with the peer.
Security_AppGroupKey(uint32_t aAppGroupGlobalId, uint32_t aRootKeyId, bool aUseRotatingKey)
When communicating with the peer, send and receive messages encrypted for a specified Weave Application Group.
Security_AuthenticationMode(WeaveAuthMode aAuthMode)
Set the requested authentication mode to be used to authenticate the peer.
Security_CASESession(void)
When communicating with the peer, send and receive messages encrypted using a CASE session key established with the peer node.
Security_EncryptionType(uint8_t aEncType)
When communicating with the peer, send and receive messages encrypted using the specified message encryption type.
Security_Key(uint32_t aKeyId)
When communicating with the peer, send and receive messages encrypted using a specified key.
Security_None(void)
When communicating with the peer, send and receive unencrypted (i.e.
Security_PASESession(uint8_t aPasswordSource)
When communicating with the peer, send and receive messages encrypted using a PASE session key established with the peer node.
Security_SharedCASESession(void)
When communicating with the peer, send and receive messages encrypted using a shared CASE session key established with the Nest core router.
Security_SharedCASESession(uint64_t aRouterNodeId)
When communicating with the peer, send and receive messages encrypted using a shared CASE session key established with a specified router node.
Security_TAKESession()
When communicating with the peer, send and receive messages encrypted using a TAKE session key established with the peer node.
TargetAddress_IP(nl::Inet::IPAddress aPeerAddress, uint16_t aPeerPort, InterfaceId aInterfaceId)
When communicating with the peer, use the specific IP address, port and network interface.
TargetAddress_IP(const char *aHostName, uint16_t aPeerPort, InterfaceId aInterfaceId)
When communicating with the peer, use the specific host name, port and network interface.
TargetAddress_IP(const char *aHostName, size_t aHostNameLen, uint16_t aPeerPort, InterfaceId aInterfaceId)
When communicating with the peer, use the specific host name, port and network interface.
TargetAddress_WeaveFabric(uint16_t aSubnetId)
When communicating with the peer, use a Weave fabric address derived from the peer's node id and a specified subnet.
TargetAddress_WeaveService(void)
When communicating with the peer, use a Weave service fabric address derived from the peer's node id.
Target_NodeId(uint64_t aPeerNodeId)
Configure the binding to communicate with a specific Weave node id.
Target_ServiceEndpoint(uint64_t aPeerNodeId)
Configure the binding to communicate with a specific Weave service endpoint.
Transport_DefaultWRMPConfig(const WRMPConfig & aWRMPConfig)
Set the default WRMP configuration for exchange contexts created from this Binding object.
Transport_ExistingConnection(WeaveConnection *apConnection)
Use an existing Weave connection to communicate with the peer.
Transport_TCP(void)
Use TCP to communicate with the peer.
Transport_UDP(void)
Use UDP to communicate with the peer.
Transport_UDP_PathMTU(uint32_t aPathMTU)
Set the expected path MTU for UDP packets travelling to the peer.
Transport_UDP_WRM(void)
Use the Weave Reliable Messaging protocol when communicating with the peer.

Public functions

ConfigureFromMessage

Configuration & ConfigureFromMessage(
  const WeaveMessageInfo *aMsgInfo,
  const Inet::IPPacketInfo *aPacketInfo
)

Configure the binding to allow communication with the sender of a received message.

Details
Parameters
[in] aMsgInfo
Message information structure associated with the received message.
[in] aPacketInfo
Packet information for the received message.

DNS_Options

Configuration & DNS_Options(
  uint8_t dnsOptions
)

When resolving the host name of the peer, use the specified DNS options.

Details
Parameters
[in] dnsOptions
An integer value controlling how host name resolution is performed. Value should be one of values from the #::nl::Inet::DNSOptions enumeration.
Returns
A reference to the binding object.

Exchange_ResponseTimeoutMsec

Configuration & Exchange_ResponseTimeoutMsec(
  uint32_t aResponseTimeoutMsec
)

Set default response timeout for exchange contexts created from this Binding object.

Details
Parameters
[in] aResponseTimeoutMsec
The default response time, in ms.
Returns
A reference to the binding object.

GetError

WEAVE_ERROR GetError(
  void
) const 

Return any error that has occurred while configuring the Binding.

PrepareBinding

WEAVE_ERROR PrepareBinding(
  void
)

Being the process of preparing the Binding for communication with the peer.

Security_AppGroupKey

Configuration & Security_AppGroupKey(
  uint32_t aAppGroupGlobalId,
  uint32_t aRootKeyId,
  bool aUseRotatingKey
)

When communicating with the peer, send and receive messages encrypted for a specified Weave Application Group.

Details
Parameters
[in] aAppGroupGlobalId
The global id of the application group for which messages should be encrypted.
[in] aRootKeyId
The root key used to derive encryption keys for the specified Weave Application Group.
[in] aUseRotatingKey
True if the Weave Application Group uses rotating message keys.
Returns
A reference to the Binding object.

Security_AuthenticationMode

Configuration & Security_AuthenticationMode(
  WeaveAuthMode aAuthMode
)

Set the requested authentication mode to be used to authenticate the peer.

Details
Parameters
[in] aAuthMode
The requested authentication mode.
Returns
A reference to the Binding object.

Security_CASESession

Configuration & Security_CASESession(
  void
)

When communicating with the peer, send and receive messages encrypted using a CASE session key established with the peer node.

If the necessary session is not available, it will be established automatically as part of preparing the binding.

Details
Returns
A reference to the binding object.

Security_EncryptionType

Configuration & Security_EncryptionType(
  uint8_t aEncType
)

When communicating with the peer, send and receive messages encrypted using the specified message encryption type.

Details
Parameters
[in] aEncType
The Weave message encryption type.
Returns
A reference to the Binding object.

Security_Key

Configuration & Security_Key(
  uint32_t aKeyId
)

When communicating with the peer, send and receive messages encrypted using a specified key.

Details
Parameters
[in] aKeyId
The id of the encryption key. The specified key must be suitable for Weave message encryption.
Returns
A reference to the Binding object.

Security_None

Configuration & Security_None(
  void
)

When communicating with the peer, send and receive unencrypted (i.e.

unsecured) messages.

Details
Returns
A reference to the binding object.

Security_PASESession

Configuration & Security_PASESession(
  uint8_t aPasswordSource
)

When communicating with the peer, send and receive messages encrypted using a PASE session key established with the peer node.

If the necessary session is not available, it will be established automatically as part of preparing the binding.

Details
Parameters
[in] aPasswordSource
The source for the password to be used during PASE session establishment.
Returns
A reference to the binding object.

Security_SharedCASESession

Configuration & Security_SharedCASESession(
  void
)

When communicating with the peer, send and receive messages encrypted using a shared CASE session key established with the Nest core router.

If the necessary session is not available, it will be established automatically as part of preparing the binding.

Details
Returns
A reference to the binding object.

Security_SharedCASESession

Configuration & Security_SharedCASESession(
  uint64_t aRouterNodeId
)

When communicating with the peer, send and receive messages encrypted using a shared CASE session key established with a specified router node.

If the necessary session is not available, it will be established automatically as part of preparing the binding.

Details
Parameters
[in] aRouterNodeId
The Weave node ID of the router with which shared CASE session should be established.
Returns
A reference to the binding object.

Security_TAKESession

Configuration & Security_TAKESession()

When communicating with the peer, send and receive messages encrypted using a TAKE session key established with the peer node.

If the necessary session is not available, it will be established automatically as part of preparing the binding.

Details
Returns
A reference to the binding object.

TargetAddress_IP

Configuration & TargetAddress_IP(
  nl::Inet::IPAddress aPeerAddress,
  uint16_t aPeerPort,
  InterfaceId aInterfaceId
)

When communicating with the peer, use the specific IP address, port and network interface.

Details
Parameters
[in] aPeerAddress
IP address for the peer
[in] aPeerPort
Remote port
[in] aInterfaceId
The ID of local network interface to use for communication
Returns
A reference to the binding object.

TargetAddress_IP

Configuration & TargetAddress_IP(
  const char *aHostName,
  uint16_t aPeerPort,
  InterfaceId aInterfaceId
)

When communicating with the peer, use the specific host name, port and network interface.

NOTE: The caller must ensure that the supplied host name string remains valid until the binding preparation phase completes.

Details
Parameters
[in] aHostName
A NULL-terminated string containing the host name of the peer.
[in] aPeerPort
Remote port to use when communicating with the peer.
[in] aInterfaceId
The ID of local network interface to use for communication.
Returns
A reference to the binding object.

TargetAddress_IP

Configuration & TargetAddress_IP(
  const char *aHostName,
  size_t aHostNameLen,
  uint16_t aPeerPort,
  InterfaceId aInterfaceId
)

When communicating with the peer, use the specific host name, port and network interface.

NOTE: The caller must ensure that the supplied host name string remains valid until the binding preparation phase completes.

Details
Parameters
[in] aHostName
A string containing the host name of the peer. This string does not need to be NULL terminated.
[in] aHostNameLen
The length of the string pointed at by aHostName.
[in] aPeerPort
Remote port to use when communicating with the peer.
[in] aInterfaceId
The ID of local network interface to use for communication.
Returns
A reference to the binding object.

TargetAddress_WeaveFabric

Configuration & TargetAddress_WeaveFabric(
  uint16_t aSubnetId
)

When communicating with the peer, use a Weave fabric address derived from the peer's node id and a specified subnet.

Details
Parameters
[in] aSubnetId
The subnet id to be used in forming the Weave fabric address of the peer.
Returns
A reference to the binding object.

TargetAddress_WeaveService

Configuration & TargetAddress_WeaveService(
  void
)

When communicating with the peer, use a Weave service fabric address derived from the peer's node id.

Details
Returns
A reference to the binding object.

Target_NodeId

Configuration & Target_NodeId(
  uint64_t aPeerNodeId
)

Configure the binding to communicate with a specific Weave node id.

Details
Parameters
[in] aPeerNodeId
Node id of the peer node.
Returns
A reference to the binding object.

Target_ServiceEndpoint

Configuration & Target_ServiceEndpoint(
  uint64_t aPeerNodeId
)

Configure the binding to communicate with a specific Weave service endpoint.

If not otherwise configured, the peer address is set to the Weave fabric address of the service endpoint.

Details
Parameters
[in] serviceEndpointId
The node id of the service endpoint with which communication will take place.
Returns
A reference to the binding object.

Transport_DefaultWRMPConfig

Configuration & Transport_DefaultWRMPConfig(
  const WRMPConfig & aWRMPConfig
)

Set the default WRMP configuration for exchange contexts created from this Binding object.

Details
Parameters
[in] aWRMPConfig
A reference to the new default WRMP configuration.
Returns
A reference to the binding object.

Transport_ExistingConnection

Configuration & Transport_ExistingConnection(
  WeaveConnection *apConnection
)

Use an existing Weave connection to communicate with the peer.

NOTE: The reference count on the connection object is incremented when binding preparation succeeds. Thus the application is responsible for ensuring the connection object remain alive until that time.

Details
Parameters
[in] con
A pointer to the existing Weave connection.
Returns
A reference to the binding object.

Transport_TCP

Configuration & Transport_TCP(
  void
)

Use TCP to communicate with the peer.

Details
Returns
A reference to the binding object.

Transport_UDP

Configuration & Transport_UDP(
  void
)

Use UDP to communicate with the peer.

Details
Returns
A reference to the binding object.

Transport_UDP_PathMTU

Configuration & Transport_UDP_PathMTU(
  uint32_t aPathMTU
)

Set the expected path MTU for UDP packets travelling to the peer.

For some Weave protocols this will be used to dynamically adjust the Weave message payload size.

Details
Parameters
[in] aPathMTU
The expected path MTU for UDP packets travelling to the peer.
Returns
A reference to the binding object.

Transport_UDP_WRM

Configuration & Transport_UDP_WRM(
  void
)

Use the Weave Reliable Messaging protocol when communicating with the peer.

Details
Returns
A reference to the binding object.