• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.thermal (Thermal Management)
2
3<!--Kit: Basic Services Kit-->
4<!--Subsystem: PowerManager-->
5<!--Owner: @zhang-yinglie; @volcano_wang-->
6<!--Designer: @wangyantian0-->
7<!--Tester: @alien0208-->
8<!--Adviser: @w_Machine_cc-->
9
10The **thermal** module provides thermal level-related callback and query APIs to obtain the information required for thermal control.
11
12> **NOTE**
13>
14> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
15
16## Modules to Import
17
18```js
19import {thermal} from '@kit.BasicServicesKit';
20```
21
22## thermal.registerThermalLevelCallback<sup>9+</sup>
23
24registerThermalLevelCallback(callback: Callback&lt;ThermalLevel&gt;): void
25
26Subscribes to thermal level changes.
27
28**System capability**: SystemCapability.PowerManager.ThermalManager
29
30**Parameters**
31
32| Name  | Type                        | Mandatory| Description                          |
33| -------- | ---------------------------- | ---- | ------------------------------ |
34| callback | Callback&lt;ThermalLevel&gt; | Yes  | Callback used to return thermal level. This parameter is of the function type.|
35
36**Error codes**
37
38For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
39
40| ID  | Error Message   |
41|---------|---------|
42| 401     | Parameter error. Possible causes: 1. Incorrect parameter types. |
43
44**Example**
45
46```js
47try {
48    thermal.registerThermalLevelCallback((level: thermal.ThermalLevel) => {
49        console.info('thermal level is: ' + level);
50    });
51    console.info('register thermal level callback success.');
52} catch(err) {
53    console.error('register thermal level callback failed, err: ' + err);
54}
55```
56
57## thermal.unregisterThermalLevelCallback<sup>9+</sup>
58
59unregisterThermalLevelCallback(callback?: Callback\<void>): void
60
61Unsubscribes from thermal level changes.
62
63**System capability**: SystemCapability.PowerManager.ThermalManager
64
65**Parameters**
66
67| Name  | Type                | Mandatory| Description                                          |
68| -------- | -------------------- | ---- | ---------------------------------------------- |
69| callback | Callback&lt;void&gt; | No  | (Optional) Callback that returns no value.|
70
71**Error codes**
72
73For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
74
75| ID  | Error Message   |
76|---------|---------|
77| 401     | Parameter error. Possible causes: 1. Incorrect parameter types. |
78
79**Example**
80
81```js
82try {
83    thermal.unregisterThermalLevelCallback(() => {
84        console.info('unsubscribe thermal level success.');
85    });
86    console.info('unregister thermal level callback success.');
87} catch(err) {
88    console.error('unregister thermal level callback failed, err: ' + err);
89}
90```
91
92## thermal.getLevel<sup>9+</sup>
93
94getLevel(): ThermalLevel
95
96Obtains the current thermal level.
97
98**System capability**: SystemCapability.PowerManager.ThermalManager
99
100**Return value**
101
102| Type        | Description        |
103| ------------ | ------------ |
104| ThermalLevel | Thermal level.|
105
106**Example**
107
108```js
109let level = thermal.getLevel();
110console.info('thermal level is: ' + level);
111```
112
113## thermal.subscribeThermalLevel<sup>(deprecated)</sup>
114
115subscribeThermalLevel(callback: AsyncCallback&lt;ThermalLevel&gt;): void
116
117> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [thermal.registerThermalLevelCallback](#thermalregisterthermallevelcallback9).
118
119Subscribes to thermal level changes.
120
121**System capability**: SystemCapability.PowerManager.ThermalManager
122
123**Parameters**
124
125| Name  | Type                             | Mandatory| Description                                                        |
126| -------- | --------------------------------- | ---- | ------------------------------------------------------------ |
127| callback | AsyncCallback&lt;ThermalLevel&gt; | Yes  | Callback used to return the result. The return value contains only one parameter, that is, thermal level.|
128
129**Example**
130
131```js
132thermal.subscribeThermalLevel((err: Error, level: thermal.ThermalLevel) => {
133    console.info('thermal level is: ' + level);
134});
135```
136
137## thermal.unsubscribeThermalLevel<sup>(deprecated)</sup>
138
139unsubscribeThermalLevel(callback?: AsyncCallback\<void>): void
140
141> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [thermal.unregisterThermalLevelCallback](#thermalunregisterthermallevelcallback9).
142
143Unsubscribes from thermal level changes.
144
145**System capability**: SystemCapability.PowerManager.ThermalManager
146
147**Parameters**
148
149| Name  | Type                     | Mandatory| Description                                          |
150| -------- | ------------------------- | ---- | ---------------------------------------------- |
151| callback | AsyncCallback&lt;void&gt; | No  | Callback that returns no value. If this parameter is not set, all callbacks will be unregistered.|
152
153**Example**
154
155```js
156thermal.unsubscribeThermalLevel(() => {
157    console.info('unsubscribe thermal level success.');
158});
159```
160
161## thermal.getThermalLevel<sup>(deprecated)</sup>
162
163getThermalLevel(): ThermalLevel
164
165> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [thermal.getLevel](#thermalgetlevel9).
166
167Obtains the current thermal level.
168
169**System capability**: SystemCapability.PowerManager.ThermalManager
170
171**Return value**
172
173| Type          | Description    |
174| ------------ | ------ |
175| ThermalLevel | Thermal level.|
176
177**Example**
178
179```js
180let level = thermal.getThermalLevel();
181console.info('thermal level is: ' + level);
182```
183
184## ThermalLevel
185
186Enumerates thermal levels.
187
188**System capability**: SystemCapability.PowerManager.ThermalManager
189
190| Name      | Value  | Description                                                        |
191| ---------- | ---- | ------------------------------------------------------------ |
192| COOL       | 0    | The device is cool, and services are not restricted.            |
193| NORMAL     | 1    | The device is in the normal temperature range but it is getting warm. You need to downgrade or reduce the load of imperceptible services.|
194| WARM       | 2    | The device is warm. You need to stop or delay some imperceptible services.|
195| HOT        | 3    | The device is heating up. You need to stop all imperceptible services and downgrade or reduce the load of non-critical services.|
196| OVERHEATED | 4    | The device is overheated. You need to stop all imperceptible services and downgrade or reduce the load of major foreground services.|
197| WARNING    | 5    | The device is overheated and is about to enter the emergency state. You need to stop all imperceptible services and downgrade major foreground services to the maximum extent.|
198| EMERGENCY  | 6    | The device has entered the emergency state. You need to stop all services except those for fundamental use.|
199| ESCAPE<sup>11+</sup>     | 7    | The device is about to enter the escape state. You need to stop all services and take necessary emergency measures such as data backup.<br>Note: This API is supported since API version 11.|
200