@ohos.systemTimer (System Timer) (System API)
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 provided by this module are system APIs.
Modules to Import
import { systemTimer } from '@kit.BasicServicesKit';
Constants
Provides the constants that define the supported timer types.
System capability: SystemCapability.MiscServices.Time
| Name | Type | Value | Description |
|---|---|---|---|
| TIMER_TYPE_REALTIME | number | 1 | CPU time type. (The start time of the timer cannot be later than the current system time.) |
| TIMER_TYPE_WAKEUP | number | 2 | Wakeup type. (If the wakeup type is not set, the system does not wake up until it exits the sleep state.) |
| TIMER_TYPE_EXACT | number | 4 | Exact type. (If the system time is changed, the offset may be 1s at most.) |
| TIMER_TYPE_IDLE | number | 8 | Idle timer type (supported only for system services). |
TimerOptions
Defines the initialization options for the system timer.
System capability: SystemCapability.MiscServices.Time
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| type | number | No | No | Timer types. Use pipe (|) symbol |
| repeat | boolean | No | No | 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. |
| autoRestore15+ | boolean | No | Yes | Whether the timer is restored after the device is restarted. The value true means that the timer is restored after the restart, and the value false means the opposite. This parameter can be set to true only for timers that are not of the TIMER_TYPE_REALTIME type and have wantAgent configured. The default value is false. |
| name15+ | string | No | Yes | Timer name, with a maximum length of 64 bytes. A UID cannot contain two timers with the same name. If a timer with the same name as an existing timer is created, the existing timer is destroyed. The default value is an empty string. |
| interval | number | No | Yes | Interval between two consecutive timers, in milliseconds. For a repeating timer, the minimum value of interval is 1s and the maximum value is 365 days. It is recommended that the value be greater than or equal to 5000 ms. For a one-shot timer, the value is 0. Default value: 0. |
| wantAgent | WantAgent | No | Yes | WantAgent object of the notification to be sent when the timer expires. (An application MainAbility can be started, but not a ServiceAbility.) The default value is empty. |
| callback | void | No | Yes | Callback to be executed by the user. The default value is empty. |
systemTimer.createTimer
createTimer(options: TimerOptions, callback: AsyncCallback<number>): void
Creates a timer. This API uses an asynchronous callback to return the result.
NOTE
This API must be used together with systemTimer.destroyTimer. Otherwise, memory leakage occurs.
System capability: SystemCapability.MiscServices.Time
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | TimerOptions | Yes | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and WantAgent options. |
| callback | AsyncCallback<number> | Yes | Callback used to return the timer ID. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat: false
};
try {
systemTimer.createTimer(options, (error: BusinessError, timerId: Number) => {
if (error) {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
return;
}
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.createTimer
createTimer(options: TimerOptions): Promise<number>
Creates a timer. This API uses a promise to return the timer ID.
NOTE
This API must be used together with systemTimer.destroyTimer. Otherwise, memory leakage occurs.
System capability: SystemCapability.MiscServices.Time
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| options | TimerOptions | Yes | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and WantAgent options. |
Return value
| Type | Description |
|---|---|
| Promise<number> | Promise used to return the timer ID. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
};
try {
systemTimer.createTimer(options).then((timerId: Number) => {
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.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. If TIMER_TYPE_REALTIME is set as the timer type, the value of triggerTime is the system startup time, which can be obtained by calling systemDateTime.getUptime(STARTUP). If TIMER_TYPE_REALTIME is not set, the value of triggerTime is the wall time, which can be obtained by calling systemDateTime.getTime(). |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let triggerTime: number = new Date().getTime();
triggerTime += 3000;
try {
systemTimer.createTimer(options).then((timerId: number) => {
systemTimer.startTimer(timerId, triggerTime, (error: BusinessError) => {
if (error) {
console.error(`Failed to start timer. message: ${error.message}, code: ${error.code}`);
return;
}
console.info(`Succeeded in starting the timer.`);
});
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.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. If TIMER_TYPE_REALTIME is set as the timer type, the value of triggerTime is the system startup time, which can be obtained by calling systemDateTime.getUptime(STARTUP). If TIMER_TYPE_REALTIME is not set, the value of triggerTime is the wall time, which can be obtained by calling systemDateTime.getTime(). |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let triggerTime: number = new Date().getTime();
triggerTime += 3000;
try {
systemTimer.createTimer(options).then((timerId: number) => {
systemTimer.startTimer(timerId, triggerTime).then(() => {
console.info(`Succeeded in starting the timer.`);
}).catch((error: BusinessError) => {
console.error(`Failed to start timer. message: ${error.message}, code: ${error.code}`);
});
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.stopTimer
stopTimer(timer: number, callback: AsyncCallback<void>): void
Stops the 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. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let triggerTime: number = new Date().getTime();
triggerTime += 3000;
try {
systemTimer.createTimer(options).then((timerId: number) => {
systemTimer.startTimer(timerId, triggerTime);
systemTimer.stopTimer(timerId, (error: BusinessError) => {
if (error) {
console.error(`Failed to stop timer. message: ${error.message}, code: ${error.code}`);
return;
}
console.info(`Succeeded in stopping the timer.`);
});
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.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. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let triggerTime: number = new Date().getTime();
triggerTime += 3000;
try {
systemTimer.createTimer(options).then((timerId: number) => {
systemTimer.startTimer(timerId, triggerTime);
systemTimer.stopTimer(timerId).then(() => {
console.info(`Succeeded in stopping the timer.`);
}).catch((error: BusinessError) => {
console.error(`Failed to stop timer. message: ${error.message}, code: ${error.code}`);
});
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.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. |
| callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let triggerTime: number = new Date().getTime();
triggerTime += 3000;
try {
systemTimer.createTimer(options).then((timerId: number) => {
systemTimer.startTimer(timerId, triggerTime);
systemTimer.stopTimer(timerId);
systemTimer.destroyTimer(timerId, (error: BusinessError) => {
if (error) {
console.error(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`);
return;
}
console.info(`Succeeded in destroying the timer.`);
});
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}
systemTimer.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. |
Return value
| Type | Description |
|---|---|
| Promise<void> | Promise that returns no value. |
Error codes
For details about the error codes, see Time and Time Zone Service Error Codes.
| ID | Error Message |
|---|---|
| 202 | Permission verification failed. A non-system application calls a system API. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
Example
import { BusinessError } from '@kit.BasicServicesKit';
let options: systemTimer.TimerOptions = {
type: systemTimer.TIMER_TYPE_REALTIME,
repeat:false
}
let triggerTime: number = new Date().getTime();
triggerTime += 3000;
try {
systemTimer.createTimer(options).then((timerId: number) => {
systemTimer.startTimer(timerId, triggerTime);
systemTimer.stopTimer(timerId);
systemTimer.destroyTimer(timerId).then(() => {
console.info(`Succeeded in destroying the timer.`);
}).catch((error: BusinessError) => {
console.error(`Failed to destroy timer. message: ${error.message}, code: ${error.code}`);
});
console.info(`Succeeded in creating a timer. timerId: ${timerId}`);
}).catch((error: BusinessError) => {
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
});
} catch(e) {
let error = e as BusinessError;
console.error(`Failed to create timer. message: ${error.message}, code: ${error.code}`);
}