本頁面由 Cloud Translation API 翻譯而成。

執行個體

這個模組內含控管 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)`	`otError` 清除儲存在非揮發記憶體中的所有 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)`	`otInstance *` 初始化 OpenThread 程式庫。
`otInstanceInitMultiple(uint8_t aIdx)`	`otInstance *` 初始化 OpenThread 執行個體。
`otInstanceInitSingle(void)`	`otInstance *` 初始化 OpenThread 程式庫的靜態單一執行個體。
`otInstanceIsInitialized(otInstance *aInstance)`	`bool` 表示執行個體是否有效/已初始化。
`otInstanceReset(otInstance *aInstance)`	`void` 觸發平台重設程序。
`otInstanceResetRadioStack(otInstance *aInstance)`	`void` 重設 OpenThread 無線電堆疊的內部狀態。
`otInstanceResetToBootloader(otInstance *aInstance)`	`otError` 觸發平台重設為系統啟動載入程式模式 (如支援)。
`otRemoveStateChangeCallback(otInstance aInstance, otStateChangedCallback aCallback, void aContext)`	`void` 移除回呼，指出 OpenThread 內特定設定或狀態變更的時間。
`otSetStateChangedCallback(otInstance aInstance, otStateChangedCallback aCallback, void aContext)`	`otError` 註冊回呼，指出 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

 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 取得。如要瞭解詳情或對說明文件做出貢獻，請參閱資源。