Home Original page

History Tracker  |  OpenThread

Records the history of different events, for example RX and TX messages or network info changes.

Summary

All tracked entries are timestamped.

The functions in this module are available when OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE is enabled.

Enumerations
Anonymous Enum 1{
  OT_HISTORY_TRACKER_MSG_PRIORITY_LOW = OT_MESSAGE_PRIORITY_LOW,
  OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL = OT_MESSAGE_PRIORITY_NORMAL,
  OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH = OT_MESSAGE_PRIORITY_HIGH,
  OT_HISTORY_TRACKER_MSG_PRIORITY_NET = OT_MESSAGE_PRIORITY_HIGH + 1
} 		enum

Constants representing message priority used in otHistoryTrackerMessageInfo struct.

otHistoryTrackerAddressEvent{
  OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED = 0,
  OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED = 1
} 		enum

Defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).

otHistoryTrackerAilRouterEvent{
  OT_HISTORY_TRACKER_AIL_ROUTER_EVENT_ADDED = 0,
  OT_HISTORY_TRACKER_AIL_ROUTER_EVENT_CHANGED = 1,
  OT_HISTORY_TRACKER_AIL_ROUTER_EVENT_REMOVED = 2
} 		enum

Defines events for discovered routers on an Adjacent Infrastructure Link (AIL).

otHistoryTrackerBorderAgentEpskcEvent{
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_ACTIVATED,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_CONNECTED,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_PETITIONED,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_RETRIEVED_ACTIVE_DATASET,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_RETRIEVED_PENDING_DATASET,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_KEEP_ALIVE,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_LOCAL_CLOSE,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_REMOTE_CLOSE,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_SESSION_ERROR,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_SESSION_TIMEOUT,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_MAX_ATTEMPTS,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_EPSKC_TIMEOUT,
  OT_HISTORY_TRACKER_BORDER_AGENT_EPSKC_EVENT_DEACTIVATED_UNKNOWN
} 		enum

Represents events during the Border Agent's ePSKc journey.

otHistoryTrackerDnsSrpAddrType{
  OT_HISTORY_TRACKER_DNS_SRP_ADDR_TYPE_UNICAST_LOCAL,
  OT_HISTORY_TRACKER_DNS_SRP_ADDR_TYPE_UNICAST_INFRA,
  OT_HISTORY_TRACKER_DNS_SRP_ADDR_TYPE_ANYCAST
} 		enum

Represents the DNS/SRP server address type parsed from Network Data service entries.

otHistoryTrackerNeighborEvent{
  OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED = 0,
  OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED = 1,
  OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED = 2,
  OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING = 3
} 		enum

Defines the events in a neighbor info (i.e.

otHistoryTrackerNetDataEvent{
  OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED = 0,
  OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED = 1
} 		enum

Defines the events for a Network Data entry (i.e., whether an entry is added or removed).

otHistoryTrackerRouterEvent{
  OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED = 0,
  OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED = 1,
  OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED = 2,
  OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED = 3
} 		enum

Defines the events in a router info (i.e.

Typedefs
otHistoryTrackerAilRouter typedef

Represents information about a discovered router on an Adjacent Infrastructure Link (AIL).

otHistoryTrackerDhcp6PdInfo typedef

Represents the DHCPv6-PD state and delegated prefix (if any) by a device acting as Border Router (BR).

otHistoryTrackerDnsSrpAddrInfo typedef

Represents DNS/SRP server address information parsed from a Network Data service entry.

otHistoryTrackerExternalRouteInfo typedef

Represent a Network Data extern route info.

otHistoryTrackerFavoredOmrPrefix typedef

Represents a favored OMR prefix tracked by a device acting as a Border Router (BR).

otHistoryTrackerFavoredOnLinkPrefix typedef

Represents a favored on-link prefix on AIL tracked by a device acting as a Border Router (BR).

otHistoryTrackerIterator typedef

Represents an iterator to iterate through a history list.

otHistoryTrackerMessageInfo typedef

Represents a RX/TX IPv6 message info.

otHistoryTrackerMulticastAddressInfo typedef

Represent an IPv6 multicast address info.

otHistoryTrackerNeighborInfo typedef

Represents a neighbor info.

otHistoryTrackerNetInfoCallback)(otError aError, const otHistoryTrackerNetworkInfo *aNetworkInfo, uint32_t aEntryAge, void *aContext) typedef

void(*

Callback function pointer type to report the retrieved Network Info entries from a query to another device.

otHistoryTrackerNetworkInfo typedef

Represents Thread network info.

otHistoryTrackerOnMeshPrefixInfo typedef

Represent a Network Data on mesh prefix info.

otHistoryTrackerRouterInfo typedef

Represents a router table entry event.

otHistoryTrackerUnicastAddressInfo typedef

Represent a unicast IPv6 address info.

Functions
otHistoryTrackerCancelQuery(otInstance *aInstance)

void

Cancels any ongoing query.

otHistoryTrackerEntryAgeToString(uint32_t aEntryAge, char *aBuffer, uint16_t aSize)

void

Converts a given entry age to a human-readable string.

otHistoryTrackerInitIterator(otHistoryTrackerIterator *aIterator)

void

Initializes an otHistoryTrackerIterator.

otHistoryTrackerIterateAilRoutersHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the BR AIL routers history list.

otHistoryTrackerIterateBorderAgentEpskcEventHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the Border Agent ePSKc history list.

otHistoryTrackerIterateDhcp6PdHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the DHCPv6-PD history list.

otHistoryTrackerIterateDnsSrpAddrHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the Network Data SRP/DNS address history list.

otHistoryTrackerIterateExternalRouteHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the Network Data external route entry history list.

otHistoryTrackerIterateFavoredOmrPrefixHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the favored OMR prefix history list.

otHistoryTrackerIterateFavoredOnLinkPrefixHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the favored on-link prefix history list.

otHistoryTrackerIterateMulticastAddressHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the multicast address history list.

otHistoryTrackerIterateNeighborHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the neighbor history list.

otHistoryTrackerIterateNetInfoHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the network info history list.

otHistoryTrackerIterateOnMeshPrefixHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the Network Data on mesh prefix entry history list.

otHistoryTrackerIterateRouterHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the router history list.

otHistoryTrackerIterateRxHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the RX message history list.

otHistoryTrackerIterateTxHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the TX message history list.

otHistoryTrackerIterateUnicastAddressHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)

Iterates over the entries in the unicast address history list.

otHistoryTrackerQueryNetInfo(otInstance *aInstance, uint16_t aRloc16, uint16_t aMaxEntries, uint32_t aMaxEntryAge, otHistoryTrackerNetInfoCallback aCallback, void *aContext)

Queries for Network Info history entries from a specified RLOC16.

Macros
OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21

Recommended size for string representation of an entry age.

OT_HISTORY_TRACKER_INFINITE_PATH_COST 0

Infinite path cost - used in otHistoryTrackerRouterInfo.

OT_HISTORY_TRACKER_MAX_AGE (49 * 24 * 60 * 60 * 1000u)

This constant specifies the maximum age of entries which is 49 days (in msec).

OT_HISTORY_TRACKER_NO_NEXT_HOP 63

No next hop - For mNextHop in otHistoryTrackerRouterInfo.

Structs
otHistoryTrackerAilRouter

Represents information about a discovered router on an Adjacent Infrastructure Link (AIL).

otHistoryTrackerDhcp6PdInfo

Represents the DHCPv6-PD state and delegated prefix (if any) by a device acting as Border Router (BR).

otHistoryTrackerDnsSrpAddrInfo

Represents DNS/SRP server address information parsed from a Network Data service entry.

otHistoryTrackerExternalRouteInfo

Represent a Network Data extern route info.

otHistoryTrackerFavoredOmrPrefix

Represents a favored OMR prefix tracked by a device acting as a Border Router (BR).

otHistoryTrackerFavoredOnLinkPrefix

Represents a favored on-link prefix on AIL tracked by a device acting as a Border Router (BR).

otHistoryTrackerIterator

Represents an iterator to iterate through a history list.

otHistoryTrackerMessageInfo

Represents a RX/TX IPv6 message info.

otHistoryTrackerMulticastAddressInfo

Represent an IPv6 multicast address info.

otHistoryTrackerNeighborInfo

Represents a neighbor info.

otHistoryTrackerNetworkInfo

Represents Thread network info.

otHistoryTrackerOnMeshPrefixInfo

Represent a Network Data on mesh prefix info.

otHistoryTrackerRouterInfo

Represents a router table entry event.

otHistoryTrackerUnicastAddressInfo

Represent a unicast IPv6 address info.

Enumerations

Anonymous Enum 1

 Anonymous Enum 1

otHistoryTrackerAddressEvent

 otHistoryTrackerAddressEvent

otHistoryTrackerAilRouterEvent

 otHistoryTrackerAilRouterEvent

otHistoryTrackerBorderAgentEpskcEvent

 otHistoryTrackerBorderAgentEpskcEvent

otHistoryTrackerDnsSrpAddrType

 otHistoryTrackerDnsSrpAddrType

otHistoryTrackerNeighborEvent

 otHistoryTrackerNeighborEvent

otHistoryTrackerNetDataEvent

 otHistoryTrackerNetDataEvent

otHistoryTrackerRouterEvent

 otHistoryTrackerRouterEvent

Typedefs

otHistoryTrackerAilRouter

struct otHistoryTrackerAilRouter otHistoryTrackerAilRouter

Represents information about a discovered router on an Adjacent Infrastructure Link (AIL).

This applies when a device is acting as a Border Router, processing received Router Advertisements and tracking information about discovered AIL routers.

mProvidesDefaultRoute indicates whether the router provides a default route. If it does, mDefRoutePreference specifies the route preference.

mFavoredOnLinkPrefix indicates the favored on-link prefix advertised by the router. If there is no on-link prefix, this will be an empty prefix (i.e., its length will be zero).

otHistoryTrackerDhcp6PdInfo

struct otHistoryTrackerDhcp6PdInfo otHistoryTrackerDhcp6PdInfo

Represents the DHCPv6-PD state and delegated prefix (if any) by a device acting as Border Router (BR).

otHistoryTrackerDnsSrpAddrInfo

struct otHistoryTrackerDnsSrpAddrInfo otHistoryTrackerDnsSrpAddrInfo

Represents DNS/SRP server address information parsed from a Network Data service entry.

The mType field specifies the entry type. Some fields are only applicable to specific types.

  • The mPort field is only applicable for OT_HISTORY_TRACKER_DNS_SRP_ADDR_TYPE_UNICAST_* types.
  • The mSequenceNumber field is only applicable for the OT_HISTORY_TRACKER_DNS_SRP_ADDR_TYPE_ANYCAST type.
  • Other fields are common and used for all address types.

otHistoryTrackerExternalRouteInfo

struct otHistoryTrackerExternalRouteInfo otHistoryTrackerExternalRouteInfo

Represent a Network Data extern route info.

otHistoryTrackerFavoredOmrPrefix

struct otHistoryTrackerFavoredOmrPrefix otHistoryTrackerFavoredOmrPrefix

Represents a favored OMR prefix tracked by a device acting as a Border Router (BR).

The mIsLocal field indicates whether the favored OMR prefix is the same as the local one maintained by this BR. The local OMR prefix can be either based on (random) ULA or a prefix delegated via DHCPv6-PD.

otHistoryTrackerFavoredOnLinkPrefix

struct otHistoryTrackerFavoredOnLinkPrefix otHistoryTrackerFavoredOnLinkPrefix

Represents a favored on-link prefix on AIL tracked by a device acting as a Border Router (BR).

The mIsLocal field indicates whether the favored on-link prefix is the same as the local one maintained by this BR.

otHistoryTrackerIterator

struct otHistoryTrackerIterator otHistoryTrackerIterator

Represents an iterator to iterate through a history list.

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

Before using an iterator, it MUST be initialized using otHistoryTrackerInitIterator(),

otHistoryTrackerMessageInfo

struct otHistoryTrackerMessageInfo otHistoryTrackerMessageInfo

Represents a RX/TX IPv6 message info.

Some of the fields in this struct are applicable to a RX message or a TX message only, e.g., mAveRxRss is the average RSS of all fragment frames that form a received message and is only applicable for a RX message.

otHistoryTrackerMulticastAddressInfo

struct otHistoryTrackerMulticastAddressInfo otHistoryTrackerMulticastAddressInfo

Represent an IPv6 multicast address info.

otHistoryTrackerNeighborInfo

struct otHistoryTrackerNeighborInfo otHistoryTrackerNeighborInfo

Represents a neighbor info.

otHistoryTrackerNetInfoCallback

void(* otHistoryTrackerNetInfoCallback)(otError aError, const otHistoryTrackerNetworkInfo *aNetworkInfo, uint32_t aEntryAge, void *aContext)

Callback function pointer type to report the retrieved Network Info entries from a query to another device.

Used when OPENTHREAD_CONFIG_HISTORY_TRACKER_CLIENT_ENABLE is enabled.

Details
Parameters
[in] aError

Indicates the status of the query and entries being reported:

  • OT_ERROR_PENDING: There are more entries to be reported.
  • OT_ERROR_NONE: This is the last entry, and the query is complete.
  • OT_ERROR_RESPONSE_TIMEOUT: Timed out waiting for a response.
  • OT_ERROR_PARSE: The received query answer does not follow the expected format.
[in] aNetworkInfo

The network information entry. This may be NULL if aError is OT_ERROR_NONE (indicating the end of the list) or on certain error conditions.

[in] aEntryAge

The entry age in milliseconds. Applicable only when aNetworkInfo is not NULL.

[in] aContext

An arbitrary callback context provided by the caller during the query.

otHistoryTrackerNetworkInfo

struct otHistoryTrackerNetworkInfo otHistoryTrackerNetworkInfo

Represents Thread network info.

otHistoryTrackerOnMeshPrefixInfo

struct otHistoryTrackerOnMeshPrefixInfo otHistoryTrackerOnMeshPrefixInfo

Represent a Network Data on mesh prefix info.

otHistoryTrackerRouterInfo

struct otHistoryTrackerRouterInfo otHistoryTrackerRouterInfo

Represents a router table entry event.

otHistoryTrackerUnicastAddressInfo

struct otHistoryTrackerUnicastAddressInfo otHistoryTrackerUnicastAddressInfo

Represent a unicast IPv6 address info.

Functions

otHistoryTrackerCancelQuery

void otHistoryTrackerCancelQuery(
  otInstance *aInstance
)

Cancels any ongoing query.

Requires OPENTHREAD_CONFIG_HISTORY_TRACKER_CLIENT_ENABLE.

Details
Parameters
[in] aInstance

The OpenThread instance.

otHistoryTrackerEntryAgeToString

void otHistoryTrackerEntryAgeToString(
  uint32_t aEntryAge,
  char *aBuffer,
  uint16_t aSize
)

Converts a given entry age to a human-readable string.

The entry age string follows the format hours:minutes:seconds:milliseconds (if shorter than one day) or days:hours:minutes:seconds(if longer than one day).

If the resulting string does not fit in aBuffer (within its aSize characters), the string will be truncated but the outputted string is always null-terminated.

Details
Parameters
[in] aEntryAge

The entry age (duration in msec).

[out] aBuffer

A pointer to a char array to output the string (MUST NOT be NULL).

[in] aSize

The size of aBuffer. Recommended to use OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE.

otHistoryTrackerInitIterator

void otHistoryTrackerInitIterator(
  otHistoryTrackerIterator *aIterator
)

Initializes an otHistoryTrackerIterator.

An iterator MUST be initialized before it is used.

An iterator can be initialized again to start from the beginning of the list.

When iterating over entries in a list, to ensure the entry ages are consistent, the age is given relative to the time the iterator was initialized, i.e., the entry age is provided as the duration (in milliseconds) from the event (when entry was recorded) to the iterator initialization time.

Details
Parameters
[in] aIterator

A pointer to the iterator to initialize (MUST NOT be NULL).

otHistoryTrackerIterateAilRoutersHistory

const otHistoryTrackerAilRouter * otHistoryTrackerIterateAilRoutersHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the BR AIL routers history list.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE (device acting as Border Router).

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when the entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than the max age.
Returns

The otHistoryTrackerAilRouter entry or NULL if no more entries in the list.

otHistoryTrackerIterateBorderAgentEpskcEventHistory

const otHistoryTrackerBorderAgentEpskcEvent * otHistoryTrackerIterateBorderAgentEpskcEventHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the Border Agent ePSKc history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerBorderAgentEpskcEvent entry or NULL if no more entries in the list.

otHistoryTrackerIterateDhcp6PdHistory

const otHistoryTrackerDhcp6PdInfo * otHistoryTrackerIterateDhcp6PdHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the DHCPv6-PD history list.

Requires both OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE and OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerDhcp6PdInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateDnsSrpAddrHistory

const otHistoryTrackerDnsSrpAddrInfo * otHistoryTrackerIterateDnsSrpAddrHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the Network Data SRP/DNS address history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerDnsSrpAddrInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateExternalRouteHistory

const otHistoryTrackerExternalRouteInfo * otHistoryTrackerIterateExternalRouteHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the Network Data external route entry history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerExternalRouteInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateFavoredOmrPrefixHistory

const otHistoryTrackerFavoredOmrPrefix * otHistoryTrackerIterateFavoredOmrPrefixHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the favored OMR prefix history list.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE (device acting as Border Router).

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerFavoredOmrPrefix entry or NULL if no more entries in the list.

otHistoryTrackerIterateFavoredOnLinkPrefixHistory

const otHistoryTrackerFavoredOnLinkPrefix * otHistoryTrackerIterateFavoredOnLinkPrefixHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the favored on-link prefix history list.

Requires OPENTHREAD_CONFIG_BORDER_ROUTING_ENABLE (device acting as Border Router).

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when the entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than the max age.
Returns

The otHistoryTrackerFavoredOnLinkPrefix entry or NULL if no more entries in the list.

otHistoryTrackerIterateMulticastAddressHistory

const otHistoryTrackerMulticastAddressInfo * otHistoryTrackerIterateMulticastAddressHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the multicast address history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

A pointer to otHistoryTrackerMulticastAddressInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateNeighborHistory

const otHistoryTrackerNeighborInfo * otHistoryTrackerIterateNeighborHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the neighbor history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerNeighborInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateNetInfoHistory

const otHistoryTrackerNetworkInfo * otHistoryTrackerIterateNetInfoHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the network info history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

A pointer to otHistoryTrackerNetworkInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateOnMeshPrefixHistory

const otHistoryTrackerOnMeshPrefixInfo * otHistoryTrackerIterateOnMeshPrefixHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the Network Data on mesh prefix entry history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerOnMeshPrefixInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateRouterHistory

const otHistoryTrackerRouterInfo * otHistoryTrackerIterateRouterHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the router history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerRouterInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateRxHistory

const otHistoryTrackerMessageInfo * otHistoryTrackerIterateRxHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the RX message history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerMessageInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateTxHistory

const otHistoryTrackerMessageInfo * otHistoryTrackerIterateTxHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the TX message history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

The otHistoryTrackerMessageInfo entry or NULL if no more entries in the list.

otHistoryTrackerIterateUnicastAddressHistory

const otHistoryTrackerUnicastAddressInfo * otHistoryTrackerIterateUnicastAddressHistory(
  otInstance *aInstance,
  otHistoryTrackerIterator *aIterator,
  uint32_t *aEntryAge
)

Iterates over the entries in the unicast address history list.

Details
Parameters
[in] aInstance

A pointer to the OpenThread instance.

[in,out] aIterator

A pointer to an iterator. MUST be initialized or the behavior is undefined.

[out] aEntryAge

A pointer to a variable to output the entry's age. MUST NOT be NULL. Age is provided as the duration (in milliseconds) from when entry was recorded to aIterator initialization time. It is set to OT_HISTORY_TRACKER_MAX_AGE for entries older than max age.
Returns

A pointer to otHistoryTrackerUnicastAddressInfo entry or NULL if no more entries in the list.

otHistoryTrackerQueryNetInfo

otError otHistoryTrackerQueryNetInfo(
  otInstance *aInstance,
  uint16_t aRloc16,
  uint16_t aMaxEntries,
  uint32_t aMaxEntryAge,
  otHistoryTrackerNetInfoCallback aCallback,
  void *aContext
)

Queries for Network Info history entries from a specified RLOC16.

Requires OPENTHREAD_CONFIG_HISTORY_TRACKER_CLIENT_ENABLE.

Upon successful initiation of the query, the provided aCallback will be invoked to report the requested entries.

The callback parameter aError indicates if any error occurs. If there are more entries to be provided, aError will be set to OT_ERROR_PENDING. The end of the list is indicated by aError being set to OT_ERROR_NONE with a null entry pointer. Any other errors, such as OT_ERROR_RESPONSE_TIMEOUT or OT_ERROR_PARSE (if the received response has an invalid format), will also be indicated by aError.

Details
Parameters
[in] aInstance

The OpenThread instance.

[in] aRloc16

The RLOC16 of the device to query.

[in] aMaxEntries

The maximum number of entries to request (0 indicates all available entries).

[in] aMaxEntryAge

The maximum age (in milliseconds) of entries to request (0 indicates no age limit).

[in] aCallback

A pointer to a callback function to be called when the query response is received.

[in] aContext

A user-defined context pointer to be passed to the callback function.
Return Values
OT_ERROR_NONE

If the query was successfully sent.

OT_ERROR_BUSY

If a query is already in progress.

OT_ERROR_NO_BUFS

If there are insufficient message buffers to send the query.

OT_ERROR_INVALID_STATE

If device is not attached.

Macros

OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE

 OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21

Recommended size for string representation of an entry age.

OT_HISTORY_TRACKER_INFINITE_PATH_COST

 OT_HISTORY_TRACKER_INFINITE_PATH_COST 0

OT_HISTORY_TRACKER_MAX_AGE

 OT_HISTORY_TRACKER_MAX_AGE (49 * 24 * 60 * 60 * 1000u)

This constant specifies the maximum age of entries which is 49 days (in msec).

Entries older than the max age will give this value as their age.

OT_HISTORY_TRACKER_NO_NEXT_HOP

 OT_HISTORY_TRACKER_NO_NEXT_HOP 63

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.