執行個體

這個模組內含控管 OpenThread 執行個體的函式。

摘要

Typedefs
otChangedFlags typedef
uint32_t
代表位元欄位，指出已變更的特定狀態/設定。
otInstance typedef
struct otInstance
代表 OpenThread 執行個體結構。
otStateChangedCallback)(otChangedFlags aFlags, void *aContext) typedef
void(*
系統會呼叫指標，通知 OpenThread 內的特定設定或狀態變更。

函式
otGetRadioVersionString(otInstance *aInstance)
const char *
取得 OpenThread 無線電版本字串。
otGetVersionString(void)
const char *
取得 OpenThread 版本字串。
otInstanceErasePersistentInfo(otInstance *aInstance)
清除儲存在非揮發記憶體中的所有 OpenThread 永久資訊 (網路設定)。
otInstanceFactoryReset(otInstance *aInstance)
void
刪除儲存在非揮發記憶體中的所有設定，然後觸發平台重設程序。
otInstanceFinalize(otInstance *aInstance)
void
停用 OpenThread 程式庫。
otInstanceGetId(otInstance *aInstance)
uint32_t
取得執行個體 ID。
otInstanceGetUptime(otInstance *aInstance)
uint64_t
傳回目前執行個體的運作時間 (以毫秒為單位)。
otInstanceGetUptimeAsString(otInstance *aInstance, char *aBuffer, uint16_t aSize)
void
以使用者可理解的字串傳回目前執行個體的運作時間。
otInstanceInit(void *aInstanceBuffer, size_t *aInstanceBufferSize)
初始化 OpenThread 程式庫。
otInstanceInitMultiple(uint8_t aIdx)
初始化 OpenThread 執行個體。
otInstanceInitSingle(void)
初始化 OpenThread 程式庫的靜態單一執行個體。
otInstanceIsInitialized(otInstance *aInstance)
bool
表示執行個體是否有效/已初始化。
otInstanceReset(otInstance *aInstance)
void
觸發平台重設程序。
otInstanceResetRadioStack(otInstance *aInstance)
void
重設 OpenThread 無線電堆疊的內部狀態。
otInstanceResetToBootloader(otInstance *aInstance)
觸發平台重設為系統啟動載入程式模式 (如支援)。
otRemoveStateChangeCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext)
void
移除回呼，指出 OpenThread 內特定設定或狀態變更的時間。
otSetStateChangedCallback(otInstance *aInstance, otStateChangedCallback aCallback, void *aContext)
註冊回呼，指出 OpenThread 內的特定設定或狀態變更的時間。

Typedefs

otChangedFlags

uint32_t otChangedFlags

代表位元欄位，指出已變更的特定狀態/設定。

查看「OT_CHANGED_*」定義。

otInstance

struct otInstance otInstance

代表 OpenThread 執行個體結構。

otStateChangedCallback

void(* otStateChangedCallback)(otChangedFlags aFlags, void *aContext)

系統會呼叫指標，通知 OpenThread 內的特定設定或狀態變更。

詳細說明
參數
[in] aFlags
這個位元欄位代表已變更的特定狀態。查看「OT_CHANGED_*」定義。
[in] aContext
指向應用程式特定背景資訊的指標。

函式

otGetRadioVersionString

const char * otGetRadioVersionString(
  otInstance *aInstance
)

取得 OpenThread 無線電版本字串。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回
指向 OpenThread 無線電版本的指標。

otGetVersionString

const char * otGetVersionString(
  void
)

取得 OpenThread 版本字串。

詳細說明
傳回
指向 OpenThread 版本的指標。

otInstanceErasePersistentInfo

otError otInstanceErasePersistentInfo(
  otInstance *aInstance
)

清除儲存在非揮發記憶體中的所有 OpenThread 永久資訊 (網路設定)。

裝置必須處於 disabled 狀態/角色，才能清除資料。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回值
OT_ERROR_NONE
已成功清除所有永久資訊/狀態。
OT_ERROR_INVALID_STATE
裝置狀態並非disabled。

otInstanceFactoryReset

void otInstanceFactoryReset(
  otInstance *aInstance
)

刪除儲存在非揮發記憶體中的所有設定，然後觸發平台重設程序。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。

otInstanceFinalize

void otInstanceFinalize(
  otInstance *aInstance
)

停用 OpenThread 程式庫。

當 OpenThread 不再使用時，呼叫此函式。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。

otInstanceGetId

uint32_t otInstanceGetId(
  otInstance *aInstance
)

取得執行個體 ID。

建構執行個體時，執行個體 ID 會設為隨機值，且其值在初始化後不會變更。

詳細說明
傳回
執行個體 ID。

otInstanceGetUptime

uint64_t otInstanceGetUptime(
  otInstance *aInstance
)

傳回目前執行個體的運作時間 (以毫秒為單位)。

必須啟用 OPENTHREAD_CONFIG_UPTIME_ENABLE。

自 OpenThread 執行個體初始化以來，運作時間 (以毫秒為單位)。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回
運作時間 (毫秒)。

otInstanceGetUptimeAsString

void otInstanceGetUptimeAsString(
  otInstance *aInstance,
  char *aBuffer,
  uint16_t aSize
)

以使用者可理解的字串傳回目前執行個體的運作時間。

必須啟用 OPENTHREAD_CONFIG_UPTIME_ENABLE。

字串採用「::.」格式，代表時、分、秒和毫秒 (如果運作時間短於一天) 或「」

d.::。"(如果超過一天)。

如果產生的字串不符合 aBuffer (在其 aSize 字元之內) 的大小，系統將截斷字串，但輸出的字串一律會是空值。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[out] aBuffer
指向字元陣列的指標，用來輸出字串。
[in] aSize
aBuffer 的大小 (以位元組為單位)。建議使用 OT_UPTIME_STRING_SIZE。

otInstanceInit

otInstance * otInstanceInit(
  void *aInstanceBuffer,
  size_t *aInstanceBufferSize
)

初始化 OpenThread 程式庫。

初始化 OpenThread，並準備其以供後續的 OpenThread API 呼叫使用。必須先呼叫此函式，才能呼叫 OpenThread。

提供，而且只能在啟用多個 OpenThread 執行個體時使用。

詳細說明
參數
[in] aInstanceBuffer
OpenThread 用於分配 otInstance 結構的緩衝區。
[in,out] aInstanceBufferSize
在輸入時，aInstanceBuffer 的大小。如果輸出時 otInstance 的空間不足，則為 otInstance 所需的位元組數。
傳回
指向新 OpenThread 執行個體的指標。
另請參閱：
otInstanceFinalize

otInstanceInitMultiple

otInstance * otInstanceInitMultiple(
  uint8_t aIdx
)

初始化 OpenThread 執行個體。

此函式會初始化 OpenThread，並為後續的 OpenThread API 呼叫做好準備。必須先呼叫此函式，才能呼叫 OpenThread。這個方法會使用靜態緩衝區初始化 OpenThread 執行個體。

此函式可供使用，僅適用於啟用多個 OpenThread 靜態執行個體時才能使用 (OPENTHREAD_CONFIG_MULTIPLE_STATIC_INSTANCE_ENABLE)

詳細說明
參數
[in] aIdx
要初始化的 OpenThread 執行個體索引。
傳回
指向新 OpenThread 執行個體的指標。

otInstanceInitSingle

otInstance * otInstanceInitSingle(
  void
)

初始化 OpenThread 程式庫的靜態單一執行個體。

初始化 OpenThread，並準備其以供後續的 OpenThread API 呼叫使用。必須先呼叫此函式，才能呼叫 OpenThread。

提供，只能在停用多個 OpenThread 執行個體的支援時使用。

詳細說明
傳回
單一 OpenThread 執行個體的指標。

otInstanceIsInitialized

bool otInstanceIsInitialized(
  otInstance *aInstance
)

表示執行個體是否有效/已初始化。

如果執行個體是使用 otInstanceInitSingle() (單一例項) 或 otInstanceInit() (多執行個體情況) 取得並初始化，系統會將該執行個體視為有效。對 otInstanceFinalize() 的後續呼叫會導致系統將執行個體視為尚未初始化。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回
如果指定的執行個體有效/已初始化，則為 TRUE，否則傳回 FALSE。

otInstanceReset

void otInstanceReset(
  otInstance *aInstance
)

觸發平台重設程序。

重設程序可確保所有 OpenThread 狀態/資訊 (儲存在揮發性記憶體中) 皆已清除。請注意，otPlatformReset 不會清除非揮發性記憶體中儲存的任何持續狀態/資訊。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。

otInstanceResetRadioStack

void otInstanceResetRadioStack(
  otInstance *aInstance
)

重設 OpenThread 無線電堆疊的內部狀態。

系統會保留回呼和設定。

這個 API 僅適用於無線電版本 (OPENTHREAD_RADIO = 1)。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。

otInstanceResetToBootloader

otError otInstanceResetToBootloader(
  otInstance *aInstance
)

觸發平台重設為系統啟動載入程式模式 (如支援)。

需要 OPENTHREAD_CONFIG_PLATFORM_BOOTLOADER_MODE_ENABLE。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
傳回值
OT_ERROR_NONE
已成功重設為系統啟動載入程式。
OT_ERROR_BUSY
正在執行另一項作業，因此無法執行這項作業。
OT_ERROR_NOT_CAPABLE
無法重設為系統啟動載入程式。

otRemoveStateChangeCallback

void otRemoveStateChangeCallback(
  otInstance *aInstance,
  otStateChangedCallback aCallback,
  void *aContext
)

移除回呼，指出 OpenThread 內特定設定或狀態變更的時間。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aCallback
指向特定設定或狀態變更所呼叫函式的指標。
[in] aContext
指向應用程式特定背景資訊的指標。

otSetStateChangedCallback

otError otSetStateChangedCallback(
  otInstance *aInstance,
  otStateChangedCallback aCallback,
  void *aContext
)

註冊回呼，指出 OpenThread 內的特定設定或狀態變更的時間。

詳細說明
參數
[in] aInstance
指向 OpenThread 執行個體的指標。
[in] aCallback
指向特定設定或狀態變更所呼叫函式的指標。
[in] aContext
指向應用程式特定背景資訊的指標。
傳回值
OT_ERROR_NONE
已將回呼新增至回呼清單。
OT_ERROR_ALREADY
先前已註冊過回呼。
OT_ERROR_NO_BUFS
因資源限製而無法新增回呼。

巨集

OT_CHANGED_ACTIVE_DATASET

 OT_CHANGED_ACTIVE_DATASET (1U << 28)

有效作業資料集已變更。

OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL

 OT_CHANGED_CHANNEL_MANAGER_NEW_CHANNEL (1U << 21)

頻道管理員新增的待處理討論串頻道已變更。

OT_CHANGED_COMMISSIONER_STATE

 OT_CHANGED_COMMISSIONER_STATE (1U << 23)

調試者狀態已變更。

OT_CHANGED_IP6_ADDRESS_ADDED

 OT_CHANGED_IP6_ADDRESS_ADDED (1U << 0)

已新增 IPv6 位址。

OT_CHANGED_IP6_ADDRESS_REMOVED

 OT_CHANGED_IP6_ADDRESS_REMOVED (1U << 1)

已移除 IPv6 位址。

OT_CHANGED_IP6_MULTICAST_SUBSCRIBED

 OT_CHANGED_IP6_MULTICAST_SUBSCRIBED (1U << 12)

已訂閱 IPv6 多點傳播位址。

OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED

 OT_CHANGED_IP6_MULTICAST_UNSUBSCRIBED (1U << 13)

已取消訂閱 IPv6 多點傳送位址。

OT_CHANGED_JOINER_STATE

 OT_CHANGED_JOINER_STATE (1U << 27)

彙整者狀態已變更。

OT_CHANGED_NAT64_TRANSLATOR_STATE

 OT_CHANGED_NAT64_TRANSLATOR_STATE (1U << 30)

NAT64 譯者的狀態已變更。

OT_CHANGED_NETWORK_KEY

 OT_CHANGED_NETWORK_KEY (1U << 18)

網路金鑰已變更。

 OT_CHANGED_PARENT_LINK_QUALITY (1U << 31)

上層連結品質已變更。

OT_CHANGED_PENDING_DATASET

 OT_CHANGED_PENDING_DATASET (1U << 29)

已變更待處理作業的資料集。

OT_CHANGED_PSKC

 OT_CHANGED_PSKC (1U << 19)

PSKc 已變更。

OT_CHANGED_SECURITY_POLICY

 OT_CHANGED_SECURITY_POLICY (1U << 20)

安全性政策已變更。

OT_CHANGED_SUPPORTED_CHANNEL_MASK

 OT_CHANGED_SUPPORTED_CHANNEL_MASK (1U << 22)

支援的頻道遮罩已變更。

OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL

 OT_CHANGED_THREAD_BACKBONE_ROUTER_LOCAL (1U << 26)

已變更本機骨幹路由器設定。

OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE

 OT_CHANGED_THREAD_BACKBONE_ROUTER_STATE (1U << 25)

骨幹路由器狀態已變更。

OT_CHANGED_THREAD_CHANNEL

 OT_CHANGED_THREAD_CHANNEL (1U << 14)

Thread 網路頻道已變更。

OT_CHANGED_THREAD_CHILD_ADDED

 OT_CHANGED_THREAD_CHILD_ADDED (1U << 10)

已新增孩童。

OT_CHANGED_THREAD_CHILD_REMOVED

 OT_CHANGED_THREAD_CHILD_REMOVED (1U << 11)

已移除孩童。

OT_CHANGED_THREAD_EXT_PANID

 OT_CHANGED_THREAD_EXT_PANID (1U << 17)

執行緒網路擴充 PAN ID 已變更。

OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER

 OT_CHANGED_THREAD_KEY_SEQUENCE_COUNTER (1U << 8)

執行緒索引鍵順序已變更。

OT_CHANGED_THREAD_LL_ADDR

 OT_CHANGED_THREAD_LL_ADDR (1U << 3)

連結-本機位址已變更。

OT_CHANGED_THREAD_ML_ADDR

 OT_CHANGED_THREAD_ML_ADDR (1U << 4)

網格本機位址已變更。

OT_CHANGED_THREAD_NETDATA

 OT_CHANGED_THREAD_NETDATA (1U << 9)

執行緒網路資料已變更。

OT_CHANGED_THREAD_NETIF_STATE

 OT_CHANGED_THREAD_NETIF_STATE (1U << 24)

執行緒網路介面狀態已變更。

OT_CHANGED_THREAD_NETWORK_NAME

 OT_CHANGED_THREAD_NETWORK_NAME (1U << 16)

執行緒網路名稱已變更。

OT_CHANGED_THREAD_PANID

 OT_CHANGED_THREAD_PANID (1U << 15)

執行緒網路永久帳號 ID 已變更。

OT_CHANGED_THREAD_PARTITION_ID

 OT_CHANGED_THREAD_PARTITION_ID (1U << 7)

分區 ID 已變更。

OT_CHANGED_THREAD_RLOC_ADDED

 OT_CHANGED_THREAD_RLOC_ADDED (1U << 5)

已新增 RLOC。

OT_CHANGED_THREAD_RLOC_REMOVED

 OT_CHANGED_THREAD_RLOC_REMOVED (1U << 6)

已移除 RLOC。

OT_CHANGED_THREAD_ROLE

 OT_CHANGED_THREAD_ROLE (1U << 2)

角色 (已停用、卸離、子項、路由器、領導者) 已變更。

OT_UPTIME_STRING_SIZE

 OT_UPTIME_STRING_SIZE 24

表示運作時間字串的建議大小。

資源

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