• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.systemTimer (System Timer)
2
3The **systemTimer** module provides system timer features. You can use the APIs of this module to implement the alarm clock and other timer services.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8> - The APIs provided by this module are system APIs.
9
10## Modules to Import
11
12
13```js
14import systemTimer from '@ohos.systemTimer';
15```
16
17## Constants
18
19Provides the constants that define the supported timer types.
20
21**System capability**: SystemCapability.MiscServices.Time
22
23| Name               | Type  | Value  | Description                        |
24| ------------------- | ------ | ---- | ---------------------------- |
25| TIMER_TYPE_REALTIME | number | 1    | CPU time type. (The start time of the timer cannot be later than the current system time.)        |
26| TIMER_TYPE_WAKEUP   | number | 2    | Wakeup type.                |
27| TIMER_TYPE_EXACT    | number | 4    | Exact type.                |
28| TIMER_TYPE_IDLE     | number | 8    | Idle type (not supported currently).|
29
30 ## TimerOptions
31
32Defines the initialization options for **createTimer**.
33
34**System capability**: SystemCapability.MiscServices.Time
35
36| Name     | Type                                         | Mandatory| Description                                                        |
37| --------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
38| type      | number                                        | Yes  | Timer type.<br>**1**: CPU time type. (The start time of the timer cannot be later than the current system time.)<br>**2**: wakeup type.<br>**4**: exact type.<br>**8**: idle type (not supported currently).|
39| repeat    | boolean                                       | Yes  | Whether the timer is a repeating timer. The value **true** means that the timer is a repeating timer, and **false** means that the timer is a one-shot timer.                       |
40| interval  | number                                        | No  | Repeat interval. For a repeating timer, the value must be greater than 5000 ms. For a one-shot timer, the value is **0**.|
41| wantAgent | [WantAgent](js-apis-app-ability-wantAgent.md) | No  | **WantAgent** object of the notification to be sent when the timer expires. (An application MainAbility can be started, but not a Service ability.)|
42| callback  | number                                        | Yes  | Callback used to return the timer ID.                            |
43
44
45## systemTimer.createTimer
46
47createTimer(options: TimerOptions, callback: AsyncCallback&lt;number&gt;): void
48
49Creates a timer. This API uses an asynchronous callback to return the result.
50
51**System capability**: SystemCapability.MiscServices.Time
52
53**Parameters**
54
55| Name  | Type                         | Mandatory| Description                                                        |
56| -------- | ----------------------------- | ---- | ------------------------------------------------------------ |
57| options  | [TimerOptions](#timeroptions) | Yes  | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and **WantAgent** options.|
58| callback | AsyncCallback&lt;number>      | Yes  | Callback used to return the timer ID.                                  |
59
60**Example**
61
62```js
63export default {
64  systemTimer () {
65    let options = {
66      type: systemTimer.TIMER_TYPE_REALTIME,
67      repeat: false
68    };
69    try {
70      systemTimer.createTimer(options, (error, timerId) => {
71        if (error) {
72          console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
73          return;
74        }
75        console.info(`Succeeded in creating timer. timerId: ${timerId}`);
76      });
77    } catch(e) {
78      console.info(`Failed to create timer. message: ${e.message}, code: ${e.code}`);
79    }
80  }
81}
82```
83
84## systemTimer.createTimer
85
86createTimer(options: TimerOptions): Promise&lt;number&gt;
87
88Creates a timer. This API uses a promise to return the result.
89
90**System capability**: SystemCapability.MiscServices.Time
91
92**Parameters**
93
94| Name | Type                         | Mandatory| Description                                                        |
95| ------- | ----------------------------- | ---- | ------------------------------------------------------------ |
96| options | [TimerOptions](#timeroptions) | Yes  | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and **WantAgent** options.|
97
98**Return value**
99
100| Type                 | Description                         |
101| --------------------- | ----------------------------- |
102| Promise&lt;number&gt; | Promise used to return the timer ID.|
103
104**Example**
105
106```js
107export default {
108  systemTimer () {
109    let options = {
110      type: systemTimer.TIMER_TYPE_REALTIME,
111      repeat:false
112    };
113    try {
114      systemTimer.createTimer(options).then((timerId) => {
115        console.info(`Succeeded in creating timer. timerId: ${timerId}`);
116      }).catch((error) => {
117        console.info(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
118      });
119    } catch(e) {
120      console.info(`Failed to create timer. message: ${e.message}, code: ${e.code}`);
121    }
122  }
123}
124```
125
126## systemTimer.startTimer
127
128startTimer(timer: number, triggerTime: number, callback: AsyncCallback&lt;void&gt;): void
129
130Starts a timer. This API uses an asynchronous callback to return the result.
131
132**System capability**: SystemCapability.MiscServices.Time
133
134**Parameters**
135
136| Name     | Type                  | Mandatory| Description                          |
137| ----------- | ---------------------- | ---- | ------------------------------ |
138| timer       | number                 | Yes  | ID of the timer.                  |
139| triggerTime | number                 | Yes  | Time when the timer is triggered, in milliseconds.|
140| callback    | AsyncCallback&lt;void> | Yes  | Callback used to return the result.                    |
141
142**Example**
143
144```js
145export default {
146  async systemTimer () {
147    let options = {
148      type: systemTimer.TIMER_TYPE_REALTIME,
149      repeat:false
150    }
151  let timerId = await systemTimer.createTimer(options);
152  let triggerTime = new Date().getTime();
153  triggerTime += 3000;
154  try {
155      systemTimer.startTimer(timerId, triggerTime, (error) => {
156        if (error) {
157          console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`);
158          return;
159        }
160        console.info(`Succeeded in starting timer.`);
161      });
162    } catch(e) {
163      console.info(`Failed to start timer. message: ${e.message}, code: ${e.code}`);
164    }
165  }
166}
167```
168
169## systemTimer.startTimer
170
171startTimer(timer: number, triggerTime: number): Promise&lt;void&gt;
172
173Starts a timer. This API uses a promise to return the result.
174
175**System capability**: SystemCapability.MiscServices.Time
176
177**Parameters**
178
179| Name     | Type  | Mandatory| Description                          |
180| ----------- | ------ | ---- | ------------------------------ |
181| timer       | number | Yes  | ID of the timer.                  |
182| triggerTime | number | Yes  | Time when the timer is triggered, in milliseconds.|
183
184**Return value**
185
186| Type          | Description                     |
187| -------------- | ------------------------- |
188| Promise\<void> | Promise that returns no value.|
189
190**Example**
191
192```js
193export default {
194  async systemTimer (){
195    let options = {
196      type: systemTimer.TIMER_TYPE_REALTIME,
197      repeat:false
198    }
199    let timerId = await systemTimer.createTimer(options);
200    let triggerTime = new Date().getTime();
201    triggerTime += 3000;
202    try {
203      systemTimer.startTimer(timerId, triggerTime).then(() => {
204        console.info(`Succeeded in starting timer.`);
205         }).catch((error) => {
206        console.info(`Failed to start timer. message: ${error.message}, code: ${error.code}`);
207      });
208    } catch(e) {
209      console.info(`Failed to start timer. message: ${e.message}, code: ${e.code}`);
210    }
211  }
212}
213```
214
215## systemTimer.stopTimer
216
217stopTimer(timer: number, callback: AsyncCallback&lt;void&gt;): void
218
219Stops a timer. This API uses an asynchronous callback to return the result.
220
221**System capability**: SystemCapability.MiscServices.Time
222
223**Parameters**
224
225| Name  | Type                  | Mandatory| Description        |
226| -------- | ---------------------- | ---- | ------------ |
227| timer    | number                 | Yes  | ID of the timer.|
228| callback | AsyncCallback&lt;void> | Yes  | Callback used to return the result.  |
229
230**Example**
231
232```js
233export default {
234  async systemTimer () {
235    let options = {
236      type: systemTimer.TIMER_TYPE_REALTIME,
237      repeat:false
238    }
239    let timerId = await systemTimer.createTimer(options);
240    let triggerTime = new Date().getTime();
241    triggerTime += 3000;
242    systemTimer.startTimer(timerId, triggerTime);
243    try {
244      systemTimer.stopTimer(timerId, (error) => {
245        if (error) {
246          console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`);
247          return;
248        }
249        console.info(`Succeeded in stopping timer.`);
250      });
251    } catch(e) {
252      console.info(`Failed to stop timer. message: ${e.message}, code: ${e.code}`);
253    }
254  }
255}
256```
257
258## systemTimer.stopTimer
259
260stopTimer(timer: number): Promise&lt;void&gt;
261
262Stops a timer. This API uses a promise to return the result.
263
264**System capability**: SystemCapability.MiscServices.Time
265
266**Parameters**
267
268| Name| Type  | Mandatory| Description        |
269| ------ | ------ | ---- | ------------ |
270| timer  | number | Yes  | ID of the timer.|
271
272**Return value**
273
274| Type          | Description                     |
275| -------------- | ------------------------- |
276| Promise\<void> | Promise that returns no value.|
277
278**Example**
279
280```js
281export default {
282  async systemTimer (){
283    let options = {
284      type: systemTimer.TIMER_TYPE_REALTIME,
285      repeat:false
286    }
287    let timerId = await systemTimer.createTimer(options);
288    let triggerTime = new Date().getTime();
289    triggerTime += 3000;
290    systemTimer.startTimer(timerId, triggerTime);
291    try {
292      systemTimer.stopTimer(timerId).then(() => {
293        console.info(`Succeeded in stopping timer.`);
294      }).catch((error) => {
295        console.info(`Failed to stop timer. message: ${error.message}, code: ${error.code}`);
296      });
297    } catch(e) {
298      console.info(`Failed to stop timer. message: ${e.message}, code: ${e.code}`);
299    }
300  }
301}
302```
303
304## systemTimer.destroyTimer
305
306destroyTimer(timer: number, callback: AsyncCallback&lt;void&gt;): void
307
308Destroys a timer. This API uses an asynchronous callback to return the result.
309
310**System capability**: SystemCapability.MiscServices.Time
311
312**Parameters**
313
314| Name  | Type                  | Mandatory| Description        |
315| -------- | ---------------------- | ---- | ------------ |
316| timer    | number                 | Yes  | ID of the timer.|
317| callback | AsyncCallback&lt;void> | Yes  | Callback used to return the result.  |
318
319**Example**
320
321```js
322export default {
323  async systemTimer () {
324    let options = {
325      type: systemTimer.TIMER_TYPE_REALTIME,
326      repeat:false
327    }
328    let timerId = await systemTimer.createTimer(options);
329    let triggerTime = new Date().getTime();
330    triggerTime += 3000;
331    systemTimer.startTimer(timerId, triggerTime);
332    systemTimer.stopTimer(timerId);
333    try {
334      systemTimer.destroyTimer(timerId, (error) => {
335        if (error) {
336          console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`);
337          return;
338        }
339        console.info(`Succeeded in destroying timer.`);
340      });
341    } catch(e) {
342      console.info(`Failed to destroying timer. message: ${e.message}, code: ${e.code}`);
343    }
344  }
345}
346```
347
348## systemTimer.destroyTimer
349
350destroyTimer(timer: number): Promise&lt;void&gt;
351
352Destroys a timer. This API uses a promise to return the result.
353
354**System capability**: SystemCapability.MiscServices.Time
355
356**Parameters**
357
358| Name| Type  | Mandatory| Description        |
359| ------ | ------ | ---- | ------------ |
360| timer  | number | Yes  | ID of the timer.|
361
362**Return value**
363
364| Type          | Description                     |
365| -------------- | ------------------------- |
366| Promise\<void> | Promise that returns no value.|
367
368**Example**
369
370```js
371export default {
372  async systemTimer (){
373    let options = {
374      type: systemTimer.TIMER_TYPE_REALTIME,
375      repeat:false
376    }
377    let timerId = await systemTimer.createTimer(options);
378    let triggerTime = new Date().getTime();
379    triggerTime += 3000;
380    systemTimer.startTimer(timerId, triggerTime);
381    systemTimer.stopTimer(timerId);
382    try {
383      systemTimer.destroyTimer(timerId).then(() => {
384         console.info(`Succeeded in destroying timer.`);
385      }).catch((error) => {
386        console.info(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`);
387      });
388    } catch(e) {
389      console.info(`Failed to destroying timer. message: ${e.message}, code: ${e.code}`);
390    }
391  }
392}
393```
394