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