Thermal

摘要

枚举
AThermalStatus{
  ATHERMAL_STATUS_ERROR = -1,
  ATHERMAL_STATUS_NONE = 0,
  ATHERMAL_STATUS_LIGHT = 1,
  ATHERMAL_STATUS_MODERATE = 2,
  ATHERMAL_STATUS_SEVERE = 3,
  ATHERMAL_STATUS_CRITICAL = 4,
  ATHERMAL_STATUS_EMERGENCY = 5,
  ATHERMAL_STATUS_SHUTDOWN = 6
} 		enum
在函数 AThermal_getCurrentThermalStatus 和 AThermal_StatusCallback 中使用的热状态。

类型定义
AThermalHeadroomThreshold typedef
AThermalManager typedef
结构体 AThermalManager
表示热管理器句柄的不透明类型。
AThermalStatus typedef
AThermal_StatusCallback)(void *_Nullable data, AThermalStatus status) typedef
void(*
热状态变化时调用的函数原型。

函数
AThermal_acquireManager()
AThermalManager *_Nonnull
获取热管理器实例。
AThermal_getCurrentThermalStatus(AThermalManager *_Nonnull manager)
获取当前热状态。
AThermal_getThermalHeadroom(AThermalManager *_Nonnull manager, int forecastSeconds)
float
提供设备在达到严重节流之前当前有多少热余量的估算值。
AThermal_getThermalHeadroomThresholds(AThermalManager *_Nonnull manager, const AThermalHeadroomThreshold *_Nonnull *_Nullable outThresholds, size_t *_Nonnull size)
int
获取所有可用热状态的热余量阈值。
AThermal_registerThermalStatusListener(AThermalManager *_Nonnull manager, AThermal_StatusCallback _Nullable callback, void *_Nullable data)
int
注册热状态监听器以监听热状态变化。
AThermal_releaseManager(AThermalManager *_Nonnull manager)
void
释放通过 AThermal_acquireManager 获取的热管理器指针。
AThermal_unregisterThermalStatusListener(AThermalManager *_Nonnull manager, AThermal_StatusCallback _Nullable callback, void *_Nullable data)
int
注销之前注册的热状态监听器。

结构体
AThermalHeadroomThreshold

此结构体定义了余量阈值及其状态的实例。

枚举

AThermalStatus

声明于 android/thermal.h 
 AThermalStatus

在函数 AThermal_getCurrentThermalStatus 和 AThermal_StatusCallback 中使用的热状态。

属性
ATHERMAL_STATUS_CRITICAL

平台已采取一切措施降低功耗。
ATHERMAL_STATUS_EMERGENCY

平台中的关键组件因散热条件而关机。

设备功能将受到限制。
ATHERMAL_STATUS_ERROR

热状态出错。
ATHERMAL_STATUS_LIGHT

轻度节流，用户体验不受影响。
ATHERMAL_STATUS_MODERATE

中度节流，用户体验基本不受影响。
ATHERMAL_STATUS_NONE

未进行节流。
ATHERMAL_STATUS_SEVERE

严重节流，用户体验受到很大影响。
ATHERMAL_STATUS_SHUTDOWN

需要立即关机。

类型定义

AThermalHeadroomThreshold

声明于 android/thermal.h 
struct AThermalHeadroomThreshold AThermalHeadroomThreshold

AThermalManager

声明于 android/thermal.h 
struct AThermalManager AThermalManager

表示热管理器句柄的不透明类型。

在使用热状态 API 之前必须获取热管理器实例，并在使用后释放。

使用方法

AThermalStatus

声明于 android/thermal.h 
enum AThermalStatus AThermalStatus

AThermal_StatusCallback

声明于 android/thermal.h 
void(* AThermal_StatusCallback)(void *_Nullable data, AThermalStatus status)

热状态变化时调用的函数原型。

它会作为参数传入更新后的热状态，以及注册回调的客户端提供的指针。

函数

AThermal_acquireManager

声明于 android/thermal.h 
AThermalManager *_Nonnull AThermal_acquireManager()

获取热管理器实例。

必须使用 AThermal_releaseManager 释放此内容。

自 API 级别 30 起可用。

详情
返回值
成功时返回管理器实例，失败时返回 nullptr。

AThermal_getCurrentThermalStatus

声明于 android/thermal.h 
AThermalStatus AThermal_getCurrentThermalStatus(
  AThermalManager *_Nonnull manager
)

获取当前热状态。

自 API 级别 30 起可用。

详情
参数
manager
用于查询热状态的管理器实例。通过 AThermal_acquireManager 获取。
返回值
当前热状态；失败时返回 ATHERMAL_STATUS_ERROR。

AThermal_getThermalHeadroom

声明于 android/thermal.h 
float AThermal_getThermalHeadroom(
  AThermalManager *_Nonnull manager,
  int forecastSeconds
)

提供设备在达到严重节流之前当前有多少热余量的估算值。

请注意，此函数仅尝试跟踪慢速传感器的余量，例如皮肤温度传感器。这意味着每秒调用此函数的频率超过一次并没有益处，并且尝试以显著更高的频率调用可能会导致函数返回 NaN。

此外，为了能够提供准确的预测，系统直到拥有多个温度样本可用于推断时，才会尝试进行预测。从首次调用时起，这只需花费几秒钟，但在此期间不会进行预测，并且无论 forecastSeconds 的值如何，都会返回当前余量。

返回值是一个非负浮点数，表示热包络的使用量（或预测使用量）。值为 1.0 表示设备当前或将会在 ATHERMAL_STATUS_SEVERE 级别进行节流。这种节流会影响 CPU、GPU 和其他子系统。值可能超过 1.0，但超过该点没有隐含映射到特定的热量级别。这意味着大于 1.0 的值可能对应于 ATHERMAL_STATUS_SEVERE，但也可能表示更严重的节流。

值为 0.0 对应于距离 1.0 的固定距离，但不对应于任何特定的热状态或温度。位于 (0.0, 1.0] 之间的值预计会与温度线性变化，尽管温度随时间的变化通常不是线性的。负值在返回之前将被限制为 0.0。

自 API 级别 31 起可用。

详情
参数
manager
要使用的管理器实例。通过 AThermal_acquireManager 获取。
forecastSeconds
预测未来多少秒。鉴于设备条件可能随时变化，预测未来较远时间点的准确性可能会低于预测近期时间点。
返回值
大于等于 0.0 的值，其中 1.0 表示上述 SEVERE 节流阈值。如果设备不支持此功能或此函数调用频率远高于每秒一次，则返回 NaN。

AThermal_getThermalHeadroomThresholds

声明于 android/thermal.h 
int AThermal_getThermalHeadroomThresholds(
  AThermalManager *_Nonnull manager,
  const AThermalHeadroomThreshold *_Nonnull *_Nullable outThresholds,
  size_t *_Nonnull size
)

获取所有可用热状态的热余量阈值。

仅当设备制造商为其至少一个慢速皮肤温度传感器定义了相应的阈值时，输出中才会存在热状态。如果设置了该阈值，用户也应该能够从 AThermal_getCurrentThermalStatus 或 AThermal_StatusCallback 中获取它。

余量阈值用于根据余量预测解释可能的热节流状态。例如，如果 ATHERMAL_STATUS_LIGHT 的余量阈值为 0.7，并且 10 秒内的余量预测返回 0.75（即 AThermal_getThermalHeadroom(10)=0.75），则可以预期，如果工作负载保持不变，系统在 10 秒后可能会处于轻度节流状态。应用可以根据余量与阈值之差所对应的最接近的节流状态来考虑采取措施。

对于新设备，保证只有一个传感器；但对于具有多个传感器报告不同阈值的老设备，为了保守预测，会取最小阈值。因此，在读取实时余量时，不能保证超过上方 0.7 阈值的实时值 0.75（或 AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_LIGHT）总是会伴随轻度节流状态（或 AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_NONE），它可能更低（或 AThermal_getCurrentThermalStatus()=ATHERMAL_STATUS_NONE）。虽然始终保证设备的节流不会比未达到阈值所对应的状态更严重，因此实时余量为 0.75 绝不会对应 ATHERMAL_STATUS_MODERATE，而总是更低；实时余量为 0.65 绝不会对应 ATHERMAL_STATUS_LIGHT，而总是 ATHERMAL_STATUS_NONE。`

返回的阈值列表在首次成功查询时被缓存，并由热管理器拥有，在此函数调用之间不会改变。调用方只需使用 AThermal_releaseManager 释放管理器即可。

详情
参数
manager
要使用的管理器实例。通过 AThermal_acquireManager 获取。
outThresholds
指向 null AThermalHeadroomThreshold 指针的非 null 输出指针；如果系统或设备支持热阈值，该指针将被设置为缓存的阈值数组，否则为 nullptr 或保持不变。
size
非 null 输出指针，其值将被设置为阈值数组的大小，如果不支持则为 0。
返回值
成功时返回 0；如果 outThresholds 或 size_t 为 nullptr，或 *outThresholds 不为 nullptr，则返回 EINVAL。如果与系统服务通信失败，则返回 EPIPE。如果当前系统禁用此功能，则返回 ENOSYS。

AThermal_registerThermalStatusListener

声明于 android/thermal.h 
int AThermal_registerThermalStatusListener(
  AThermalManager *_Nonnull manager,
  AThermal_StatusCallback _Nullable callback,
  void *_Nullable data
)

注册热状态监听器以监听热状态变化。

自 API 级别 30 起可用。

详情
参数
manager
用于注册的管理器实例。通过 AThermal_acquireManager 获取。
callback
热状态更新时要调用的回调函数。
data
调用回调时要传递的数据指针。
返回值
成功时返回 0；如果监听器和数据指针之前已添加且未移除，则返回 EINVAL。如果未持有所需权限，则返回 EPERM。如果与系统服务通信失败，则返回 EPIPE。

AThermal_releaseManager

声明于 android/thermal.h 
void AThermal_releaseManager(
  AThermalManager *_Nonnull manager
)

释放通过 AThermal_acquireManager 获取的热管理器指针。

自 API 级别 30 起可用。

详情
参数
manager
要释放的管理器。

AThermal_unregisterThermalStatusListener

声明于 android/thermal.h 
int AThermal_unregisterThermalStatusListener(
  AThermalManager *_Nonnull manager,
  AThermal_StatusCallback _Nullable callback,
  void *_Nullable data
)

注销之前注册的热状态监听器。

自 API 级别 30 起可用。

详情
参数
manager
用于注销的管理器实例。通过 AThermal_acquireManager 获取。
callback
热状态更新时要调用的回调函数。
data
调用回调时要传递的数据指针。
返回值
成功时返回 0；如果监听器和数据指针之前未添加，则返回 EINVAL。如果未持有所需权限，则返回 EPERM。如果与系统服务通信失败，则返回 EPIPE。