1/* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit BasicServicesKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22import { WantAgent } from './@ohos.app.ability.wantAgent'; 23 24/** 25 * Provides js api for systemTimer 26 * 27 * @namespace systemTimer 28 * @syscap SystemCapability.MiscServices.Time 29 * @systemapi Hide this for inner system use. 30 * @since 7 31 */ 32declare namespace systemTimer { 33 /** 34 * Indicates the timing policy the timer use, which can be REALTIME or UTC. 35 * 36 * 37 * @syscap SystemCapability.MiscServices.Time 38 * @systemapi Hide this for inner system use. 39 * @since 7 40 */ 41 const TIMER_TYPE_REALTIME: number; 42 43 /** 44 * Describes whether a timer will wake the device up. 45 * 46 * 47 * @syscap SystemCapability.MiscServices.Time 48 * @systemapi Hide this for inner system use. 49 * @since 7 50 */ 51 const TIMER_TYPE_WAKEUP: number; 52 53 /** 54 * Describes whether a timer will be delivered precisely at a scheduled time. 55 * 56 * 57 * @syscap SystemCapability.MiscServices.Time 58 * @systemapi Hide this for inner system use. 59 * @since 7 60 */ 61 const TIMER_TYPE_EXACT: number; 62 63 /** 64 * Indicates whether the timer waking up the system is supported in low-power mode. 65 * 66 * 67 * @syscap SystemCapability.MiscServices.Time 68 * @systemapi Hide this for inner system use. 69 * @since 7 70 */ 71 const TIMER_TYPE_IDLE: number; 72 73 /** 74 * Creates a timer. 75 * 76 * @param { TimerOptions } options - The timer options. 77 * @param { AsyncCallback<number> } callback - {number} is the timer ID. 78 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 79 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 80 * 3.Parameter verification failed. 81 * @syscap SystemCapability.MiscServices.Time 82 * @systemapi Hide this for inner system use. 83 * @since 7 84 */ 85 function createTimer(options: TimerOptions, callback: AsyncCallback<number>): void; 86 87 /** 88 * Creates a timer. 89 * 90 * @param { TimerOptions } options - The timer options. 91 * @returns { Promise<number> } the timer ID. 92 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 93 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 94 * 3.Parameter verification failed. 95 * @syscap SystemCapability.MiscServices.Time 96 * @systemapi Hide this for inner system use. 97 * @since 7 98 */ 99 function createTimer(options: TimerOptions): Promise<number>; 100 101 /** 102 * Starts a timer. 103 * 104 * @param { number } timer - The timer ID. 105 * @param { number } triggerTime - Indicates the time at which the timer is triggered for the first time, in milliseconds. 106 * The time will be automatically set to 5000 milliseconds after the current time if the passed 107 * value is smaller than the current time plus 5000 milliseconds. 108 * @param { AsyncCallback<void> } callback - The callback function. 109 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 110 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 111 * @syscap SystemCapability.MiscServices.Time 112 * @systemapi Hide this for inner system use. 113 * @since 7 114 */ 115 function startTimer(timer: number, triggerTime: number, callback: AsyncCallback<void>): void; 116 117 /** 118 * Starts a timer. 119 * 120 * @param { number } timer - The timer ID. 121 * @param { number } triggerTime - Indicates the time at which the timer is triggered for the first time, in milliseconds. 122 * The time will be automatically set to 5000 milliseconds after the current time if the passed 123 * value is smaller than the current time plus 5000 milliseconds. 124 * @returns { Promise<void> } return a promise object. 125 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 126 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 127 * @syscap SystemCapability.MiscServices.Time 128 * @systemapi Hide this for inner system use. 129 * @since 7 130 */ 131 function startTimer(timer: number, triggerTime: number): Promise<void>; 132 133 /** 134 * Stops a timer. 135 * 136 * @param { number } timer - The timer ID. 137 * @param { AsyncCallback<void> } callback - The callback function. 138 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 139 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 140 * @syscap SystemCapability.MiscServices.Time 141 * @systemapi Hide this for inner system use. 142 * @since 7 143 */ 144 function stopTimer(timer: number, callback: AsyncCallback<void>): void; 145 146 /** 147 * Stops a timer. 148 * 149 * @param { number } timer - The timer ID. 150 * @returns { Promise<void> } return a promise object. 151 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 152 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 153 * @syscap SystemCapability.MiscServices.Time 154 * @systemapi Hide this for inner system use. 155 * @since 7 156 */ 157 function stopTimer(timer: number): Promise<void>; 158 159 /** 160 * Destroy a timer. 161 * 162 * @param { number } timer - The timer ID. 163 * @param { AsyncCallback<void> } callback - The callback function. 164 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 165 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 166 * @syscap SystemCapability.MiscServices.Time 167 * @systemapi Hide this for inner system use. 168 * @since 7 169 */ 170 function destroyTimer(timer: number, callback: AsyncCallback<void>): void; 171 172 /** 173 * Destroy a timer. 174 * 175 * @param { number } timer - The timer ID. 176 * @returns { Promise<void> } return a promise object. 177 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 178 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. 179 * @syscap SystemCapability.MiscServices.Time 180 * @systemapi Hide this for inner system use. 181 * @since 7 182 */ 183 function destroyTimer(timer: number): Promise<void>; 184 185 /** 186 * When the repeat is false,the interval is not needed, choose one of wantAgent and callback. 187 * When the repeat is true,the interval is required, the wantAgent is required, and the callback can be left blank. 188 * 189 * @interface TimerOptions 190 * @syscap SystemCapability.MiscServices.Time 191 * @systemapi Hide this for inner system use. 192 * @since 7 193 */ 194 interface TimerOptions { 195 /** 196 * The timer type. 197 * 198 * @type { number } 199 * @syscap SystemCapability.MiscServices.Time 200 * @systemapi Hide this for inner system use. 201 * @since 7 202 */ 203 type: number; 204 205 /** 206 * Indicates a repeating timer 207 * 208 * @type { boolean } 209 * @syscap SystemCapability.MiscServices.Time 210 * @systemapi Hide this for inner system use. 211 * @since 7 212 */ 213 repeat: boolean; 214 215 /** 216 * Indicates the interval between two consecutive triggers, in milliseconds. 217 * The interval will be set to 5000 milliseconds automatically if the passed value is smaller than 5000. 218 * 219 * @type { ?number } 220 * @syscap SystemCapability.MiscServices.Time 221 * @systemapi Hide this for inner system use. 222 * @since 7 223 */ 224 interval?: number; 225 226 /** 227 * Indicates the intent to send when the timer goes off. 228 * 229 * @type { ?WantAgent } 230 * @syscap SystemCapability.MiscServices.Time 231 * @systemapi Hide this for inner system use. 232 * @since 7 233 */ 234 wantAgent?: WantAgent; 235 236 /** 237 * Called back when the timer goes off. 238 * 239 * @type { ?function } 240 * @syscap SystemCapability.MiscServices.Time 241 * @systemapi Hide this for inner system use. 242 * @since 7 243 */ 244 callback?: () => void; 245 246 /** 247 * Indicates whether the timer is restored after the system restarts. 248 * True indicates the timer is restored, and false indicates the timer is not restored. 249 * The default value is false. 250 * 251 * @type { ?boolean } 252 * @syscap SystemCapability.MiscServices.Time 253 * @systemapi 254 * @since 15 255 */ 256 autoRestore?: boolean; 257 258 /** 259 * Indicates the name of the timer. 260 * The default value is empty string. 261 * The length of the name cannot be longer than 64 bytes, and the name can not be set the same name as other timers under the same UID. 262 * 263 * @type { ?string } 264 * @syscap SystemCapability.MiscServices.Time 265 * @systemapi 266 * @since 15 267 */ 268 name?: string; 269 } 270} 271 272export default systemTimer;