网格诊断

本模块包含网格诊断的定义和功能。

摘要

Mesh Diagnostics API 需要 OPENTHREAD_CONFIG_MESH_DIAG_ENABLE 和 OPENTHREAD_FTD。

类型定义符
otMeshDiagChildEntry typedef
表示来自 otMeshDiagQueryChildTable() 的子条目的信息。
otMeshDiagChildInfo typedef
表示使用 otMeshDiagDiscoverTopology() 在 Thread 网格中发现的子级的相关信息。
otMeshDiagChildIp6AddrsCallback)(otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext) typedef
void(*
表示 otMeshDiagQueryChildrenIp6Addrs() 用于提供 MTD 子级及其 IPv6 地址列表相关信息的回调函数。
otMeshDiagChildIterator typedef
一个不透明迭代器，用于遍历路由器的子项列表。
otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext) typedef
void(*
指针类型表示 otMeshDiagDiscoverTopology() 用来提供有关已发现路由器的信息的回调。
otMeshDiagDiscoverConfig typedef
表示在发现网格拓扑时使用的配置集，指示要发现的项。
otMeshDiagIp6AddrIterator typedef
一个不透明的迭代器，用于遍历路由器的 IPv6 地址列表。
otMeshDiagQueryChildTableCallback)(otError aError, const otMeshDiagChildEntry *aChildEntry, void *aContext) typedef
void(*
表示 otMeshDiagQueryChildTable() 用于提供有关子表条目信息的回调。
otMeshDiagQueryRouterNeighborTableCallback)(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext) typedef
void(*
表示 otMeshDiagQueryRouterNeighborTable() 用于提供有关相邻路由器表条目的信息的回调。
otMeshDiagRouterInfo typedef
表示使用 otMeshDiagDiscoverTopology() 发现的 Thread 网格中的路由器的相关信息。
otMeshDiagRouterNeighborEntry typedef
表示来自 otMeshDiagQueryRouterNeighborTable() 的路由器相邻条目的信息。

函数
otMeshDiagCancel(otInstance *aInstance)
void
取消正在进行的拓扑发现（如果有），否则不执行任何操作。
otMeshDiagDiscoverTopology(otInstance *aInstance, const otMeshDiagDiscoverConfig *aConfig, otMeshDiagDiscoverCallback aCallback, void *aContext)
启动网络拓扑发现。
otMeshDiagGetNextChildInfo(otMeshDiagChildIterator *aIterator, otMeshDiagChildInfo *aChildInfo)
遍历发现的路由器子项。
otMeshDiagGetNextIp6Address(otMeshDiagIp6AddrIterator *aIterator, otIp6Address *aIp6Address)
遍历发现的路由器或 MTD 子级的 IPv6 地址。
otMeshDiagQueryChildTable(otInstance *aInstance, uint16_t aRloc16, otMeshDiagQueryChildTableCallback aCallback, void *aContext)
开始查询给定路由器的子表。
otMeshDiagQueryChildrenIp6Addrs(otInstance *aInstance, uint16_t aRloc16, otMeshDiagChildIp6AddrsCallback aCallback, void *aContext)
向父级发送查询，以检索其所有 MTD 子级的 IPv6 地址。
otMeshDiagQueryRouterNeighborTable(otInstance *aInstance, uint16_t aRloc16, otMeshDiagQueryRouterNeighborTableCallback aCallback, void *aContext)
开始查询给定路由器的路由器相邻表。

结构体
otMeshDiagChildEntry

表示来自 otMeshDiagQueryChildTable() 的子条目的信息。
otMeshDiagChildInfo

表示使用 otMeshDiagDiscoverTopology() 在 Thread 网格中发现的子级的相关信息。
otMeshDiagDiscoverConfig

表示在发现网格拓扑时使用的配置集，指示要发现的项。
otMeshDiagRouterInfo

表示使用 otMeshDiagDiscoverTopology() 发现的 Thread 网格中的路由器的相关信息。
otMeshDiagRouterNeighborEntry

表示来自 otMeshDiagQueryRouterNeighborTable() 的路由器相邻条目的信息。

类型定义符

otMeshDiagChildEntry

struct otMeshDiagChildEntry otMeshDiagChildEntry

表示来自 otMeshDiagQueryChildTable() 的子条目的信息。

mSupportsErrRate 指明是否支持错误跟踪功能，以及 mFrameErrorRate 和 mMessageErrorRate 值是否有效。帧错误率跟踪 MAC 层的帧 tx 错误（向子节点发送），而 mMessageErrorRate 跟踪 IPv6 消息丢失时的 IPv6 消息错误率（在 MAC 层之上和 MAC 重试后）。例如，如果邮件很大并且需要 6LoWPAN 碎片化处理，则当邮件 tx 的某个片段帧 tx 失败（例如从未确认）时，系统会将其视为失败。

otMeshDiagChildInfo

struct otMeshDiagChildInfo otMeshDiagChildInfo

表示使用 otMeshDiagDiscoverTopology() 在 Thread 网格中发现的子级的相关信息。

otMeshDiagChildIp6AddrsCallback

void(* otMeshDiagChildIp6AddrsCallback)(otError aError, uint16_t aChildRloc16, otMeshDiagIp6AddrIterator *aIp6AddrIterator, void *aContext)

表示 otMeshDiagQueryChildrenIp6Addrs() 用于提供 MTD 子级及其 IPv6 地址列表相关信息的回调函数。

当 aError 为 OT_ERROR_PENDING 时，表示还有更多子元素，并且将再次调用该回调函数。

具体说明
参数
[in] aError
OT_ERROR_PENDING 表示表中有更多子项。OT_ERROR_NONE 表示表已完成。OT_ERROR_PARENT_TIMEOUT 等待响应时超时。
[in] aChildRloc16
子项的 RLOC16。在 OT_ERROR_RESPONSE_TIMEOUT 上使用 0xfffe。
[in] aIp6AddrIterator
使用 otMeshDiagGetNextIp6Address() 遍历 aRloc 子级的 IPv6 地址的迭代器。在 OT_ERROR_RESPONSE_TIMEOUT 上设置为 NULL。
[in] aContext
特定于应用的上下文。

otMeshDiagChildIterator

struct otMeshDiagChildIterator otMeshDiagChildIterator

一个不透明迭代器，用于遍历路由器的子项列表。

otMeshDiagRouterInfo 中提供了指向此类型的实例的指针。

otMeshDiagDiscoverCallback

void(* otMeshDiagDiscoverCallback)(otError aError, otMeshDiagRouterInfo *aRouterInfo, void *aContext)

指针类型表示 otMeshDiagDiscoverTopology() 用来提供有关已发现路由器的信息的回调。

当 aError 为 OT_ERROR_PENDING 时，表示发现尚未完成，需要发现更多路由器，并且将再次调用回调。

具体说明
参数
[in] aError
OT_ERROR_PENDING 表示还有更多路由器待发现。OT_ERROR_NONE 表示这是最后一个完成的路由器和网状网发现操作。OT_ERROR_PARENT_TIMEOUT 等待一个或多个路由器的响应超时。
[in] aRouterInfo
已发现的路由器信息（如果 aError 为 OT_ERROR_response_TIMEOUT，则可以为 null）。
[in] aContext
特定于应用的上下文。

otMeshDiagDiscoverConfig

struct otMeshDiagDiscoverConfig otMeshDiagDiscoverConfig

表示在发现网格拓扑时使用的配置集，指示要发现的项。

otMeshDiagIp6AddrIterator

struct otMeshDiagIp6AddrIterator otMeshDiagIp6AddrIterator

一个不透明的迭代器，用于遍历路由器的 IPv6 地址列表。

otMeshDiagRouterInfo 中提供了指向此类型的实例的指针。

otMeshDiagQueryChildTableCallback

void(* otMeshDiagQueryChildTableCallback)(otError aError, const otMeshDiagChildEntry *aChildEntry, void *aContext)

表示 otMeshDiagQueryChildTable() 用于提供有关子表条目信息的回调。

当 aError 为 OT_ERROR_PENDING 时，表示表中仍有更多条目，并且系统会再次调用该回调函数。

具体说明
参数
[in] aError
OT_ERROR_PENDING 表示表中有更多条目。OT_ERROR_NONE 表示表已完成。OT_ERROR_PARENT_TIMEOUT 等待响应时超时。
[in] aChildEntry
子条目（如果 aError 为 OT_ERROR_response_TIMEOUT 或 OT_ERROR_NONE，则为 null）。
[in] aContext
特定于应用的上下文。

otMeshDiagQueryRouterNeighborTableCallback

void(* otMeshDiagQueryRouterNeighborTableCallback)(otError aError, const otMeshDiagRouterNeighborEntry *aNeighborEntry, void *aContext)

表示 otMeshDiagQueryRouterNeighborTable() 用于提供有关相邻路由器表条目的信息的回调。

当 aError 为 OT_ERROR_PENDING 时，表示表中仍有更多条目，并且系统会再次调用该回调函数。

具体说明
参数
[in] aError
OT_ERROR_PENDING 表示表中有更多条目。OT_ERROR_NONE 表示表已完成。OT_ERROR_PARENT_TIMEOUT 等待响应时超时。
[in] aNeighborEntry
相邻条目（如果 aError 为 Playback_TIMEOUT 或 NONE，则可以为 null）。
[in] aContext
特定于应用的上下文。

otMeshDiagRouterInfo

struct otMeshDiagRouterInfo otMeshDiagRouterInfo

表示使用 otMeshDiagDiscoverTopology() 发现的 Thread 网格中的路由器的相关信息。

otMeshDiagRouterNeighborEntry

struct otMeshDiagRouterNeighborEntry otMeshDiagRouterNeighborEntry

表示来自 otMeshDiagQueryRouterNeighborTable() 的路由器相邻条目的信息。

mSupportsErrRate 指明是否支持错误跟踪功能，以及 mFrameErrorRate 和 mMessageErrorRate 值是否有效。帧错误率跟踪 MAC 层的帧 tx 错误（向子节点发送），而 mMessageErrorRate 跟踪 IPv6 消息丢失时的 IPv6 消息错误率（在 MAC 层之上和 MAC 重试后）。例如，如果邮件很大并且需要 6LoWPAN 碎片化处理，则当邮件 tx 的某个片段帧 tx 失败（例如从未确认）时，系统会将其视为失败。

函数

otMeshDiagCancel

void otMeshDiagCancel(
  otInstance *aInstance
)

取消正在进行的拓扑发现（如果有），否则不执行任何操作。

取消持续发现后，将不再调用来自 otMeshDiagDiscoverTopology() 的回调。

otMeshDiagDiscoverTopology

otError otMeshDiagDiscoverTopology(
  otInstance *aInstance,
  const otMeshDiagDiscoverConfig *aConfig,
  otMeshDiagDiscoverCallback aCallback,
  void *aContext
)

启动网络拓扑发现。

具体说明
参数
[in] aInstance
OpenThread 实例。
[in] aConfig
用于发现的配置（例如要发现哪些商品）。
[in] aCallback
用于报告已发现路由器的回调。
[in] aContext
要在 aCallback 中传递的上下文。
返回值
OT_ERROR_NONE
已成功启动网络拓扑发现。
OT_ERROR_BUSY
之前的发现请求仍在处理中。
OT_ERROR_INVALID_STATE
设备未连接。
OT_ERROR_NO_BUFS
无法分配缓冲区来发送发现消息。

otMeshDiagGetNextChildInfo

otError otMeshDiagGetNextChildInfo(
  otMeshDiagChildIterator *aIterator,
  otMeshDiagChildInfo *aChildInfo
)

遍历发现的路由器子项。

必须通过回调 otMeshDiagDiscoverCallback() 使用该函数，并使用 aRouterInfo 结构体中的 mChildIterator（作为该回调的输入）。

具体说明
参数
[in,out] aIterator
要使用的地址迭代器。
[out] aChildInfo
用于返回子项信息（如有）的指针。
返回值
OT_ERROR_NONE
已成功检索到下一个子级。更新了 aChildInfo 和 aIterator。
OT_ERROR_NOT_FOUND
没有孩子了。已到达列表末尾。

otMeshDiagGetNextIp6Address

otError otMeshDiagGetNextIp6Address(
  otMeshDiagIp6AddrIterator *aIterator,
  otIp6Address *aIp6Address
)

遍历发现的路由器或 MTD 子级的 IPv6 地址。

必须使用

具体说明
参数
[in,out] aIterator
要使用的地址迭代器。
[out] aIp6Address
用于返回下一个 IPv6 地址（如果有）的指针。
返回值
OT_ERROR_NONE
已成功检索到下一个地址。更新了 aIp6Address 和 aIterator。
OT_ERROR_NOT_FOUND
没有其他地址了。已到达列表末尾。

otMeshDiagQueryChildTable

otError otMeshDiagQueryChildTable(
  otInstance *aInstance,
  uint16_t aRloc16,
  otMeshDiagQueryChildTableCallback aCallback,
  void *aContext
)

开始查询给定路由器的子表。

具体说明
参数
[in] aInstance
OpenThread 实例。
[in] aRloc16
要查询的路由器的 RLOC16。
[in] aCallback
用于报告查询的子表的回调函数。
[in] aContext
要在 aCallback 中传递的上下文。
返回值
OT_ERROR_NONE
已成功开始查询。
OT_ERROR_BUSY
之前的发现或查询请求仍在进行中。
OT_ERROR_INVALID_ARGS
aRloc16 不是有效的路由器 RLOC16。
OT_ERROR_INVALID_STATE
设备未连接。
OT_ERROR_NO_BUFS
无法分配缓冲区来发送查询消息。

otMeshDiagQueryChildrenIp6Addrs

otError otMeshDiagQueryChildrenIp6Addrs(
  otInstance *aInstance,
  uint16_t aRloc16,
  otMeshDiagChildIp6AddrsCallback aCallback,
  void *aContext
)

向父级发送查询，以检索其所有 MTD 子级的 IPv6 地址。

具体说明
参数
[in] aInstance
OpenThread 实例。
[in] aRloc16
要查询的父级的 RLOC16。
[in] aCallback
用于报告查询的子 IPv6 地址列表的回调函数。
[in] aContext
要在 aCallback 中传递的上下文。
返回值
OT_ERROR_NONE
已成功开始查询。
OT_ERROR_BUSY
之前的发现或查询请求仍在进行中。
OT_ERROR_INVALID_ARGS
aRloc16 不是有效的 RLOC16。
OT_ERROR_INVALID_STATE
设备未连接。
OT_ERROR_NO_BUFS
无法分配缓冲区来发送查询消息。

otMeshDiagQueryRouterNeighborTable

otError otMeshDiagQueryRouterNeighborTable(
  otInstance *aInstance,
  uint16_t aRloc16,
  otMeshDiagQueryRouterNeighborTableCallback aCallback,
  void *aContext
)

开始查询给定路由器的路由器相邻表。

具体说明
参数
[in] aInstance
OpenThread 实例。
[in] aRloc16
要查询的路由器的 RLOC16。
[in] aCallback
用于报告所查询表的回调函数。
[in] aContext
要在 aCallback 中传递的上下文。
返回值
OT_ERROR_NONE
已成功开始查询。
OT_ERROR_BUSY
之前的发现或查询请求仍在进行中。
OT_ERROR_INVALID_ARGS
aRloc16 不是有效的路由器 RLOC16。
OT_ERROR_INVALID_STATE
设备未连接。
OT_ERROR_NO_BUFS
无法分配缓冲区来发送查询消息。

宏

OT_MESH_DIAG_VERSION_UNKNOWN

 OT_MESH_DIAG_VERSION_UNKNOWN 0xffff

指定线程版本未知。

如果设备未提供其版本，则会在 otMeshDiagRouterInfo 中用于 mVersion 属性。这表示设备可能运行的是 1.3.0（版本值 4）或更低版本。

资源

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