History Tracker#
Records the history of different events, for example RX and TX messages or network info changes.
All tracked entries are timestamped.
The functions in this module are available when OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE
is enabled.
Modules#
otHistoryTrackerUnicastAddressInfo
otHistoryTrackerMulticastAddressInfo
otHistoryTrackerOnMeshPrefixInfo
otHistoryTrackerExternalRouteInfo
Enumerations#
Defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).
Constants representing message priority used in otHistoryTrackerMessageInfo
struct.
Defines the events in a neighbor info (i.e.
Defines the events in a router info (i.e.
Defines the events for a Network Data entry (i.e., whether an entry is added or removed).
Typedefs#
Represents an iterator to iterate through a history list.
Represents Thread network info.
Represent a unicast IPv6 address info.
Represent an IPv6 multicast address info.
Represents a RX/TX IPv6 message info.
Represents a neighbor info.
Represents a router table entry event.
Represent a Network Data on mesh prefix info.
Represent a Network Data extern route info.
Functions#
Initializes an otHistoryTrackerIterator
.
Iterates over the entries in the network info history list.
Iterates over the entries in the unicast address history list.
Iterates over the entries in the multicast address history list.
Iterates over the entries in the RX message history list.
Iterates over the entries in the TX message history list.
Iterates over the entries in the neighbor history list.
Iterates over the entries in the router history list.
Iterates over the entries in the Network Data on mesh prefix entry history list.
Iterates over the entries in the Network Data external route entry history list.
Converts a given entry age to a human-readable string.
Macros#
This constant specifies the maximum age of entries which is 49 days (in msec).
Recommended size for string representation of an entry age.
No next hop - For mNextHop
in otHistoryTrackerRouterInfo
.
Infinite path cost - used in otHistoryTrackerRouterInfo
.
Enumeration Documentation#
otHistoryTrackerAddressEvent#
otHistoryTrackerAddressEvent
Defines the events for an IPv6 (unicast or multicast) address info (i.e., whether address is added or removed).
Enumerator | |
---|---|
OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED | Address is added. |
OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED | Address is removed. |
94
of file include/openthread/history_tracker.h
@1#
@1
Constants representing message priority used in otHistoryTrackerMessageInfo
struct.
Enumerator | |
---|---|
OT_HISTORY_TRACKER_MSG_PRIORITY_LOW | Low priority level. |
OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL | Normal priority level. |
OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH | High priority level. |
OT_HISTORY_TRACKER_MSG_PRIORITY_NET | Network Control priority level. |
131
of file include/openthread/history_tracker.h
otHistoryTrackerNeighborEvent#
otHistoryTrackerNeighborEvent
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.
Enumerator | |
---|---|
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED | Neighbor is added. |
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED | Neighbor is removed. |
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED | Neighbor changed (e.g., device mode flags changed). |
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING | Neighbor is being restored (applicable to child only). |
171
of file include/openthread/history_tracker.h
otHistoryTrackerRouterEvent#
otHistoryTrackerRouterEvent
Defines the events in a router info (i.e.
whether router is added, removed, or changed).
Enumerator | |
---|---|
OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED | Router is added (router ID allocated). |
OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED | Router entry is removed (router ID released). |
OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED | Router entry next hop and cost changed. |
OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED | Router entry path cost changed (next hop as before). |
199
of file include/openthread/history_tracker.h
otHistoryTrackerNetDataEvent#
otHistoryTrackerNetDataEvent
Defines the events for a Network Data entry (i.e., whether an entry is added or removed).
Enumerator | |
---|---|
OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED | Network data entry is added. |
OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED | Network data entry is removed. |
228
of file include/openthread/history_tracker.h
Typedef Documentation#
otHistoryTrackerIterator#
typedef 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()
,
75
of file include/openthread/history_tracker.h
otHistoryTrackerNetworkInfo#
typedef struct otHistoryTrackerNetworkInfo otHistoryTrackerNetworkInfo
Represents Thread network info.
87
of file include/openthread/history_tracker.h
otHistoryTrackerUnicastAddressInfo#
typedef struct otHistoryTrackerUnicastAddressInfo otHistoryTrackerUnicastAddressInfo
Represent a unicast IPv6 address info.
114
of file include/openthread/history_tracker.h
otHistoryTrackerMulticastAddressInfo#
typedef struct otHistoryTrackerMulticastAddressInfo otHistoryTrackerMulticastAddressInfo
Represent an IPv6 multicast address info.
125
of file include/openthread/history_tracker.h
otHistoryTrackerMessageInfo#
typedef 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.
161
of file include/openthread/history_tracker.h
otHistoryTrackerNeighborInfo#
typedef struct otHistoryTrackerNeighborInfo otHistoryTrackerNeighborInfo
Represents a neighbor info.
193
of file include/openthread/history_tracker.h
otHistoryTrackerRouterInfo#
typedef struct otHistoryTrackerRouterInfo otHistoryTrackerRouterInfo
Represents a router table entry event.
222
of file include/openthread/history_tracker.h
otHistoryTrackerOnMeshPrefixInfo#
typedef struct otHistoryTrackerOnMeshPrefixInfo otHistoryTrackerOnMeshPrefixInfo
Represent a Network Data on mesh prefix info.
242
of file include/openthread/history_tracker.h
otHistoryTrackerExternalRouteInfo#
typedef struct otHistoryTrackerExternalRouteInfo otHistoryTrackerExternalRouteInfo
Represent a Network Data extern route info.
252
of file include/openthread/history_tracker.h
Function Documentation#
otHistoryTrackerInitIterator#
void otHistoryTrackerInitIterator (otHistoryTrackerIterator * aIterator)
Initializes an otHistoryTrackerIterator
.
[in] | aIterator | A pointer to the iterator to initialize (MUST NOT be NULL). |
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.
268
of file include/openthread/history_tracker.h
otHistoryTrackerIterateNetInfoHistory#
const otHistoryTrackerNetworkInfo * otHistoryTrackerIterateNetInfoHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the network info history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
A pointer to
otHistoryTrackerNetworkInfo
entry orNULL
if no more entries in the list.
283
of file include/openthread/history_tracker.h
otHistoryTrackerIterateUnicastAddressHistory#
const otHistoryTrackerUnicastAddressInfo * otHistoryTrackerIterateUnicastAddressHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the unicast address history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
A pointer to
otHistoryTrackerUnicastAddressInfo
entry orNULL
if no more entries in the list.
300
of file include/openthread/history_tracker.h
otHistoryTrackerIterateMulticastAddressHistory#
const otHistoryTrackerMulticastAddressInfo * otHistoryTrackerIterateMulticastAddressHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the multicast address history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
A pointer to
otHistoryTrackerMulticastAddressInfo
entry orNULL
if no more entries in the list.
318
of file include/openthread/history_tracker.h
otHistoryTrackerIterateRxHistory#
const otHistoryTrackerMessageInfo * otHistoryTrackerIterateRxHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the RX message history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
The
otHistoryTrackerMessageInfo
entry orNULL
if no more entries in the list.
336
of file include/openthread/history_tracker.h
otHistoryTrackerIterateTxHistory#
const otHistoryTrackerMessageInfo * otHistoryTrackerIterateTxHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the TX message history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
The
otHistoryTrackerMessageInfo
entry orNULL
if no more entries in the list.
353
of file include/openthread/history_tracker.h
otHistoryTrackerIterateNeighborHistory#
const otHistoryTrackerNeighborInfo * otHistoryTrackerIterateNeighborHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the neighbor history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
The
otHistoryTrackerNeighborInfo
entry orNULL
if no more entries in the list.
370
of file include/openthread/history_tracker.h
otHistoryTrackerIterateRouterHistory#
const otHistoryTrackerRouterInfo * otHistoryTrackerIterateRouterHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the router history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
The
otHistoryTrackerRouterInfo
entry orNULL
if no more entries in the list.
387
of file include/openthread/history_tracker.h
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.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
The
otHistoryTrackerOnMeshPrefixInfo
entry orNULL
if no more entries in the list.
404
of file include/openthread/history_tracker.h
otHistoryTrackerIterateExternalRouteHistory#
const otHistoryTrackerExternalRouteInfo * otHistoryTrackerIterateExternalRouteHistory (otInstance * aInstance, otHistoryTrackerIterator * aIterator, uint32_t * aEntryAge)
Iterates over the entries in the Network Data external route entry history list.
[in] | aInstance | A pointer to the OpenThread instance. |
[inout] | 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 |
Returns
The
otHistoryTrackerExternalRouteInfo
entry orNULL
if no more entries in the list.
421
of file include/openthread/history_tracker.h
otHistoryTrackerEntryAgeToString#
void otHistoryTrackerEntryAgeToString (uint32_t aEntryAge, char * aBuffer, uint16_t aSize)
Converts a given entry age to a human-readable string.
[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 |
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.
440
of file include/openthread/history_tracker.h
Macro Definition Documentation#
OT_HISTORY_TRACKER_MAX_AGE#
#define OT_HISTORY_TRACKER_MAX_AGEValue:
(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.
58
of file include/openthread/history_tracker.h
OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE#
#define OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZEValue:
21
Recommended size for string representation of an entry age.
60
of file include/openthread/history_tracker.h
OT_HISTORY_TRACKER_NO_NEXT_HOP#
#define OT_HISTORY_TRACKER_NO_NEXT_HOPValue:
63
No next hop - For mNextHop
in otHistoryTrackerRouterInfo
.
207
of file include/openthread/history_tracker.h
OT_HISTORY_TRACKER_INFINITE_PATH_COST#
#define OT_HISTORY_TRACKER_INFINITE_PATH_COSTValue:
0
Infinite path cost - used in otHistoryTrackerRouterInfo
.
209
of file include/openthread/history_tracker.h