From 8bc3a81f836a617f142337f2477e58a8ce31f38e Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Tue, 13 Dec 2022 20:26:28 +0800 Subject: [PATCH] Update system-timer (12267) Signed-off-by: ester.zhou --- .../reference/apis/js-apis-system-timer.md | 329 ++++++++++-------- 1 file changed, 175 insertions(+), 154 deletions(-) diff --git a/en/application-dev/reference/apis/js-apis-system-timer.md b/en/application-dev/reference/apis/js-apis-system-timer.md index b7880eebd3..b83ed0e104 100644 --- a/en/application-dev/reference/apis/js-apis-system-timer.md +++ b/en/application-dev/reference/apis/js-apis-system-timer.md @@ -3,18 +3,46 @@ 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. +> +> - 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 -``` +```js import systemTimer from '@ohos.systemTimer'; ``` +## 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. | +| TIMER_TYPE_EXACT | number | 4 | Exact type. | +| TIMER_TYPE_IDLE | number | 8 | Idle type (not supported currently).| -## systemTime.createTimer + ## TimerOptions + +Defines the initialization options for **createTimer**. + +**System capability**: SystemCapability.MiscServices.Time + +| Name | Type | Mandatory| Description | +| --------- | --------------------------------- | ---- | ------------------------------------------------------------ | +| type | number | Yes | Timer type.
**1**: CPU time type. The start time of the timer cannot be later than the current system time.
**2**: wakeup type.
**4**: exact type.
**5**: idle type (not supported currently).| +| 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](js-apis-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.)| +| callback | number | Yes | Callback used to return the timer ID. | + + +## systemTimer.createTimer createTimer(options: TimerOptions, callback: AsyncCallback<number>): void @@ -24,38 +52,32 @@ Creates a timer. This API uses an asynchronous callback to return the result. **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ---------------------------------| ---- | --------------------------------------------------------------------------- | -| options | [TimerOptions](#timeroptions) | Yes | Timer options. | - -**Return value** - -| Type | Description | -| ------------------------- | ------------------------------------------------------------ | -| syncCallback<number>| Callback used to return the timer ID. | +| Name | Type | Mandatory| Description | +| -------- | ----------------------------- | ---- | ------------------------------------------------------------ | +| options | [TimerOptions](#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. | **Example** - ```js +```js export default { systemTimer () { - var options = { + let options = { type: systemTimer.TIMER_TYPE_REALTIME, repeat: false - } + }; systemTimer.createTimer(options, (error, data) => { if (error) { - console.error(`failed to systemTime.createTimer ` + JSON.stringify(error)); + console.error(`Failed to create timer. Cause:` + JSON.stringify(error)); return; } - console.log(`systemTime.createTimer success data : ` + JSON.stringify(data)); + console.log(`Succeeded in creating timer. Data:` + JSON.stringify(data)); }); } } - ``` - +``` -## systemTime.createTimer +## systemTimer.createTimer createTimer(options: TimerOptions): Promise<number> @@ -65,36 +87,35 @@ Creates a timer. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory| Description | -| ------- | ---------------------------------| ---- | --------------------------------------------------------------------------- | -| options | [TimerOptions](#timeroptions) | Yes | Timer options. | +| Name | Type | Mandatory| Description | +| ------- | ----------------------------- | ---- | ------------------------------------------------------------ | +| options | [TimerOptions](#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. | +| Type | Description | +| --------------------- | ----------------------------- | +| Promise<number> | Promise used to return the timer ID.| **Example** - ```js +```js export default { systemTimer () { - var options = { + let options = { type: systemTimer.TIMER_TYPE_REALTIME, repeat:false - } + }; systemTimer.createTimer(options).then((data) => { - console.log(`systemTime.createTimer success data : ` + JSON.stringify(data)); + console.log(`Succeeded in creating timer. Data:` + JSON.stringify(data)); }).catch((error) => { - console.error(`failed to systemTime.createTimer because ` + JSON.stringify(error)); + console.error(`Failed to create timer. Cause:` + JSON.stringify(error)); }); } } - ``` - +``` -## systemTime.startTimer +## systemTimer.startTimer startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void @@ -104,36 +125,35 @@ Starts a timer. This API uses an asynchronous callback to return the result. **Parameters** -| Name | Type | Mandatory| Description | -| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | -| timer | number | Yes | ID of the timer. | -| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. | - +| Name | Type | Mandatory| Description | +| ----------- | ---------------------- | ---- | ------------------------------ | +| timer | number | Yes | ID of the timer. | +| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** - ```js +```js export default { - systemTimer () { - var options = { + async systemTimer () { + let 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)); - }); + let timerId = await systemTimer.createTimer(options) + let triggerTime = new Date().getTime() + triggerTime += 3000 + systemTimer.startTimer(timerId, triggerTime, (error) => { + if (error) { + console.error(`Failed to start timer. Cause:` + JSON.stringify(error)); + return; + } + }); } } - ``` +``` -## systemTime.startTimer +## systemTimer.startTimer startTimer(timer: number, triggerTime: number): Promise<void> @@ -143,33 +163,39 @@ Starts a timer. This API uses a promise to return the result. **Parameters** -| Name | Type | Mandatory| Description | -| ----------- | --------------------------- | ---- | ------------------------------------------------------------ | -| timer | number | Yes | ID of the timer. | | triggerTime | number | Yes | Time when the timer is triggered, in milliseconds. | +| Name | Type | Mandatory| Description | +| ----------- | ------ | ---- | ------------------------------ | +| timer | number | Yes | ID of the timer. | +| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds.| + +**Return value** + +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise that returns no value.| **Example** - ```js +```js export default { - systemTimer (){ - var options = { + async systemTimer (){ + let options = { type: systemTimer.TIMER_TYPE_REALTIME, repeat:false } - let timerId = systemTimer.createTimer(options) - let triggerTime = new Date().getTime() + let timerId = await 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)); + console.log(`Succeeded in startting timer. Data:` + JSON.stringify(data)); }).catch((error) => { - console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error)); + console.error(`Failed to start timer. Cause:` + JSON.stringify(error)); }); } } - ``` - +``` -## systemTime.stopTimer +## systemTimer.stopTimer stopTimer(timer: number, callback: AsyncCallback<void>): void @@ -179,36 +205,35 @@ Stops a timer. This API uses an asynchronous callback to return the result. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | -| timer | number | Yes | ID of the timer. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ------------ | +| timer | number | Yes | ID of the timer.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** - ```js +```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)); - }); - } + async systemTimer () { + let options = { + type: systemTimer.TIMER_TYPE_REALTIME, + repeat:false + } + let timerId = await systemTimer.createTimer(options) + let triggerTime = new Date().getTime() + triggerTime += 3000 + systemTimer.startTimer(timerId, triggerTime) + systemTimer.stopTimer(timerId, (error) => { + if (error) { + console.error(`Failed to stop timer. Cause:` + JSON.stringify(error)); + return; + } + }); + } } - ``` - +``` -## systemTime.stopTimer +## systemTimer.stopTimer stopTimer(timer: number): Promise<void> @@ -218,34 +243,39 @@ Stops a timer. This API uses a promise to return the result. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| timer | number | Yes | ID of the timer. | +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------ | +| timer | number | Yes | ID of the timer.| + +**Return value** + +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise that returns no value.| **Example** - ```js +```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)); - }); - } + async systemTimer (){ + let options = { + type: systemTimer.TIMER_TYPE_REALTIME, + repeat:false + } + let timerId = await systemTimer.createTimer(options) + let triggerTime = new Date().getTime() + triggerTime += 3000 + systemTimer.startTimer(timerId, triggerTime) + systemTimer.stopTimer(timerId).then((data) => { + console.log(`Succeeded in stopping timer. Data:` + JSON.stringify(data)); + }).catch((error) => { + console.error(`Failed to stop timer. Cause:` + JSON.stringify(error)); + }); + } } - ``` - +``` -## systemTime.destroyTimer +## systemTimer.destroyTimer destroyTimer(timer: number, callback: AsyncCallback<void>): void @@ -255,37 +285,36 @@ Destroys a timer. This API uses an asynchronous callback to return the result. **Parameters** -| Name | Type | Mandatory| Description | -| -------- | --------------------------- | ---- | ------------------------------------------------------------ | -| timer | number | Yes | ID of the timer. | +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | ------------ | +| timer | number | Yes | ID of the timer.| +| callback | AsyncCallback<void> | Yes | Callback used to return the result. | **Example** - ```js +```js export default { - systemTimer () { - var options = { + async systemTimer () { + let options = { type: systemTimer.TIMER_TYPE_REALTIME, repeat:false } - let timerId = systemTimer.createTimer(options) - let triggerTime = new Date().getTime() + let timerId = await systemTimer.createTimer(options) + let triggerTime = new Date().getTime() triggerTime += 3000 systemTimer.startTimer(timerId, triggerTime) systemTimer.stopTimer(timerId) - systemTimer.destroyTimer(timerId, (error, data) => { + systemTimer.destroyTimer(timerId, (error) => { if (error) { - console.error(`failed to systemTime.startTimer ` + JSON.stringify(error)); + console.error(`Failed to destroy timer. Cause:` + JSON.stringify(error)); return; } - console.log(`systemTime.startTimer success data : ` + JSON.stringify(data)); }); } } - ``` - +``` -## systemTime.destroyTimer +## systemTimer.destroyTimer destroyTimer(timer: number): Promise<void> @@ -295,43 +324,35 @@ Destroys a timer. This API uses a promise to return the result. **Parameters** -| Name| Type | Mandatory| Description | -| ------ | ------- | ---- | ------------------------------------------------------------ | -| timer | number | Yes | ID of the timer. | +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------ | +| timer | number | Yes | ID of the timer.| + +**Return value** + +| Type | Description | +| -------------- | ------------------------- | +| Promise\ | Promise that returns no value.| **Example** - ```js +```js export default { - systemTimer (){ - var options = { + async systemTimer (){ + let options = { type: systemTimer.TIMER_TYPE_REALTIME, repeat:false } - let timerId = systemTimer.createTimer(options) - let triggerTime = new Date().getTime() + let timerId = await 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)); + systemTimer.destroyTimer(timerId).then((data) => { + console.log(`Succeeded in destroying timer. Data:` + JSON.stringify(data)); }).catch((error) => { - console.error(`failed to systemTime.startTimer because ` + JSON.stringify(error)); + console.error(`Failed to destroy timer. Cause:` + 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. (When the set time is later than the timer startup time, the timer expires.) 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. | +``` -- GitLab