Border Routing Manager

This module includes definitions related to Border Routing Manager.

Classes

struct  otBorderRoutingPrefixTableIterator
 This structure represents an iterator to iterate through the Border Router's discovered prefix table.
 
struct  otBorderRoutingPrefixTableEntry
 This structure represents an entry from the discovered prefix table.

Typedefs

typedef struct otBorderRoutingPrefixTableIterator otBorderRoutingPrefixTableIterator
 This structure represents an iterator to iterate through the Border Router's discovered prefix table.
 
typedef struct otBorderRoutingPrefixTableEntry otBorderRoutingPrefixTableEntry
 This structure represents an entry from the discovered prefix table.

Functions

otError otBorderRoutingInit (otInstance *aInstance, uint32_t aInfraIfIndex, bool aInfraIfIsRunning)
 This method initializes the Border Routing Manager on given infrastructure interface.
 
otError otBorderRoutingSetEnabled (otInstance *aInstance, bool aEnabled)
 Enables or disables the Border Routing Manager.
 
otRoutePreference otBorderRoutingGetRouteInfoOptionPreference (otInstance *aInstance)
 This function gets the preference used when advertising Route Info Options (e.g., for discovered OMR prefixes) in Router Advertisement messages sent over the infrastructure link.
 
void otBorderRoutingSetRouteInfoOptionPreference (otInstance *aInstance, otRoutePreference aPreference)
 This function sets the preference to use when advertising Route Info Options in Router Advertisement messages sent over the infrastructure link, for example for discovered OMR prefixes.
 
otError otBorderRoutingGetOmrPrefix (otInstance *aInstance, otIp6Prefix *aPrefix)
 Gets the local Off-Mesh-Routable (OMR) Prefix, for example fdfc:1ff5:1512:5622::/64.
 
otError otBorderRoutingGetFavoredOmrPrefix (otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference)
 Gets the currently favored Off-Mesh-Routable (OMR) Prefix.
 
otError otBorderRoutingGetOnLinkPrefix (otInstance *aInstance, otIp6Prefix *aPrefix)
 Gets the On-Link Prefix for the adjacent infrastructure link, for example fd41:2650:a6f5:0::/64.
 
otError otBorderRoutingGetNat64Prefix (otInstance *aInstance, otIp6Prefix *aPrefix)
 Gets the local NAT64 Prefix of the Border Router.
 
otError otBorderRoutingGetFavoredNat64Prefix (otInstance *aInstance, otIp6Prefix *aPrefix, otRoutePreference *aPreference)
 Gets the currently favored NAT64 prefix.
 
void otBorderRoutingPrefixTableInitIterator (otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator)
 This function initializes an otBorderRoutingPrefixTableIterator.
 
otError otBorderRoutingGetNextPrefixTableEntry (otInstance *aInstance, otBorderRoutingPrefixTableIterator *aIterator, otBorderRoutingPrefixTableEntry *aEntry)
 This function iterates over the entries in the Border Router's discovered prefix table.

Detailed Description

This module includes definitions related to Border Routing Manager.

All the functions in this module require OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE to be enabled.

Border Routing Manager handles bi-directional routing between Thread network and adjacent infrastructure link (AIL).

It emits ICMRv6 ND Router Advertisement (RA) messages on AIL to advertise on-link and route prefixes. It also processes received RA messages from infrastructure and mirrors the discovered prefixes on the Thread Network Data to ensure devices on Thread mesh can reach AIL through the Border Router.

Routing Manager manages the Off-Mesh Routable (OMR) prefix on the Thread Network data which configures Thread devices with a suitable Off-Mesh Routable IPv6 address. It announces the reachability of this prefix on AIL by including it in the emitted RA messages as an IPv6 Route Information Option (RIO).

Routing Manager also monitors and adds on-link prefix on the infrastructure network. If a router on AIL is already providing RA messages containing an IPv6 Prefix Information Option (PIO) that enables IPv6 devices on the link to self-configure their own routable unicast IPv6 address, this address can be used by Thread devices to reach AIL. If Border Router finds no such RA message on AIL, it generates a ULA on-link prefix which it then advertises on AIL in the emitted RA messages.

Typedef Documentation

◆ otBorderRoutingPrefixTableEntry

This structure represents an entry from the discovered prefix table.

The entries in the discovered table track the Prefix/Route Info Options in the received Router Advertisement messages from other routers on infrastructure link.

◆ otBorderRoutingPrefixTableIterator

This structure represents an iterator to iterate through the Border Router's discovered prefix table.

The fields in this type are opaque (intended for use by OpenThread core only) and therefore should not be accessed or used by caller.

Before using an iterator, it MUST be initialized using otBorderRoutingPrefixTableInitIterator().

Function Documentation

◆ otBorderRoutingGetFavoredNat64Prefix()

otError otBorderRoutingGetFavoredNat64Prefix ( otInstance aInstance,
otIp6Prefix aPrefix,
otRoutePreference aPreference 
)

Gets the currently favored NAT64 prefix.

The favored NAT64 prefix can be discovered from infrastructure link or can be this device's local NAT64 prefix.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[out]aPrefixA pointer to output the favored NAT64 prefix.
[out]aPreferenceA pointer to output the preference associated the favored prefix.
Return values
OT_ERROR_INVALID_STATEThe Border Routing Manager is not initialized yet.
OT_ERROR_NONESuccessfully retrieved the favored NAT64 prefix.

◆ otBorderRoutingGetFavoredOmrPrefix()

otError otBorderRoutingGetFavoredOmrPrefix ( otInstance aInstance,
otIp6Prefix aPrefix,
otRoutePreference aPreference 
)

Gets the currently favored Off-Mesh-Routable (OMR) Prefix.

The favored OMR prefix can be discovered from Network Data or can be this device's local OMR prefix.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[out]aPrefixA pointer to output the favored OMR prefix.
[out]aPreferenceA pointer to output the preference associated the favored prefix.
Return values
OT_ERROR_INVALID_STATEThe Border Routing Manager is not initialized yet.
OT_ERROR_NONESuccessfully retrieved the favored OMR prefix.

◆ otBorderRoutingGetNat64Prefix()

otError otBorderRoutingGetNat64Prefix ( otInstance aInstance,
otIp6Prefix aPrefix 
)

Gets the local NAT64 Prefix of the Border Router.

NAT64 Prefix might not be advertised in the Thread network.

OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE must be enabled.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[out]aPrefixA pointer to where the prefix will be output to.
Return values
OT_ERROR_INVALID_STATEThe Border Routing Manager is not initialized yet.
OT_ERROR_NONESuccessfully retrieved the NAT64 prefix.

◆ otBorderRoutingGetNextPrefixTableEntry()

otError otBorderRoutingGetNextPrefixTableEntry ( otInstance aInstance,
otBorderRoutingPrefixTableIterator aIterator,
otBorderRoutingPrefixTableEntry aEntry 
)

This function iterates over the entries in the Border Router's discovered prefix table.

Parameters
[in]aInstanceThe OpenThread instance.
[in,out]aIteratorA pointer to the iterator.
[out]aEntryA pointer to the entry to populate.
Return values
OT_ERROR_NONEIterated to the next entry, aEntry and aIterator are updated.
OT_ERROR_NOT_FOUNDNo more entries in the table.

◆ otBorderRoutingGetOmrPrefix()

otError otBorderRoutingGetOmrPrefix ( otInstance aInstance,
otIp6Prefix aPrefix 
)

Gets the local Off-Mesh-Routable (OMR) Prefix, for example fdfc:1ff5:1512:5622::/64.

An OMR Prefix is a randomly generated 64-bit prefix that's published in the Thread network if there isn't already an OMR prefix. This prefix can be reached from the local Wi-Fi or Ethernet network.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[out]aPrefixA pointer to where the prefix will be output to.
Return values
OT_ERROR_INVALID_STATEThe Border Routing Manager is not initialized yet.
OT_ERROR_NONESuccessfully retrieved the OMR prefix.

◆ otBorderRoutingGetOnLinkPrefix()

otError otBorderRoutingGetOnLinkPrefix ( otInstance aInstance,
otIp6Prefix aPrefix 
)

Gets the On-Link Prefix for the adjacent infrastructure link, for example fd41:2650:a6f5:0::/64.

An On-Link Prefix is a 64-bit prefix that's advertised on the infrastructure link if there isn't already a usable on-link prefix being advertised on the link.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[out]aPrefixA pointer to where the prefix will be output to.
Return values
OT_ERROR_INVALID_STATEThe Border Routing Manager is not initialized yet.
OT_ERROR_NONESuccessfully retrieved the on-link prefix.

◆ otBorderRoutingGetRouteInfoOptionPreference()

otRoutePreference otBorderRoutingGetRouteInfoOptionPreference ( otInstance aInstance)

This function gets the preference used when advertising Route Info Options (e.g., for discovered OMR prefixes) in Router Advertisement messages sent over the infrastructure link.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
Returns
The OMR prefix advertisement preference.

◆ otBorderRoutingInit()

otError otBorderRoutingInit ( otInstance aInstance,
uint32_t  aInfraIfIndex,
bool  aInfraIfIsRunning 
)

This method initializes the Border Routing Manager on given infrastructure interface.

Note
This method MUST be called before any other otBorderRouting* APIs.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aInfraIfIndexThe infrastructure interface index.
[in]aInfraIfIsRunningA boolean that indicates whether the infrastructure interface is running.
Return values
OT_ERROR_NONESuccessfully started the Border Routing Manager on given infrastructure.
OT_ERROR_INVALID_STATEThe Border Routing Manager has already been initialized.
OT_ERROR_INVALID_ARGSThe index of the infrastructure interface is not valid.
OT_ERROR_FAILEDInternal failure. Usually due to failure in generating random prefixes.
See also
otPlatInfraIfStateChanged.

◆ otBorderRoutingPrefixTableInitIterator()

void otBorderRoutingPrefixTableInitIterator ( otInstance aInstance,
otBorderRoutingPrefixTableIterator aIterator 
)

This function initializes an otBorderRoutingPrefixTableIterator.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to restart from the beginning of the table.

When iterating over entries in the table, to ensure the update times mMsecSinceLastUpdate of entries are consistent, they are given relative to the time the iterator was initialized.

Parameters
[in]aInstanceThe OpenThread instance.
[out]aIteratorA pointer to the iterator to initialize.

◆ otBorderRoutingSetEnabled()

otError otBorderRoutingSetEnabled ( otInstance aInstance,
bool  aEnabled 
)

Enables or disables the Border Routing Manager.

Note
The Border Routing Manager is disabled by default.
Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aEnabledA boolean to enable/disable the routing manager.
Return values
OT_ERROR_INVALID_STATEThe Border Routing Manager is not initialized yet.
OT_ERROR_NONESuccessfully enabled/disabled the Border Routing Manager.

◆ otBorderRoutingSetRouteInfoOptionPreference()

void otBorderRoutingSetRouteInfoOptionPreference ( otInstance aInstance,
otRoutePreference  aPreference 
)

This function sets the preference to use when advertising Route Info Options in Router Advertisement messages sent over the infrastructure link, for example for discovered OMR prefixes.

By default BR will use medium preference level, but this function allows the default value to be changed. As an example, it can be set to low preference in the case where device is a temporary BR (a mobile BR or a battery-powered BR) to indicate that other BRs (if any) should be preferred over this BR on the infrastructure link.

Parameters
[in]aInstanceA pointer to an OpenThread instance.
[in]aPreferenceThe route preference to use.