OnThermalHeadroomChangedListener

onThermalHeadroomChanged

abstract fun onThermalHeadroomChanged(
    headroom: Float, 
    forecastHeadroom: Float, 
    forecastSeconds: Int, 
    thresholds: MutableMap<Int!, Float!>
): Unit

Called when overall thermal headroom or headroom thresholds have significantly changed that requires action.

This may not be used to fully replace the getThermalHeadroom(int) API as it will only notify on one of the conditions below that will significantly change one or both values of current headroom and headroom thresholds since previous callback: 1. thermal throttling events: when the skin temperature has cross any of the thresholds and there isn't a previous callback in a short time ago with similar values. 2. skin temperature threshold change events: note that if the absolute °C threshold values change in a way that does not significantly change the current headroom nor headroom thresholds, it will not trigger any callback. The client should not need to take action in such case since the difference from temperature vs threshold hasn't changed.

By API version 36, it provides a forecast in the same call for developer's convenience based on a forecastSeconds defined by the device, which can be static or dynamic varied by OEM. Be aware that it will not notify on forecast temperature change but the events mentioned above. So periodically polling against getThermalHeadroom(int) API should still be used to actively monitor temperature forecast in advance.

This serves as a more advanced option compared to thermal status listener, where the latter will only notify on thermal throttling events with status update.