History Tracker

Summary

Enumerations

anonymous enum{
  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
This enumeration defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).
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
This enumeration defines the events in a neighbor info (i.e.

Typedefs

otHistoryTrackerIterator typedef
This type represents an iterator to iterate through a history list.
otHistoryTrackerMessageInfo typedef
This structure represents a RX/TX IPv6 message info.
otHistoryTrackerMulticastAddressInfo typedef
This structure represent an IPv6 multicast address info.
otHistoryTrackerNeighborInfo typedef
This structure represents a neighbor info.
otHistoryTrackerNetworkInfo typedef
This structure represents Thread network info.
otHistoryTrackerUnicastAddressInfo typedef
This structure represent a unicast IPv6 address info.

Functions

otHistoryTrackerEntryAgeToString(uint32_t aEntryAge, char *aBuffer, uint16_t aSize)
void
This function converts a given entry age to a human-readable string.
otHistoryTrackerInitIterator(otHistoryTrackerIterator *aIterator)
void
This function initializes an otHistoryTrackerIterator.
otHistoryTrackerIterateMulticastAddressHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)
This function iterates over the entries in the multicast address history list.
otHistoryTrackerIterateNeighborHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)
This function iterates over the entries in the neighbor history list.
otHistoryTrackerIterateNetInfoHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)
This function iterates over the entries in the network info history list.
otHistoryTrackerIterateRxHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)
This function iterates over the entries in the RX message history list.
otHistoryTrackerIterateTxHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)
This function iterates over the entries in the TX message history list.
otHistoryTrackerIterateUnicastAddressHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)
This function iterates over the entries in the unicast address history list.

Structs

otHistoryTrackerIterator

This type represents an iterator to iterate through a history list.

otHistoryTrackerMessageInfo

This structure represents a RX/TX IPv6 message info.

otHistoryTrackerMulticastAddressInfo

This structure represent an IPv6 multicast address info.

otHistoryTrackerNeighborInfo

This structure represents a neighbor info.

otHistoryTrackerNetworkInfo

This structure represents Thread network info.

otHistoryTrackerUnicastAddressInfo

This structure represent a unicast IPv6 address info.

Enumerations

anonymous enum

 anonymous enum

Constants representing message priority used in otHistoryTrackerMessageInfo struct.

Properties
OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH

High priority level.

OT_HISTORY_TRACKER_MSG_PRIORITY_LOW

Low priority level.

OT_HISTORY_TRACKER_MSG_PRIORITY_NET

Network Control priority level.

OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL

Normal priority level.

otHistoryTrackerAddressEvent

 otHistoryTrackerAddressEvent

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

Properties
OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED

Address is added.

OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED

Address is removed.

otHistoryTrackerNeighborEvent

 otHistoryTrackerNeighborEvent

This enumeration defines the events in a neighbor info (i.e.

whether neighbor is added, removed, or changed).

Event OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING is applicable to child neighbors only. It is triggered after the device (re)starts and when the previous children list is retrieved from non-volatile settings and the device tries to restore connection to them.

Properties
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED

Neighbor is added.

OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED

Neighbor changed (e.g., device mode flags changed).

OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED

Neighbor is removed.

OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING

Neighbor is being restored (applicable to child only).

Typedefs

otHistoryTrackerIterator

struct otHistoryTrackerIterator otHistoryTrackerIterator

This type 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

This structure 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

This structure represent an IPv6 multicast address info.

otHistoryTrackerNeighborInfo

struct otHistoryTrackerNeighborInfo otHistoryTrackerNeighborInfo

This structure represents a neighbor info.

otHistoryTrackerNetworkInfo

struct otHistoryTrackerNetworkInfo otHistoryTrackerNetworkInfo

This structure represents Thread network info.

otHistoryTrackerUnicastAddressInfo

struct otHistoryTrackerUnicastAddressInfo otHistoryTrackerUnicastAddressInfo

This structure represent a unicast IPv6 address info.

Functions

otHistoryTrackerEntryAgeToString

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

This function converts a given entry age to a human-readable string.

The entry age string follows the format "::." for hours, minutes, seconds and millisecond (if shorter than one day) or "

days ::." (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
)

This function 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).

otHistoryTrackerIterateMulticastAddressHistory

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

This function 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
)

This function 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
)

This function 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.

otHistoryTrackerIterateRxHistory

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

This function 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
)

This function 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
)

This function 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.

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_MAX_AGE

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

This header defines the public API for History Tracker.

History Tracker module records history of different events (e.g. RX and TX messages or network info changes, etc.) as the Thread network operates. All tracked entries are timestamped.

The functions in this module are available when OPENTHREAD_CONFIG_HISTOR_TRACKER_ENABLE is enabled. 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.