实例

此模块包含用于控制 OpenThread 实例的函数。

摘要

类型定义符
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
获取实例标识符。
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 中特定配置或状态何时发生更改。

类型定义符

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
)

获取实例标识符。

构建该实例时，该实例标识符会设置为一个随机值，初始化后其值不会更改。

具体说明
返回值
实例标识符。

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.::." （如果超过 1 天）。

如果生成的字符串不适合 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 仅在电台 build (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)

更改了 Thread 网络扩展 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)

Thread 网络 PAN 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 上提供的源代码。如需了解详情，或者为我们的文档做贡献，请参阅资源。