nl::Weave::Profiles::WeaveTunnel::WeaveTunnelAgent

Summary

Constructors and Destructors
WeaveTunnelAgent(void)

Public types
AgentState{
  kState_NotInitialized = 0,
  kState_Initialized_NoTunnel = 1,
  kState_PrimaryTunModeEstablished = 2,
  kState_BkupOnlyTunModeEstablished = 3,
  kState_PrimaryAndBkupTunModeEstablished = 4
} 		enum
States of the Tunnel Agent in relation to its connection(s) to the Service.
AgentState typedef
States of the Tunnel Agent in relation to its connection(s) to the Service.
OnServiceTunnelReconnectNotifyFunct)(TunnelType tunType, const char *reconnectHost, const uint16_t reconnectPort, void *appCtxt) typedef
void(*
Function pointer to handler set by a higher layer when a Tunnel Reconnect is received from the Service.
OnServiceTunnelStatusNotifyFunct)(WeaveTunnelConnectionMgr::TunnelConnNotifyReasons reason, WEAVE_ERROR err, void *appCtxt) typedef
void(*
Function pointer to handler set by a higher layer to act upon various notifications related to the tunnel to the Service.
PlatformNetworkOnlineCheck)(TunnelType tunType, void *appCtxt) typedef
void(*
Function pointer to a handler provided by the application for performing a network level online check.
WeaveTunnelFlags{
  kTunnelFlag_PrimaryEnabled = 0x01,
  kTunnelFlag_BackupEnabled = 0x02,
  kTunnelFlag_PrimaryRestricted = 0x04,
  kTunnelFlag_BackupRestricted = 0x08
} 		enum
Weave Tunnel flag bits.
WeaveTunnelFlags typedef
Weave Tunnel flag bits.

Public attributes
NetworkOnlineCheck
OnServiceTunReconnectNotify
OnServiceTunStatusNotify
Function pointer to handler set by a higher layer to act upon various notifications related to the tunnel to the Service.
mServiceMgr
WeaveServiceManager *
Service Manager pointer to use to lookup and connect to Service.

Public functions
DisablePrimaryTunnel(void)
void
Disable Primary Tunnel.
EnablePrimaryTunnel(void)
void
Enable Primary Tunnel.
GetAgentStateName(const AgentState state)
const char *
Get the WeaveTunnelAgentState name.
GetTimeMsec(void)
uint64_t
Get the system time in milliseconds.
GetWeaveTunnelAgentState(void)
Get the TunnelAgent state.
Init(InetLayer *inet, WeaveExchangeManager *exchMgr, uint64_t dstNodeId, WeaveAuthMode authMode, WeaveServiceManager *svcMgr, const char *intfName, uint8_t role, void *appContext)
Initialize the Tunnel agent.
Init(InetLayer *inet, WeaveExchangeManager *exchMgr, uint64_t dstNodeId, IPAddress dstIPAddr, WeaveAuthMode authMode, const char *intfName, uint8_t role, void *appContext)
Initialize the Tunnel agent.
IsPrimaryTunnelEnabled(void) const
bool
Check if the primary tunnel is enabled.
IsPrimaryTunnelRoutingRestricted(void)
bool
Check if the primary tunnel is subject to routing restrictions by the service.
IsTunnelRoutingRestricted(void)
bool
Check if the tunnel is subject to routing restrictions by the service.
NetworkOnlineCheckResult(TunnelType tunType, bool isOnline)
void
Callback invoked by the platform when the result of the network online checker is available.
ResetPrimaryReconnectBackoff(bool reconnectImmediately)
Reset the Reconnect time for the primary tunnel.
SetAuthMode(const WeaveAuthMode authMode)
void
Set the WeaveAuthMode for the Tunnel.
SetDestination(const uint64_t nodeId, const IPAddress ipAddr, const uint16_t servicePort)
void
Set the destination nodeId, IPAddress and port for the Tunnel.
SetTunnelingDeviceRole(const Role role)
void
Set the Tunneling device role(BorderGateway, StandaloneDevice, MobileDevice) for the Tunnel.
Shutdown(void)
Shutdown the Tunnel Agent.
StartServiceTunnel(void)
Start the Service Tunnel.
StartServiceTunnel(uint64_t dstNodeId, IPAddress dstIPAddr, WeaveAuthMode authMode)
Start the Service Tunnel.
StopServiceTunnel(void)
void
Close the Tunnel connection to the Service.
StopServiceTunnel(WEAVE_ERROR err)
void
Close the Tunnel connection to the Service.

Public static functions
RecvdFromShortcutUDPTunnel(WeaveMessageLayer *msgLayer, PacketBuffer *message)
void
Handler to receive tunneled IPv6 packets over the shortcut UDP tunnel between the border gateway and the mobile device and forward to the Tunnel EndPoint interface after decapsulating the raw IPv6 packet from inside the tunnel header.
RecvdFromTunnelEndPoint(TunEndPoint *tunEP, PacketBuffer *message)
void
Handler to receive IPv6 packets from the Tunnel EndPoint interface and forward, either to the Service via the Service TCP connection after encapsulating IPv6 packet inside the tunnel header or to the Mobile client over a shortcut tunnel.

Public types

AgentState

 AgentState

States of the Tunnel Agent in relation to its connection(s) to the Service.

Properties
kState_BkupOnlyTunModeEstablished

Used to indicate that the Backup tunnel to the Service has been established.

kState_Initialized_NoTunnel

Used to indicate that the Tunnel Agent is initialized but no tunnel has been established.

kState_NotInitialized

Used to indicate that the Tunnel Agent is not initialized.

kState_PrimaryAndBkupTunModeEstablished

Used to indicate that both the Primary and the Backup tunnel has been established.

kState_PrimaryTunModeEstablished

Used to indicate that the Primary tunnel to the Service has been established.

AgentState

enum nl::Weave::Profiles::WeaveTunnel::WeaveTunnelAgent::AgentState AgentState

States of the Tunnel Agent in relation to its connection(s) to the Service.

OnServiceTunnelReconnectNotifyFunct

void(* OnServiceTunnelReconnectNotifyFunct)(TunnelType tunType, const char *reconnectHost, const uint16_t reconnectPort, void *appCtxt)

Function pointer to handler set by a higher layer when a Tunnel Reconnect is received from the Service.

Details
Parameters
[in] tunType
The tunnel type, Primary or Backup.
[in] reconnectHost
The hostname provided by Service to reconnect to.
[in] reconnectPort
The destination port provided by Service to reconnect to.
[in] appCtxt
A pointer to an application context object

OnServiceTunnelStatusNotifyFunct

void(* OnServiceTunnelStatusNotifyFunct)(WeaveTunnelConnectionMgr::TunnelConnNotifyReasons reason, WEAVE_ERROR err, void *appCtxt)

Function pointer to handler set by a higher layer to act upon various notifications related to the tunnel to the Service.

Details
Parameters
[in] reason
The reason for the status notification to the application.
[in] err
Weave error encountered, if any
[in] appCtxt
A pointer to an application context object

PlatformNetworkOnlineCheck

void(* PlatformNetworkOnlineCheck)(TunnelType tunType, void *appCtxt)

Function pointer to a handler provided by the application for performing a network level online check.

Details
Parameters
[in] tunType
The tunnel type, Primary or Backup.
[in] appCtxt
A pointer to an application context object

WeaveTunnelFlags

 WeaveTunnelFlags

Weave Tunnel flag bits.

Properties
kTunnelFlag_BackupEnabled

Set when the backup tunnel is enabled.

kTunnelFlag_BackupRestricted

Set when the backup tunnel is routing restricted.

kTunnelFlag_PrimaryEnabled

Set when the primary tunnel is enabled.

kTunnelFlag_PrimaryRestricted

Set when the primary tunnel is routing restricted.

WeaveTunnelFlags

enum nl::Weave::Profiles::WeaveTunnel::WeaveTunnelAgent::WeaveTunnelFlags WeaveTunnelFlags

Weave Tunnel flag bits.

Public attributes

NetworkOnlineCheck

PlatformNetworkOnlineCheck NetworkOnlineCheck

OnServiceTunReconnectNotify

OnServiceTunnelReconnectNotifyFunct OnServiceTunReconnectNotify

OnServiceTunStatusNotify

OnServiceTunnelStatusNotifyFunct OnServiceTunStatusNotify

Function pointer to handler set by a higher layer to act upon various notifications related to the tunnel to the Service.

mServiceMgr

WeaveServiceManager * mServiceMgr

Service Manager pointer to use to lookup and connect to Service.

Public functions

DisablePrimaryTunnel

void DisablePrimaryTunnel(
  void
)

Disable Primary Tunnel.

Disable the Primary Tunnel.

EnablePrimaryTunnel

void EnablePrimaryTunnel(
  void
)

Enable Primary Tunnel.

Enable the Primary Tunnel.

GetAgentStateName

const char * GetAgentStateName(
  const AgentState state
)

Get the WeaveTunnelAgentState name.

GetTimeMsec

uint64_t GetTimeMsec(
  void
)

Get the system time in milliseconds.

Get system time or monotonic time in milliseconds if system time is not available.

GetWeaveTunnelAgentState

AgentState GetWeaveTunnelAgentState(
  void
)

Get the TunnelAgent state.

Details
Returns
AgentState the current state of the WeaveTunnelAgent.

Init

WEAVE_ERROR Init(
  InetLayer *inet,
  WeaveExchangeManager *exchMgr,
  uint64_t dstNodeId,
  WeaveAuthMode authMode,
  WeaveServiceManager *svcMgr,
  const char *intfName,
  uint8_t role,
  void *appContext
)

Initialize the Tunnel agent.

This creates te Tunnel endpoint object, sets up the tunnel interface, initializes member variables, callbacks and WeaveTunnelControl.

Init

WEAVE_ERROR Init(
  InetLayer *inet,
  WeaveExchangeManager *exchMgr,
  uint64_t dstNodeId,
  IPAddress dstIPAddr,
  WeaveAuthMode authMode,
  const char *intfName,
  uint8_t role,
  void *appContext
)

Initialize the Tunnel agent.

This creates te Tunnel endpoint object, sets up the tunnel interface, initializes member variables, callbacks and WeaveTunnelControl.

IsPrimaryTunnelEnabled

bool IsPrimaryTunnelEnabled(
  void
) const

Check if the primary tunnel is enabled.

Details
Returns
true if it is enabled, else false.

IsPrimaryTunnelRoutingRestricted

bool IsPrimaryTunnelRoutingRestricted(
  void
)

Check if the primary tunnel is subject to routing restrictions by the service.

Check if the primary tunnel is subject to routing restrictions.

Details
Returns
true if the primary tunnel is established but subject to routing restrictions by the service.

IsTunnelRoutingRestricted

bool IsTunnelRoutingRestricted(
  void
)

Check if the tunnel is subject to routing restrictions by the service.

Check if the tunnel is subject to routing restrictions.

Details
Returns
true if either the primary or backup tunnel is established, and either are subject to routing restrictions by the service.

NetworkOnlineCheckResult

void NetworkOnlineCheckResult(
  TunnelType tunType,
  bool isOnline
)

Callback invoked by the platform when the result of the network online checker is available.

Details
Parameters
[in] tunType
The tunnel type corresponding to the interface over which the network connectivity check is performed.
[in] isOnline
True if network is online, false otherwise.

ResetPrimaryReconnectBackoff

WEAVE_ERROR ResetPrimaryReconnectBackoff(
  bool reconnectImmediately
)

Reset the Reconnect time for the primary tunnel.

Details
Parameters
[in] reconnectImmediately
True if required to reconnect immediately, else using the configured reconenct timeout.

SetAuthMode

void SetAuthMode(
  const WeaveAuthMode authMode
)

Set the WeaveAuthMode for the Tunnel.

Details
Parameters
[in] authMode
Weave authentication mode used with peer.

SetDestination

void SetDestination(
  const uint64_t nodeId,
  const IPAddress ipAddr,
  const uint16_t servicePort
)

Set the destination nodeId, IPAddress and port for the Tunnel.

Set the destination nodeId and IPAddress for the Tunnel.

Details
Parameters
[in] nodeId
Node ID of the destination node.
[in] ipAddr
IP address of the destination node.
[in] servicePort
Port of the destination node.

SetTunnelingDeviceRole

void SetTunnelingDeviceRole(
  const Role role
)

Set the Tunneling device role(BorderGateway, StandaloneDevice, MobileDevice) for the Tunnel.

Set the Tunneling device role(BorderGateway vs Standalone) for the Tunnel.

Details
Parameters
[in] role
Role assumed by Tunnel Agent; Border Gateway, Standalone or Mobile Device.

Shutdown

WEAVE_ERROR Shutdown(
  void
)

Shutdown the Tunnel Agent.

This tears down connection to the Service and closes the TunEndPoint interface after removing addresses and routes associated with the tunnel interface.

This tears down connection to the Service and closes the TunEndPoint interface after removing addresses and routes associated with the tunnel interface.

Details
Returns
WEAVE_NO_ERROR on success, else a corresponding WEAVE_ERROR type.

StartServiceTunnel

WEAVE_ERROR StartServiceTunnel(
  void
)

Start the Service Tunnel.

This enables the tunnel and tries to establish a connection to the Service.

This tries to establish a connection to the Service and also sets the fabric route to the tunnel interface.

Details
Returns
WEAVE_NO_ERROR on success, else a corresponding WEAVE_ERROR type.

StartServiceTunnel

WEAVE_ERROR StartServiceTunnel(
  uint64_t dstNodeId,
  IPAddress dstIPAddr,
  WeaveAuthMode authMode
)

Start the Service Tunnel.

This enables the tunnel and tries to establish a connection to the Service.

StopServiceTunnel

void StopServiceTunnel(
  void
)

Close the Tunnel connection to the Service.

StopServiceTunnel

void StopServiceTunnel(
  WEAVE_ERROR err
)

Close the Tunnel connection to the Service.

Details
Parameters
[in] err
WEAVE_NO_ERROR if there is no specific reason for this StopServiceTunnel request, otherwise the cause of error would be passed down.

WeaveTunnelAgent

 WeaveTunnelAgent(
  void
)

Public static functions

RecvdFromShortcutUDPTunnel

void RecvdFromShortcutUDPTunnel(
  WeaveMessageLayer *msgLayer,
  PacketBuffer *message
)

Handler to receive tunneled IPv6 packets over the shortcut UDP tunnel between the border gateway and the mobile device and forward to the Tunnel EndPoint interface after decapsulating the raw IPv6 packet from inside the tunnel header.

Handler to receive tunneled IPv6 packets from the Service TCP connection and forward to the Tunnel EndPoint interface after decapsulating the raw IPv6 packet from inside the tunnel header.

Details
Parameters
[in] con
A pointer to the WeaveConnection object.
[in] msgInfo
A pointer to the WeaveMessageInfo object.
[in] message
A pointer to the PacketBuffer object holding the tunneled IPv6 packet.

RecvdFromTunnelEndPoint

void RecvdFromTunnelEndPoint(
  TunEndPoint *tunEP,
  PacketBuffer *message
)

Handler to receive IPv6 packets from the Tunnel EndPoint interface and forward, either to the Service via the Service TCP connection after encapsulating IPv6 packet inside the tunnel header or to the Mobile client over a shortcut tunnel.

Handler to receive IPv6 packets from the Tunnel EndPoint interface and forward, either to the Service via the Service TCP connection after encapsulating IPv6 packet inside the tunnel header or to the Mobile client over a local tunnel.

If the Service connection is not yet up, the message is queued until the connection is set up. For tunneling to the Mobile client device, the nexthop neighbor table is referenced.

If the Service connection is not yet up, the message is queued until the connection is set up. For tunneling to the Mobile client device, the nexthop neighbor table is referenced.

Details
Parameters
[in] tunEP
A pointer to the TunEndPoint object.
[in] message
A pointer to the PacketBuffer object holding the raw IPv6 packet.