1# Time Subsystem ChangeLog
2
3## cl.time.1 API Error Change
4
5Errors thrown by timer APIs of the time subsystem: **202** (non-system application) and **401** (invalid parameters).
6
7**Change Impacts**
8
9The API change is forward compatible. Applications developed based on earlier versions can still use the APIs, and corresponding error handling is added. The original functions are not affected.
10
11**Key API/Component Changes**
12
13Before change:
14  - The API throws an error message without an error code.
15
16After change:
17  - The API throws an error message with an error code. Error code **202** indicates that the application is not a system application, and error code **401** indicates that the parameters are invalid.
18
19    | Module           | Class       | Method/Attribute/Enumeration/Constant                                         | Change Type|
20    | ----------------- | ----------- | ------------------------------------------------------------ | -------- |
21    | @ohos.systemTimer | systemTimer | function createTimer(options: TimerOptions, callback: AsyncCallback\<number>): void | Changed    |
22    | @ohos.systemTimer | systemTimer | function createTimer(options: TimerOptions): Promise\<number> | Changed    |
23    | @ohos.systemTimer | systemTimer | function startTimer(timer: number, triggerTime: number, callback: AsyncCallback\<void>): void | Changed    |
24    | @ohos.systemTimer | systemTimer | function startTimer(timer: number, triggerTime: number): Promise\<void> | Changed    |
25    | @ohos.systemTimer | systemTimer | function stopTimer(timer: number, callback: AsyncCallback\<void>): void | Changed    |
26    | @ohos.systemTimer | systemTimer | function stopTimer(timer: number): Promise\<void>            | Changed    |
27    | @ohos.systemTimer | systemTimer | function destroyTimer(timer: number, callback: AsyncCallback\<void>): void | Changed    |
28    | @ohos.systemTimer | systemTimer | function destroyTimer(timer: number): Promise\<void>         | Changed    |
29
30
31**Adaptation Guide**
32
33Refer to the code below to capture errors when **systemTimer** APIs are called in applications.
34
35createTimer callback mode:
36
37**Example**
38
39```js
40export default {
41  systemTimer () {
42    let options = {
43      type: systemTimer.TIMER_TYPE_REALTIME,
44      repeat: false
45    };
46    try {
47      systemTimer.createTimer(options, (error, timerId) => {
48        if (error) {
49          // Capture the permission denial error.
50          console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
51        }
52        console.info(`Succeeded in creating timer. timerId: ${timerId}`);
53      });
54    } catch(e) {
55      // Capture the parameter verification error.
56      console.info(`Failed to create timer. message: ${e.message}, code: ${e.code}`);
57    }
58  }
59}
60```
61
62createTimer promise mode:
63
64**Example**
65
66```js
67export default {
68  systemTimer () {
69    let options = {
70      type: systemTimer.TIMER_TYPE_REALTIME,
71      repeat: false
72    };
73    try {
74      systemTimer.createTimer(options).then((timerId) => {
75        console.info(`Succeeded in creating timer. timerId: ${timerId}`);
76      }).catch((error) => {
77        // Capture the permission denial error.
78        console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
79      });
80    } catch(e) {
81      // Capture the parameter verification error.
82      console.info(`Failed to create timer. message: ${e.message}, code: ${e.code}`);
83    }
84  }
85}
86```
87
88startTimer callback mode:
89
90**Example**
91
92```js
93export default {
94  async systemTimer () {
95    let options = {
96      type: systemTimer.TIMER_TYPE_REALTIME,
97      repeat:false
98    }
99    let timerId = await systemTimer.createTimer(options);
100    let triggerTime = new Date().getTime();
101    triggerTime += 3000;
102    try {
103      systemTimer.startTimer(timerId, triggerTime, (error) => {
104        if (error) {
105          // Capture the permission denial error.
106          console.error(`Failed to start timer. message: ${error.message}, code: ${error.code}`);
107        }
108        });
109    } catch (e) {
110      // Capture the parameter verification error.
111      console.info(`Failed to start timer. message: ${e.message}, code: ${e.code}`);
112    }
113  }
114}
115```
116
117startTimer promise mode:
118
119**Example**
120
121```js
122export default {
123  async systemTimer (){
124    let options = {
125      type: systemTimer.TIMER_TYPE_REALTIME,
126      repeat:false
127    }
128    let timerId = await systemTimer.createTimer(options);
129    let triggerTime = new Date().getTime();
130    triggerTime += 3000;
131    try {
132      systemTimer.startTimer(timerId, triggerTime).then((data) => {
133        console.log(`Succeeded in startting timer. Data:` + data);
134      }).catch((error) => {
135        // Capture the permission denial error.
136        console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`);
137      });
138    } catch (e) {
139      // Capture the parameter verification error.
140      console.info(`Failed to start timer. message: ${e.message}, code: ${e.code}`);
141    }
142  }
143}
144```
145
146stopTimer callback mode:
147
148**Example**
149
150```js
151export default {
152  async systemTimer () {
153    let options = {
154      type: systemTimer.TIMER_TYPE_REALTIME,
155      repeat:false
156    }
157    let timerId = await systemTimer.createTimer(options);
158    let triggerTime = new Date().getTime();
159    triggerTime += 3000;
160    systemTimer.startTimer(timerId, triggerTime);
161    try {
162      systemTimer.stopTimer(timerId, triggerTime, (error) => {
163        if (error) {
164          // Capture the permission denial error.
165          console.error(`Failed to stop timer. message: ${error.message}, code: ${error.code}`);
166        }
167        });
168    } catch (e) {
169      // Capture the parameter verification error.
170      console.info(`Failed to stop timer. message: ${e.message}, code: ${e.code}`);
171    }
172  }
173}git
174```
175
176stopTimer promise mode:
177
178**Example**
179
180```js
181export default {
182  async systemTimer (){
183    let options = {
184      type: systemTimer.TIMER_TYPE_REALTIME,
185      repeat:false
186    }
187    let timerId = await systemTimer.createTimer(options);
188    let triggerTime = new Date().getTime();
189    triggerTime += 3000;
190    systemTimer.startTimer(timerId, triggerTime);
191    try {
192      systemTimer.stopTimer(timerId, triggerTime).then((data) => {
193        console.log(`Succeeded in stop timer. Data:` + data);
194      }).catch((error) => {
195        // Capture the permission denial error.
196        console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`);
197      });
198    } catch (e) {
199      // Capture the parameter verification error.
200      console.info(`Failed to stop timer. message: ${e.message}, code: ${e.code}`);
201    }
202  }
203}
204```
205
206destroyTimer callback mode:
207
208**Example**
209
210```js
211export default {
212  async systemTimer () {
213    let options = {
214      type: systemTimer.TIMER_TYPE_REALTIME,
215      repeat:false
216    }
217    let timerId = await systemTimer.createTimer(options);
218    let triggerTime = new Date().getTime();
219    triggerTime += 3000;
220    systemTimer.startTimer(timerId, triggerTime);
221    systemTimer.stopTimer(timerId);
222    try {
223      systemTimer.destroyTimer(timerId, triggerTime, (error) => {
224        if (error) {
225          // Capture the permission denial error.
226          console.error(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`);
227        }
228        });
229    } catch (e) {
230      // Capture the parameter verification error.
231      console.info(`Failed to destroy timer. message: ${e.message}, code: ${e.code}`);
232    }
233  }
234}
235```
236
237destroyTimer promise mode:
238
239**Example**
240
241```js
242export default {
243  async systemTimer (){
244    let options = {
245      type: systemTimer.TIMER_TYPE_REALTIME,
246      repeat:false
247    }
248    let timerId = await systemTimer.createTimer(options);
249    let triggerTime = new Date().getTime();
250    triggerTime += 3000;
251    systemTimer.startTimer(timerId, triggerTime);
252    systemTimer.stopTimer(timerId);
253    try {
254      systemTimer.destroyTimer(timerId, triggerTime).then((data) => {
255        console.log(`Succeeded in destroy timer. Data:` + data);
256      }).catch((error) => {
257        // Capture the permission denial error.
258        console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`);
259      });
260    } catch (e) {
261      // Capture the parameter verification error.
262      console.info(`Failed to destroy timer. message: ${e.message}, code: ${e.code}`);
263    }
264  }
265}
266```
267
268## cl.time.2 API Error Change
269
270Errors thrown by timer APIs of the time subsystem: **201** (permission denied), **202** (non-system application), and **401** (invalid parameters).
271
272**Change Impacts**
273
274Applications developed based on earlier versions can still use the APIs. When new APIs are used, errors must be captured and processed.
275
276**Key API/Component Changes**
277
278Before change:
279  - The API throws an error message with error code **-1**.
280
281After change:
282  - The API throws an error message with an error code. Error code **201** indicates that the permission is denied, error code **202** indicates that the application is not a system application, and error code **401** indicates that the parameters are invalid.
283
284Deprecated APIs can be replaced with new ones with same names.
285
286| Original API          | New API              |
287| ---------------- | -------------------- |
288| @ohos.systemTime | @ohos.systemDateTime |
289
290**Adaptation Guide**
291
292Refer to the code below to capture errors when **systemTime** APIs are called in applications. In the examples, the **setTime** API is invoked.
293
294In callback mode:
295
296**Example**
297
298```js
299import systemDateTime from @ohos.systemDateTime
300// Set the system time to 2021-01-20 02:36:25.
301let time = 1611081385000;
302try {
303  systemDateTime.setTime(time, (error) => {
304    // Capture permission denial and non-system-application errors.
305    if (error) {
306      console.info(`Failed to setting time. message: ${error.message}, code: ${error.code}`);
307      return;
308    }
309    console.info(`Succeeded in setting time.`);
310  })
311} catch(e) {
312  // Capture the parameter verification error.
313  console.info(`Failed to set time. message: ${e.message}, code: ${e.code}`);
314}
315```
316
317In promise mode:
318
319**Example**
320
321```js
322import systemDateTime from @ohos.systemDateTime
323// Set the system time to 2021-01-20 02:36:25.
324let time = 1611081385000;
325try {
326  systemDateTime.setTime(time).then(() => {
327    console.info(`Succeeded in setting time.`);
328  }).catch((error) => {
329    // Capture permission denial and non-system-application errors.
330    console.info(`Failed to setting time. message: ${error.message}, code: ${error.code}`);
331  });
332} catch(e) {
333   // Capture the parameter verification error.
334  console.info(`Failed to set time. message: ${e.message}, code: ${e.code}`);
335}
336```
337