1# @ohos.systemTimer (System Timer) (System API) 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```ts 14import { systemTimer } from '@kit.BasicServicesKit'; 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. (If the wakeup type is not set, the system does not wake up until it exits the sleep state.)| 27| TIMER_TYPE_EXACT | number | 4 | Exact type. (If the system time is changed, the offset may be 1s at most.) | 28| TIMER_TYPE_IDLE | number | 8 | Idle timer type (supported only for system services, but not applications) | 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 types. Use pipe (\|) symbol to combine two or more types.<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. (If an application is frozen, the timer is also frozen. In addition, the timer is controlled by a unified heartbeat. Therefore, even a timer of the exact type cannot be triggered at specified time.)<br>**8**: idle timer type (supported only for system services, but not applications). | 39| repeat | boolean | Yes | Whether the timer is a repeating timer.<br>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.<br>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.<br>For a one-shot timer, the value is **0**. | 41| 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.) | 42| callback | void | No | Callback to be executed by the user. | 43 44 45## systemTimer.createTimer 46 47createTimer(options: TimerOptions, callback: AsyncCallback<number>): void 48 49Creates a timer. This API uses an asynchronous callback to return the result. 50 51**NOTE**<br>This function must be used together with [systemTimer.destroyTimer](#systemtimerdestroytimer). Otherwise, memory leakage occurs. 52 53**System capability**: SystemCapability.MiscServices.Time 54 55**Parameters** 56 57| Name | Type | Mandatory| Description | 58| -------- | ----------------------------- | ---- | ------------------------------------------------------------ | 59| options | [TimerOptions](#timeroptions) | Yes | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and **WantAgent** options.| 60| callback | AsyncCallback<number> | Yes | Callback used to return the timer ID. | 61 62**Error codes** 63 64For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 65 66| ID| Error Message | 67|-------|----------------------------------------------------------------------------------------------------------------------------------------------| 68| 202 | Permission verification failed. A non-system application calls a system API. | 69| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 70 71**Example** 72 73```ts 74import { BusinessError } from '@kit.BasicServicesKit'; 75 76let options: systemTimer.TimerOptions = { 77 type: systemTimer.TIMER_TYPE_REALTIME, 78 repeat: false 79}; 80try { 81 systemTimer.createTimer(options, (error: BusinessError, timerId: Number) => { 82 if (error) { 83 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 84 return; 85 } 86 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 87 }); 88} catch(e) { 89 let error = e as BusinessError; 90 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 91} 92``` 93 94## systemTimer.createTimer 95 96createTimer(options: TimerOptions): Promise<number> 97 98Creates a timer. This API uses a promise to return the result. 99 100**NOTE**<br>This function must be used together with [systemTimer.destroyTimer](#systemtimerdestroytimer). Otherwise, memory leakage occurs. 101 102**System capability**: SystemCapability.MiscServices.Time 103 104**Parameters** 105 106| Name | Type | Mandatory| Description | 107| ------- | ----------------------------- | ---- | ------------------------------------------------------------ | 108| options | [TimerOptions](#timeroptions) | Yes | Timer initialization options, including the timer type, whether the timer is a repeating timer, interval, and **WantAgent** options.| 109 110**Return value** 111 112| Type | Description | 113| --------------------- | ----------------------------- | 114| Promise<number> | Promise used to return the timer ID.| 115 116**Error codes** 117 118For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 119 120| ID| Error Message | 121|-------|-------------------------------------------------------------------------------------------------------------| 122| 202 | Permission verification failed. A non-system application calls a system API. | 123| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 124 125**Example** 126 127```ts 128import { BusinessError } from '@kit.BasicServicesKit'; 129 130let options: systemTimer.TimerOptions = { 131 type: systemTimer.TIMER_TYPE_REALTIME, 132 repeat:false 133}; 134try { 135 systemTimer.createTimer(options).then((timerId: Number) => { 136 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 137 }).catch((error: BusinessError) => { 138 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 139 }); 140} catch(e) { 141 let error = e as BusinessError; 142 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 143} 144``` 145 146## systemTimer.startTimer 147 148startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void 149 150Starts a timer. This API uses an asynchronous callback to return the result. 151 152**System capability**: SystemCapability.MiscServices.Time 153 154**Parameters** 155 156| Name | Type | Mandatory| Description | 157| ----------- | ---------------------- | ---- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 158| timer | number | Yes | ID of the timer. | 159| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds.<br>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)](js-apis-date-time.md#systemdatetimegetuptime10).<br>If **TIMER_TYPE_REALTIME** is not set, the value of **triggerTime** is the wall time, which can be obtained by calling [systemDateTime.getTime()](js-apis-date-time.md#systemdatetimegettime10).| 160| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 161 162**Error codes** 163 164For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 165 166| ID| Error Message | 167|-------|-------------------------------------------------------------------------------------------------------------| 168| 202 | Permission verification failed. A non-system application calls a system API. | 169| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 170 171**Example** 172 173```ts 174import { BusinessError } from '@kit.BasicServicesKit'; 175 176let options: systemTimer.TimerOptions = { 177 type: systemTimer.TIMER_TYPE_REALTIME, 178 repeat:false 179} 180let triggerTime = new Date().getTime(); 181triggerTime += 3000; 182 183try { 184 systemTimer.createTimer(options).then((timerId: number) => { 185 systemTimer.startTimer(timerId, triggerTime, (error: BusinessError) => { 186 if (error) { 187 console.info(`Failed to start the timer. Message: ${error.message}, code: ${error.code}`); 188 return; 189 } 190 console.info(`Succeeded in starting the timer.`); 191 }); 192 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 193 }).catch((error: BusinessError) => { 194 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 195 }); 196} catch(e) { 197 let error = e as BusinessError; 198 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 199} 200``` 201 202## systemTimer.startTimer 203 204startTimer(timer: number, triggerTime: number): Promise<void> 205 206Starts a timer. This API uses a promise to return the result. 207 208**System capability**: SystemCapability.MiscServices.Time 209 210**Parameters** 211 212| Name | Type | Mandatory| Description | 213| ----------- | ------ | ---- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 214| timer | number | Yes | ID of the timer. | 215| triggerTime | number | Yes | Time when the timer is triggered, in milliseconds.<br>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)](js-apis-date-time.md#systemdatetimegetuptime10).<br>If **TIMER_TYPE_REALTIME** is not set, the value of **triggerTime** is the wall time, which can be obtained by calling [systemDateTime.getTime()](js-apis-date-time.md#systemdatetimegettime10).| 216 217**Return value** 218 219| Type | Description | 220| -------------- | ------------------------- | 221| Promise\<void> | Promise that returns no value.| 222 223**Error codes** 224 225For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 226 227| ID| Error Message | 228|-------|-------------------------------------------------------------------------------------------------------------| 229| 202 | Permission verification failed. A non-system application calls a system API. | 230| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 231 232**Example** 233 234```ts 235import { BusinessError } from '@kit.BasicServicesKit'; 236 237let options: systemTimer.TimerOptions = { 238 type: systemTimer.TIMER_TYPE_REALTIME, 239 repeat:false 240} 241let triggerTime = new Date().getTime(); 242triggerTime += 3000; 243 244try { 245 systemTimer.createTimer(options).then((timerId: number) => { 246 systemTimer.startTimer(timerId, triggerTime).then(() => { 247 console.info(`Succeeded in starting the timer.`); 248 }).catch((error: BusinessError) => { 249 console.info(`Failed to start the timer. Message: ${error.message}, code: ${error.code}`); 250 }); 251 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 252 }).catch((error: BusinessError) => { 253 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 254 }); 255} catch(e) { 256 let error = e as BusinessError; 257 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 258} 259``` 260 261## systemTimer.stopTimer 262 263stopTimer(timer: number, callback: AsyncCallback<void>): void 264 265Stops a timer. This API uses an asynchronous callback to return the result. 266 267**System capability**: SystemCapability.MiscServices.Time 268 269**Parameters** 270 271| Name | Type | Mandatory| Description | 272| -------- | ---------------------- | ---- | ------------ | 273| timer | number | Yes | ID of the timer.| 274| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 275 276**Error codes** 277 278For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 279 280| ID| Error Message | 281|-------|-------------------------------------------------------------------------------------------------------------| 282| 202 | Permission verification failed. A non-system application calls a system API. | 283| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 284 285**Example** 286 287```ts 288import { BusinessError } from '@kit.BasicServicesKit'; 289 290let options: systemTimer.TimerOptions = { 291 type: systemTimer.TIMER_TYPE_REALTIME, 292 repeat:false 293} 294let triggerTime = new Date().getTime(); 295triggerTime += 3000; 296 297try { 298 systemTimer.createTimer(options).then((timerId: number) => { 299 systemTimer.startTimer(timerId, triggerTime); 300 systemTimer.stopTimer(timerId, (error: BusinessError) => { 301 if (error) { 302 console.info(`Failed to stop the timer. Message: ${error.message}, code: ${error.code}`); 303 return; 304 } 305 console.info(`Succeeded in stopping the timer.`); 306 }); 307 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 308 }).catch((error: BusinessError) => { 309 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 310 }); 311} catch(e) { 312 let error = e as BusinessError; 313 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 314} 315``` 316 317## systemTimer.stopTimer 318 319stopTimer(timer: number): Promise<void> 320 321Stops a timer. This API uses a promise to return the result. 322 323**System capability**: SystemCapability.MiscServices.Time 324 325**Parameters** 326 327| Name| Type | Mandatory| Description | 328| ------ | ------ | ---- | ------------ | 329| timer | number | Yes | ID of the timer.| 330 331**Return value** 332 333| Type | Description | 334| -------------- | ------------------------- | 335| Promise\<void> | Promise that returns no value.| 336 337**Error codes** 338 339For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 340 341| ID| Error Message | 342|-------|-------------------------------------------------------------------------------------------------------------| 343| 202 | Permission verification failed. A non-system application calls a system API. | 344| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 345 346**Example** 347 348```ts 349import { BusinessError } from '@kit.BasicServicesKit'; 350 351let options: systemTimer.TimerOptions = { 352 type: systemTimer.TIMER_TYPE_REALTIME, 353 repeat:false 354} 355let triggerTime = new Date().getTime(); 356triggerTime += 3000; 357 358try { 359 systemTimer.createTimer(options).then((timerId: number) => { 360 systemTimer.startTimer(timerId, triggerTime); 361 systemTimer.stopTimer(timerId).then(() => { 362 console.info(`Succeeded in stopping the timer.`); 363 }).catch((error: BusinessError) => { 364 console.info(`Failed to stop the timer. Message: ${error.message}, code: ${error.code}`); 365 }); 366 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 367 }).catch((error: BusinessError) => { 368 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 369 }); 370} catch(e) { 371 let error = e as BusinessError; 372 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 373} 374``` 375 376## systemTimer.destroyTimer 377 378destroyTimer(timer: number, callback: AsyncCallback<void>): void 379 380Destroys a timer. This API uses an asynchronous callback to return the result. 381 382**System capability**: SystemCapability.MiscServices.Time 383 384**Parameters** 385 386| Name | Type | Mandatory| Description | 387| -------- | ---------------------- | ---- | ------------ | 388| timer | number | Yes | ID of the timer.| 389| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 390 391**Error codes** 392 393For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 394 395| ID| Error Message | 396|-------|-------------------------------------------------------------------------------------------------------------| 397| 202 | Permission verification failed. A non-system application calls a system API. | 398| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 399 400**Example** 401 402```ts 403import { BusinessError } from '@kit.BasicServicesKit'; 404 405let options: systemTimer.TimerOptions = { 406 type: systemTimer.TIMER_TYPE_REALTIME, 407 repeat:false 408} 409let triggerTime = new Date().getTime(); 410triggerTime += 3000; 411 412try { 413 systemTimer.createTimer(options).then((timerId: number) => { 414 systemTimer.startTimer(timerId, triggerTime); 415 systemTimer.stopTimer(timerId); 416 systemTimer.destroyTimer(timerId, (error: BusinessError) => { 417 if (error) { 418 console.info(`Failed to destroy the timer. Message: ${error.message}, code: ${error.code}`); 419 return; 420 } 421 console.info(`Succeeded in destroying the timer.`); 422 }); 423 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 424 }).catch((error: BusinessError) => { 425 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 426 }); 427} catch(e) { 428 let error = e as BusinessError; 429 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 430} 431``` 432 433## systemTimer.destroyTimer 434 435destroyTimer(timer: number): Promise<void> 436 437Destroys a timer. This API uses a promise to return the result. 438 439**System capability**: SystemCapability.MiscServices.Time 440 441**Parameters** 442 443| Name| Type | Mandatory| Description | 444| ------ | ------ | ---- | ------------ | 445| timer | number | Yes | ID of the timer.| 446 447**Return value** 448 449| Type | Description | 450| -------------- | ------------------------- | 451| Promise\<void> | Promise that returns no value.| 452 453**Error codes** 454 455For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md). 456 457| ID| Error Message | 458|-------|-------------------------------------------------------------------------------------------------------------| 459| 202 | Permission verification failed. A non-system application calls a system API. | 460| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 461 462**Example** 463 464```ts 465import { BusinessError } from '@kit.BasicServicesKit'; 466 467let options: systemTimer.TimerOptions = { 468 type: systemTimer.TIMER_TYPE_REALTIME, 469 repeat:false 470} 471let triggerTime = new Date().getTime(); 472triggerTime += 3000; 473 474try { 475 systemTimer.createTimer(options).then((timerId: number) => { 476 systemTimer.startTimer(timerId, triggerTime); 477 systemTimer.stopTimer(timerId); 478 systemTimer.destroyTimer(timerId).then(() => { 479 console.info(`Succeeded in destroying the timer.`); 480 }).catch((error: BusinessError) => { 481 console.info(`Failed to destroy the timer. Message: ${error.message}, code: ${error.code}`); 482 }); 483 console.info(`Succeeded in creating a timer. timerId: ${timerId}`); 484 }).catch((error: BusinessError) => { 485 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 486 }); 487} catch(e) { 488 let error = e as BusinessError; 489 console.info(`Failed to create a timer. Message: ${error.message}, code: ${error.code}`); 490} 491``` 492