# System Timer
The **systemTimer** module provides system timer features. You can use the APIs of this module to implement the alarm clock and other timer services.
> **NOTE**
>- 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.
>- The APIs of this module are system APIs and cannot be called by third-party applications.
## Modules to Import
```
import systemTimer from '@ohos.systemTimer';
```
## systemTime.createTimer
createTimer(options: TimerOptions, callback: AsyncCallback<number>): void
Creates a timer. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ---------------------------------| ---- | --------------------------------------------------------------------------- |
| options | [TimerOptions](#timeroptions) | Yes | Timer options. |
**Return value**
| Type | Description |
| ------------------------- | ------------------------------------------------------------ |
| syncCallback<number>| Callback used to return the timer ID. |
**Example**
```js
export default {
systemTimer () {
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat: false
}
systemTimer.createTimer(options, (error, data) => {
if (error) {
console.error(`failed to systemTime.createTimer ` + JSON.stringify(error));
return;
}
console.log(`systemTime.createTimer success data : ` + JSON.stringify(data));
});
}
}
```
## systemTime.createTimer
createTimer(options: TimerOptions): Promise<number>
Creates a timer. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ---------------------------------| ---- | --------------------------------------------------------------------------- |
| options | [TimerOptions](#timeroptions) | Yes | Timer options. |
**Return value**
| Type | Description |
| --------------------- | ------------------------------------------------------------ |
| Promise<number> | Promise used to return the timer ID. |
**Example**
```js
export default {
systemTimer () {
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
systemTimer.createTimer(options).then((data) => {
console.log(`systemTime.createTimer success data : ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to systemTime.createTimer because ` + JSON.stringify(error));
});
}
}
```
## systemTime.startTimer
startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void
Starts a timer. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. |
| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. |
**Example**
```js
export default {
systemTimer () {
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let timerId = systemTimer.createTimer(options)
let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime, (error, data) => {
if (error) {
console.error(`failed to systemTime.startTimer ` + JSON.stringify(error));
return;
}
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
});
}
}
```
## systemTime.startTimer
startTimer(timer: number, triggerTime: number): Promise<void>
Starts a timer. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | --------------------------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. | | triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. |
**Example**
```js
export default {
systemTimer (){
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let timerId = systemTimer.createTimer(options)
let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime).then((data) => {
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error));
});
}
}
```
## systemTime.stopTimer
stopTimer(timer: number, callback: AsyncCallback<void>): void
Stops a timer. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. |
**Example**
```js
export default {
systemTimer () {
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let timerId = systemTimer.createTimer(options)
let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stoptTimer(timerId, (error, data) => {
if (error) {
console.error(`failed to systemTime.startTimer ` + JSON.stringify(error));
return;
}
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
});
}
}
```
## systemTime.stopTimer
stopTimer(timer: number): Promise<void>
Stops a timer. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. |
**Example**
```js
export default {
systemTimer (){
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let timerId = systemTimer.createTimer(options)
let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stoptTimer(timerId).then((data) => {
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error));
});
}
}
```
## systemTime.destroyTimer
destroyTimer(timer: number, callback: AsyncCallback<void>): void
Destroys a timer. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. |
**Example**
```js
export default {
systemTimer () {
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let timerId = systemTimer.createTimer(options)
let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stopTimer(timerId)
systemTimer.destroyTimer(timerId, (error, data) => {
if (error) {
console.error(`failed to systemTime.startTimer ` + JSON.stringify(error));
return;
}
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
});
}
}
```
## systemTime.destroyTimer
destroyTimer(timer: number): Promise<void>
Destroys a timer. This API uses a promise to return the result.
**System capability**: SystemCapability.MiscServices.Time
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------------------------ |
| timer | number | Yes | ID of the timer. |
**Example**
```js
export default {
systemTimer (){
var options = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let timerId = systemTimer.createTimer(options)
let triggerTime = new Date().getTime()
triggerTime += 3000
systemTimer.startTimer(timerId, triggerTime)
systemTimer.stopTimer(timerId)
systemTimer.destroyTimer(timerId, 10000).then((data) => {
console.log(`systemTime.startTimer success data : ` + JSON.stringify(data));
}).catch((error) => {
console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error));
});
}
}
```
## TimerOptions
Defines the initialization options for **createTimer**.
**System capability**: SystemCapability.MiscServices.Time
| Name | Type | Mandatory| Description |
| -------- | ------------------| ---- | ------------------------------------------------------------------------------------------------------------------------- |
| type | number | Yes | **const TIMER_TYPE_REALTIME**: sets the timer to the CPU time type. If it is not specified, the timer is of the wall-time type.
**const TIMER_TYPE_WAKEUP**: sets the timer to the wakeup type. If it is not specified, the timer is of the non-wakeup type.
**const TIMER_TYPE_EXACT**: sets the timer to the exact type. If it is not specified, the timer is of the non-exact type.
**const TIMER_TYPE_IDLE: number**: sets the timer to the idle type. If it is not specified, the timer is of the non-idle type (not yet supported). |
| 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. |
| 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**. |
| wantAgent| wantAgent | No | **wantAgent** object of the notification to be sent when the timer expires. (An application MainAbility can be started, but not a Service ability.) |
| callback | number | Yes | Callback used to return the timer ID. |