網格診斷

本單元包含網狀診斷的定義和函式。

摘要

網狀診斷 API 需要 OPENTHREAD_CONFIG_MESH_DIAG_ENABLE 和 OPENTHREAD_FTD。

Typedefs
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() 中的路由器相鄰項目相關資訊。

Typedefs

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_RESPONSE_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_RESPONSE_TIMEOUT 等待一或多個路由器回應逾時。
[in] aRouterInfo
找到的路由器資訊 (如果 aError 為 OT_ERROR_RESPONSE_TIMEOUT，則可為空值)。
[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_RESPONSE_TIMEOUT 等候回應已逾時。
[in] aChildEntry
子項項目 (如果 aError 為 OT_ERROR_RESPONSE_TIMEOUT 或 OT_ERROR_NONE 則可為空值)。
[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_RESPONSE_TIMEOUT 等候回應已逾時。
[in] aNeighborEntry
相鄰項目 (如果 aError 為 Reply_TIMEOUT 或 NONE，則可為空值)。
[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

指定 Thread Version 不明。

如果裝置未提供版本，otMeshDiagRouterInfo 會在 mVersion 屬性中使用。這表示裝置可能搭載 1.3.0 (版本值 4) 以下版本。

資源

OpenThread API 參考資料主題源自原始碼，請前往 GitHub 取得。如要瞭解詳情或對說明文件做出貢獻，請參閱資源。