历史记录跟踪器

记录不同事件的历史记录，例如 RX 和 TX 消息或网络信息更改。

摘要

所有跟踪的条目都带有时间戳。

启用 OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE 后，即可使用此模块中的函数。

枚举
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 }	枚举 表示 otHistoryTrackerMessageInfo 结构体中使用的消息优先级的常量。
otHistoryTrackerAddressEvent{   OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED = 0,   OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED = 1 }	枚举 定义 IPv6（单播或多播）地址信息（即是添加或移除地址）的事件。
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 }	枚举 定义相邻信息（即
otHistoryTrackerNetDataEvent{   OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED = 0,   OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED = 1 }	枚举 定义网络数据条目的事件（例如，添加或移除条目）。
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 }	枚举 定义路由器信息（即

类型定义符
otHistoryTrackerExternalRouteInfo	typedef struct otHistoryTrackerExternalRouteInfo 表示网络数据外部路由信息。
otHistoryTrackerIterator	typedef struct otHistoryTrackerIterator 表示用于遍历历史记录列表的迭代器。
otHistoryTrackerMessageInfo	typedef struct otHistoryTrackerMessageInfo 表示 RX/TX IPv6 消息信息。
otHistoryTrackerMulticastAddressInfo	typedef struct otHistoryTrackerMulticastAddressInfo 表示 IPv6 多播地址信息。
otHistoryTrackerNeighborInfo	typedef struct otHistoryTrackerNeighborInfo 表示邻近对象信息。
otHistoryTrackerNetworkInfo	typedef struct otHistoryTrackerNetworkInfo 表示线程网络信息。
otHistoryTrackerOnMeshPrefixInfo	typedef struct otHistoryTrackerOnMeshPrefixInfo 表示关于网状网前缀信息的网络数据。
otHistoryTrackerRouterInfo	typedef struct otHistoryTrackerRouterInfo 表示路由器表条目事件。
otHistoryTrackerUnicastAddressInfo	typedef struct otHistoryTrackerUnicastAddressInfo 表示单播 IPv6 地址信息。

函数
otHistoryTrackerEntryAgeToString(uint32_t aEntryAge, char *aBuffer, uint16_t aSize)	void 将指定的条目存在时间转换为直观易懂的字符串。
otHistoryTrackerInitIterator(otHistoryTrackerIterator *aIterator)	void 初始化 otHistoryTrackerIterator。
otHistoryTrackerIterateExternalRouteHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerExternalRouteInfo * 遍历网络数据外部路由条目历史记录列表中的条目。
otHistoryTrackerIterateMulticastAddressHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerMulticastAddressInfo * 遍历多播地址历史记录列表中的条目。
otHistoryTrackerIterateNeighborHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerNeighborInfo * 遍历相邻历史记录列表中的条目。
otHistoryTrackerIterateNetInfoHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerNetworkInfo * 遍历网络信息历史记录列表中的条目。
otHistoryTrackerIterateOnMeshPrefixHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerOnMeshPrefixInfo * 遍历网状网前缀条目历史记录列表中的网络数据条目。
otHistoryTrackerIterateRouterHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerRouterInfo * 遍历路由器历史记录列表中的条目。
otHistoryTrackerIterateRxHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerMessageInfo * 遍历 RX 消息历史记录列表中的条目。
otHistoryTrackerIterateTxHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerMessageInfo * 遍历 TX 消息记录列表中的条目。
otHistoryTrackerIterateUnicastAddressHistory(otInstance *aInstance, otHistoryTrackerIterator *aIterator, uint32_t *aEntryAge)	const otHistoryTrackerUnicastAddressInfo * 遍历单播地址历史记录列表中的条目。

结构体
otHistoryTrackerExternalRouteInfo 类	表示网络数据外部路由信息。
otHistoryTrackerIterator 类	表示用于遍历历史记录列表的迭代器。
otHistoryTrackerMessageInfo	表示 RX/TX IPv6 消息信息。
otHistoryTrackerMulticastAddressInfo	表示 IPv6 多播地址信息。
otHistoryTrackerNeighborInfo	表示邻近对象信息。
otHistoryTrackerNetworkInfo	表示线程网络信息。
otHistoryTrackerOnMeshPrefixInfo	表示关于网状网前缀信息的网络数据。
otHistoryTrackerRouterInfo	表示路由器表条目事件。
otHistoryTrackerUnicastAddressInfo	表示单播 IPv6 地址信息。

枚举

匿名枚举

 anonymous enum

表示 otHistoryTrackerMessageInfo 结构体中使用的消息优先级的常量。

属性
OT_HISTORY_TRACKER_MSG_PRIORITY_HIGH	高优先级。
OT_HISTORY_TRACKER_MSG_PRIORITY_LOW	低优先级。
OT_HISTORY_TRACKER_MSG_PRIORITY_NET	网络控制优先级。
OT_HISTORY_TRACKER_MSG_PRIORITY_NORMAL	普通优先级。

otHistoryTrackerAddressEvent

 otHistoryTrackerAddressEvent

定义 IPv6（单播或多播）地址信息（即是添加或移除地址）的事件。

属性
OT_HISTORY_TRACKER_ADDRESS_EVENT_ADDED	已添加地址。
OT_HISTORY_TRACKER_ADDRESS_EVENT_REMOVED	已移除此地址。

otHistoryTrackerNeighborEvent

 otHistoryTrackerNeighborEvent

定义相邻信息（即

添加、移除或更改相邻项）。

事件 OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING 仅适用于子相邻项。该事件会在设备启动（重启）以及从非易失性设置中检索到之前的子项列表且设备尝试恢复与这些子项的连接时触发。

属性
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_ADDED	已添加邻居。
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_CHANGED	邻居已更改（例如，设备模式标志已更改）。
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_REMOVED	邻居已移除。
OT_HISTORY_TRACKER_NEIGHBOR_EVENT_RESTORING	正在恢复邻居（仅适用于孩子）。

otHistoryTrackerNetDataEvent

 otHistoryTrackerNetDataEvent

定义网络数据条目的事件（例如，添加或移除条目）。

属性
OT_HISTORY_TRACKER_NET_DATA_ENTRY_ADDED	添加了网络数据条目。
OT_HISTORY_TRACKER_NET_DATA_ENTRY_REMOVED	移除了网络数据条目。

otHistoryTrackerRouterEvent

 otHistoryTrackerRouterEvent

定义路由器信息（即

添加、移除或更改路由器。

属性
OT_HISTORY_TRACKER_ROUTER_EVENT_ADDED	已添加路由器（已分配路由器 ID）。
OT_HISTORY_TRACKER_ROUTER_EVENT_COST_CHANGED	路由器条目路径费用已更改（下一个跃点和以前一样）。
OT_HISTORY_TRACKER_ROUTER_EVENT_NEXT_HOP_CHANGED	路由器条目的下一个跃点和费用已更改。
OT_HISTORY_TRACKER_ROUTER_EVENT_REMOVED	路由器条目已删除（路由器 ID 已释放）。

类型定义符

otHistoryTrackerExternalRouteInfo

struct otHistoryTrackerExternalRouteInfo otHistoryTrackerExternalRouteInfo

表示网络数据外部路由信息。

otHistoryTrackerIterator

struct otHistoryTrackerIterator otHistoryTrackerIterator

表示用于遍历历史记录列表的迭代器。

此类型的字段是不透明的（供 OpenThread 核心使用），因此调用方不应访问/使用这些字段。

在使用迭代器之前，必须先使用 otHistoryTrackerInitIterator() 对其进行初始化，

otHistoryTrackerMessageInfo

struct otHistoryTrackerMessageInfo otHistoryTrackerMessageInfo

表示 RX/TX IPv6 消息信息。

此结构体中的某些字段仅适用于 RX 消息或 TX 消息，例如，mAveRxRss 是构成所接收消息的所有 fragment 帧的平均 RSS，仅适用于 RX 消息。

otHistoryTrackerMulticastAddressInfo

struct otHistoryTrackerMulticastAddressInfo otHistoryTrackerMulticastAddressInfo

表示 IPv6 多播地址信息。

otHistoryTrackerNeighborInfo

struct otHistoryTrackerNeighborInfo otHistoryTrackerNeighborInfo

表示邻近对象信息。

otHistoryTrackerNetworkInfo

struct otHistoryTrackerNetworkInfo otHistoryTrackerNetworkInfo

表示线程网络信息。

otHistoryTrackerOnMeshPrefixInfo

struct otHistoryTrackerOnMeshPrefixInfo otHistoryTrackerOnMeshPrefixInfo

表示关于网状网前缀信息的网络数据。

otHistoryTrackerRouterInfo

struct otHistoryTrackerRouterInfo otHistoryTrackerRouterInfo

表示路由器表条目事件。

otHistoryTrackerUnicastAddressInfo

struct otHistoryTrackerUnicastAddressInfo otHistoryTrackerUnicastAddressInfo

表示单播 IPv6 地址信息。

函数

otHistoryTrackerEntryAgeToString

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

将指定的条目存在时间转换为直观易懂的字符串。

条目的存在时间字符串采用“::.”格式，表示小时、分钟、秒和毫秒（如果少于一天），或“

天 ::.”（如果超过一天）。

如果生成的字符串不适合 aBuffer（在其 aSize 字符内），该字符串将被截断，但输出的字符串始终以空字符结尾。

具体说明
参数	[in] aEntryAge 条目存在时间（时长，以毫秒为单位）。 [out] aBuffer 指向用于输出字符串的字符数组的指针（不得为 NULL）。 [in] aSize aBuffer 的大小。建议使用 OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE。

otHistoryTrackerInitIterator

void otHistoryTrackerInitIterator(
  otHistoryTrackerIterator *aIterator
)

初始化 otHistoryTrackerIterator。

在使用迭代器之前，必须先对其进行初始化。

您可以再次初始化迭代器，以便从列表的开头开始。

遍历列表中的条目时，为了确保条目的存在时间保持一致，系统会以迭代器初始化的时间为参照点指定存在时间，即条目存在时间是指从事件（记录条目时）到迭代器初始化时间的时长（以毫秒为单位）。

具体说明
参数	[in] aIterator 指向要初始化的迭代器的指针（不得为 NULL）。

otHistoryTrackerIterateExternalRouteHistory

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

遍历网络数据外部路由条目历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	otHistoryTrackerExternalRouteInfo 条目；如果列表中没有其他条目，则返回 NULL。

otHistoryTrackerIterateMulticastAddressHistory

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

遍历多播地址历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	指向 otHistoryTrackerMulticastAddressInfo 条目的指针，如果列表中没有更多条目，则返回 NULL。

otHistoryTrackerIterateNeighborHistory

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

遍历相邻历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	otHistoryTrackerNeighborInfo 条目；如果列表中没有其他条目，则返回 NULL。

otHistoryTrackerIterateNetInfoHistory

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

遍历网络信息历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	指向 otHistoryTrackerNetworkInfo 条目的指针，如果列表中没有更多条目，则返回 NULL。

otHistoryTrackerIterateOnMeshPrefixHistory

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

遍历网状网前缀条目历史记录列表中的网络数据条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	otHistoryTrackerOnMeshPrefixInfo 条目；如果列表中没有其他条目，则返回 NULL。

otHistoryTrackerIterateRouterHistory

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

遍历路由器历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	otHistoryTrackerRouterInfo 条目；如果列表中没有其他条目，则返回 NULL。

otHistoryTrackerIterateRxHistory

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

遍历 RX 消息历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	otHistoryTrackerMessageInfo 条目；如果列表中没有其他条目，则返回 NULL。

otHistoryTrackerIterateTxHistory

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

遍历 TX 消息记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	otHistoryTrackerMessageInfo 条目；如果列表中没有其他条目，则返回 NULL。

otHistoryTrackerIterateUnicastAddressHistory

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

遍历单播地址历史记录列表中的条目。

具体说明
参数	[in] aInstance 指向 OpenThread 实例的指针。 [in,out] aIterator 指向迭代器的指针。必须进行初始化，或者未定义行为。 [out] aEntryAge 指向用于输出条目存在时间的变量的指针。不得为 NULL。存在时间是指从记录条目到 aIterator 初始化时间的时长（以毫秒为单位）。对于超过最长存在时间的条目，此字段设为 OT_HISTORY_TRACKER_MAX_AGE。
返回值	指向 otHistoryTrackerUnicastAddressInfo 条目的指针，如果列表中没有更多条目，则返回 NULL。

宏

OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE

 OT_HISTORY_TRACKER_ENTRY_AGE_STRING_SIZE 21

条目年龄的字符串表示形式的建议大小。

OT_HISTORY_TRACKER_INFINITE_PATH_COST

 OT_HISTORY_TRACKER_INFINITE_PATH_COST 0

无限路径费用 - 在 otHistoryTrackerRouterInfo 中使用。

OT_HISTORY_TRACKER_MAX_AGE

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

该常量指定条目的最长存在时间，即 49 天（以毫秒为单位）。

超过年龄上限的条目将以此值作为其年龄。

OT_HISTORY_TRACKER_NO_NEXT_HOP

 OT_HISTORY_TRACKER_NO_NEXT_HOP 63

没有下一个跃点 - 针对 otHistoryTrackerRouterInfo 中的 mNextHop。

资源

OpenThread API 参考文档源自 GitHub 上提供的源代码。如需了解详情，或者为我们的文档做贡献，请参阅资源。