1/* 2 * Copyright (C) 2022 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'; 22 23/** 24 * System time and timezone. 25 * 26 * @namespace systemDateTime 27 * @syscap SystemCapability.MiscServices.Time 28 * @since 9 29 */ 30/** 31 * System time and timezone. 32 * 33 * @namespace systemDateTime 34 * @syscap SystemCapability.MiscServices.Time 35 * @crossplatform 36 * @since arkts {'1.1':'18', '1.2':'20'} 37 * @arkts 1.1&1.2 38 */ 39declare namespace systemDateTime { 40 /** 41 * Sets the system time. 42 * 43 * @permission ohos.permission.SET_TIME 44 * @param { number } time - Indicates the target timestamp(in milliseconds) 45 * @param { AsyncCallback<void> } callback - The callback of setTime 46 * @throws { BusinessError } 201 - Permission denied 47 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 48 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 49 * @syscap SystemCapability.MiscServices.Time 50 * @systemapi Hide this for inner system use 51 * @since 9 52 */ 53 function setTime(time: number, callback: AsyncCallback<void>): void; 54 /** 55 * Sets the system time. 56 * 57 * @permission ohos.permission.SET_TIME 58 * @param { number } time - Indicates the target timestamp(in milliseconds) 59 * @returns { Promise<void> } The promise returned by the function 60 * @throws { BusinessError } 201 - Permission denied 61 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 62 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 63 * @syscap SystemCapability.MiscServices.Time 64 * @systemapi Hide this for inner system use 65 * @since 9 66 */ 67 function setTime(time: number): Promise<void>; 68 69 /** 70 * Obtains the number of milliseconds that have elapsed since the Unix epoch. 71 * 72 * @param { boolean } isNano - True if the result is in nanoseconds, otherwise in milliseconds 73 * @param { AsyncCallback<number> } callback - The callback of getCurrentTime 74 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 75 * @syscap SystemCapability.MiscServices.Time 76 * @since 9 77 * @deprecated since 12 78 * @useinstead systemDateTime.getTime 79 */ 80 function getCurrentTime(isNano: boolean, callback: AsyncCallback<number>): void; 81 82 /** 83 * Obtains the number of milliseconds that have elapsed since the Unix epoch. 84 * 85 * @param { AsyncCallback<number> } callback - The callback of getCurrentTime 86 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 87 * @syscap SystemCapability.MiscServices.Time 88 * @since 9 89 * @deprecated since 12 90 * @useinstead systemDateTime.getTime 91 */ 92 function getCurrentTime(callback: AsyncCallback<number>): void; 93 94 /** 95 * Obtains the number of milliseconds that have elapsed since the Unix epoch. 96 * 97 * @param { boolean } isNano - True if the result is in nanoseconds, otherwise in milliseconds 98 * @returns { Promise<number> } The promise returned by the function 99 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 100 * @syscap SystemCapability.MiscServices.Time 101 * @since 9 102 * @deprecated since 12 103 * @useinstead systemDateTime.getTime 104 */ 105 function getCurrentTime(isNano?: boolean): Promise<number>; 106 107 /** 108 * Obtains the number of timestamp that have elapsed since the Unix epoch. 109 * 110 * @param { boolean } [ isNanoseconds ] - True if the result is in nanoseconds, otherwise in milliseconds 111 * @returns { number } The timestamp returned of getTime. 112 * @syscap SystemCapability.MiscServices.Time 113 * @since 10 114 */ 115 /** 116 * Obtains the number of timestamp that have elapsed since the Unix epoch. 117 * 118 * @param { boolean } [ isNanoseconds ] - True if the result is in nanoseconds, otherwise in milliseconds 119 * @returns { number } The timestamp returned of getTime. 120 * @syscap SystemCapability.MiscServices.Time 121 * @crossplatform 122 * @since arkts {'1.1':'18', '1.2':'20'} 123 * @arkts 1.1&1.2 124 */ 125 function getTime(isNanoseconds?: boolean): number; 126 127 /** 128 * Obtains the number of milliseconds elapsed since the system was booted, not including deep sleep time. 129 * 130 * @param { boolean } isNano - True if the result is in nanoseconds., otherwise in milliseconds 131 * @param { AsyncCallback<number> } callback - The callback of getRealActiveTime 132 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 133 * @syscap SystemCapability.MiscServices.Time 134 * @since 9 135 * @deprecated since 12 136 * @useinstead systemDateTime.getUptime 137 */ 138 function getRealActiveTime(isNano: boolean, callback: AsyncCallback<number>): void; 139 140 /** 141 * Obtains the number of milliseconds elapsed since the system was booted, not including deep sleep time. 142 * 143 * @param { AsyncCallback<number> } callback - The callback of getRealActiveTime 144 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 145 * @syscap SystemCapability.MiscServices.Time 146 * @since 9 147 * @deprecated since 12 148 * @useinstead systemDateTime.getUptime 149 */ 150 function getRealActiveTime(callback: AsyncCallback<number>): void; 151 152 /** 153 * Obtains the number of milliseconds elapsed since the system was booted, not including deep sleep time. 154 * 155 * @param { boolean } [isNano] - True if the result is in nanoseconds, otherwise in milliseconds 156 * @returns { Promise<number> } The promise returned by the function 157 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 158 * @syscap SystemCapability.MiscServices.Time 159 * @since 9 160 * @deprecated since 12 161 * @useinstead systemDateTime.getUptime 162 */ 163 function getRealActiveTime(isNano?: boolean): Promise<number>; 164 165 /** 166 * Obtains the number of milliseconds elapsed since the system was booted, including deep sleep time. 167 * 168 * @param { boolean } isNano - True if the result is in nanoseconds, otherwise in milliseconds 169 * @param { AsyncCallback<number> } callback - The callback of getRealTime 170 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 171 * @syscap SystemCapability.MiscServices.Time 172 * @since 9 173 * @deprecated since 12 174 * @useinstead systemDateTime.getUptime 175 */ 176 function getRealTime(isNano: boolean, callback: AsyncCallback<number>): void; 177 178 /** 179 * Obtains the number of milliseconds elapsed since the system was booted, including deep sleep time. 180 * 181 * @param { AsyncCallback<number> } callback - The callback of getRealTime 182 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 183 * @syscap SystemCapability.MiscServices.Time 184 * @since 9 185 * @deprecated since 12 186 * @useinstead systemDateTime.getUptime 187 */ 188 function getRealTime(callback: AsyncCallback<number>): void; 189 190 /** 191 * Obtains the number of milliseconds elapsed since the system was booted, including deep sleep time. 192 * 193 * @param { boolean } [isNano] - True if the result is in nanoseconds, otherwise in milliseconds 194 * @returns { Promise<number> } The promise returned by the function 195 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Incorrect parameter types; 196 * @syscap SystemCapability.MiscServices.Time 197 * @since 9 198 * @deprecated since 12 199 * @useinstead systemDateTime.getUptime 200 */ 201 function getRealTime(isNano?: boolean): Promise<number>; 202 203 /** 204 * Indicates time type. 205 * 206 * @enum { number } TimeType 207 * @syscap SystemCapability.MiscServices.Time 208 * @since 10 209 */ 210 /** 211 * Indicates time type. 212 * 213 * @enum { number } TimeType 214 * @syscap SystemCapability.MiscServices.Time 215 * @crossplatform 216 * @since 18 217 */ 218 enum TimeType { 219 /** 220 * Indicates the time elapsed since the system was booted, including deep sleep time. 221 * 222 * @syscap SystemCapability.MiscServices.Time 223 * @since 10 224 */ 225 /** 226 * Indicates the time elapsed since the system was booted, including deep sleep time. 227 * 228 * @syscap SystemCapability.MiscServices.Time 229 * @crossplatform 230 * @since 18 231 */ 232 STARTUP, 233 234 /** 235 * Indicates the time elapsed since the system was booted, not including deep sleep time. 236 * 237 * @syscap SystemCapability.MiscServices.Time 238 * @since 10 239 */ 240 /** 241 * Indicates the time elapsed since the system was booted, not including deep sleep time. 242 * 243 * @syscap SystemCapability.MiscServices.Time 244 * @crossplatform 245 * @since 18 246 */ 247 ACTIVE 248 } 249 250 /** 251 * Obtains the number of milliseconds since the system has been running. 252 * 253 * @param { TimeType } timeType - indicates the type of get uptime. It can only be `STARTUP` or `ACTIVE`. 254 * @param { boolean } [ isNanoseconds ] - True if the result is in nanoseconds, otherwise in milliseconds 255 * @returns { number } The timestamp returned of getUpTime. 256 * @syscap SystemCapability.MiscServices.Time 257 * @since 10 258 */ 259 /** 260 * Obtains the number of milliseconds since the system has been running. 261 * 262 * @param { TimeType } timeType - indicates the type of get uptime. It can only be `STARTUP` or `ACTIVE`. 263 * @param { boolean } [ isNanoseconds ] - True if the result is in nanoseconds, otherwise in milliseconds 264 * @returns { number } The timestamp returned of getUpTime. 265 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 266 * 3. Parameter verification failed. This error code was added due to missing issues. 267 * @syscap SystemCapability.MiscServices.Time 268 * @since 12 269 */ 270 /** 271 * Obtains the number of milliseconds since the system has been running. 272 * 273 * @param { TimeType } timeType - indicates the type of get uptime. It can only be `STARTUP` or `ACTIVE`. 274 * @param { boolean } [ isNanoseconds ] - True if the result is in nanoseconds, otherwise in milliseconds 275 * @returns { number } The timestamp returned of getUpTime. 276 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 277 * 3. Parameter verification failed. This error code was added due to missing issues. 278 * @syscap SystemCapability.MiscServices.Time 279 * @crossplatform 280 * @since 18 281 */ 282 function getUptime(timeType: TimeType, isNanoseconds?: boolean): number; 283 284 /** 285 * Sets the system time. 286 * 287 * @permission ohos.permission.SET_TIME 288 * @param { Date } date - The target date, it must > 0 289 * @param { AsyncCallback<void> } callback - The callback of setDate 290 * @throws { BusinessError } 201 - Permission denied 291 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 292 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 293 * 3.Parameter verification failed; 294 * @syscap SystemCapability.MiscServices.Time 295 * @systemapi Hide this for inner system use 296 * @since 9 297 * @deprecated since 10 298 * @useinstead systemDateTime.setTime 299 */ 300 function setDate(date: Date, callback: AsyncCallback<void>): void; 301 302 /** 303 * Sets the system time. 304 * 305 * @permission ohos.permission.SET_TIME 306 * @param { Date } date - The target date, it must > 0 307 * @returns { Promise<void> } The promise returned by the function 308 * @throws { BusinessError } 201 - Permission denied 309 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 310 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 311 * 3.Parameter verification failed; 312 * @syscap SystemCapability.MiscServices.Time 313 * @systemapi Hide this for inner system use 314 * @since 9 315 * @deprecated since 10 316 * @useinstead systemDateTime.setTime 317 */ 318 function setDate(date: Date): Promise<void>; 319 320 /** 321 * Obtains the system date. 322 * 323 * @param { AsyncCallback<Date> } callback - The callback of getDate 324 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.System error; 325 * @syscap SystemCapability.MiscServices.Time 326 * @since 9 327 * @deprecated since 10 328 * @useinstead new Date() 329 */ 330 function getDate(callback: AsyncCallback<Date>): void; 331 332 /** 333 * Obtains the system date. 334 * 335 * @returns { Promise<Date> } The promise returned by the function 336 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.System error; 337 * @syscap SystemCapability.MiscServices.Time 338 * @since 9 339 * @deprecated since 10 340 * @useinstead new Date() 341 */ 342 function getDate(): Promise<Date>; 343 344 /** 345 * Sets the system time zone. 346 * 347 * @permission ohos.permission.SET_TIME_ZONE 348 * @param { string } timezone - The system time zone 349 * @param { AsyncCallback<void> } callback - The callback of setTimezone 350 * @throws { BusinessError } 201 - Permission denied 351 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 352 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 353 * @syscap SystemCapability.MiscServices.Time 354 * @systemapi Hide this for inner system use 355 * @since 9 356 */ 357 function setTimezone(timezone: string, callback: AsyncCallback<void>): void; 358 359 /** 360 * Sets the system time zone. 361 * 362 * @permission ohos.permission.SET_TIME_ZONE 363 * @param { string } timezone - The system time zone 364 * @returns { Promise<void> } The promise returned by the function 365 * @throws { BusinessError } 201 - Permission denied 366 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 367 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 368 * @syscap SystemCapability.MiscServices.Time 369 * @systemapi Hide this for inner system use 370 * @since 9 371 */ 372 function setTimezone(timezone: string): Promise<void>; 373 374 /** 375 * Obtains the system time zone. 376 * 377 * @param { AsyncCallback<string> } callback - The callback of getTimezone 378 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.System error. 379 * @syscap SystemCapability.MiscServices.Time 380 * @since 9 381 */ 382 /** 383 * Obtains the system time zone. 384 * 385 * @param { AsyncCallback<string> } callback - The callback of getTimezone 386 * @syscap SystemCapability.MiscServices.Time 387 * @since 12 388 */ 389 /** 390 * Obtains the system time zone. 391 * 392 * @param { AsyncCallback<string> } callback - The callback of getTimezone 393 * @syscap SystemCapability.MiscServices.Time 394 * @crossplatform 395 * @since arkts {'1.1':'18', '1.2':'20'} 396 * @arkts 1.1&1.2 397 */ 398 function getTimezone(callback: AsyncCallback<string>): void; 399 400 /** 401 * Obtains the system time zone. 402 * 403 * @returns { Promise<string> } The promise returned by the function 404 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1.System error. 405 * @syscap SystemCapability.MiscServices.Time 406 * @since 9 407 */ 408 /** 409 * Obtains the system time zone. 410 * 411 * @returns { Promise<string> } The promise returned by the function 412 * @syscap SystemCapability.MiscServices.Time 413 * @since 12 414 */ 415 /** 416 * Obtains the system time zone. 417 * 418 * @returns { Promise<string> } The promise returned by the function 419 * @syscap SystemCapability.MiscServices.Time 420 * @crossplatform 421 * @since arkts {'1.1':'18', '1.2':'20'} 422 * @arkts 1.1&1.2 423 */ 424 function getTimezone(): Promise<string>; 425 426 /** 427 * Obtains the system time zone. 428 * 429 * @returns { string } The timezone returned of getTimezoneSync. 430 * @syscap SystemCapability.MiscServices.Time 431 * @since 10 432 */ 433 /** 434 * Obtains the system time zone. 435 * 436 * @returns { string } The timezone returned of getTimezoneSync. 437 * @syscap SystemCapability.MiscServices.Time 438 * @crossplatform 439 * @since arkts {'1.1':'18', '1.2':'20'} 440 * @arkts 1.1&1.2 441 */ 442 function getTimezoneSync(): string; 443 444 /** 445 * Updates the NTP time from the ntp server. This method will only update NTP time once within an hour. 446 * 447 * @returns { Promise<void> } The promise returned by the function 448 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 449 * @throws { BusinessError } 13000001 - Network connection error or OS error. 450 * @syscap SystemCapability.MiscServices.Time 451 * @systemapi Hide this for inner system use 452 * @since 14 453 */ 454 function updateNtpTime(): Promise<void>; 455 456 /** 457 * Obtains the current time of milliseconds since the Unix epoch calculated based on the last updated NTP time. 458 * 459 * @returns { number } The current NTP time returned of getNtpTime. 460 * @throws { BusinessError } 202 - Permission verification failed. A non-system application calls a system API. 461 * @throws { BusinessError } 13000002 - updateNtpTime() is not called successfully. 462 * @syscap SystemCapability.MiscServices.Time 463 * @systemapi Hide this for inner system use 464 * @since 14 465 */ 466 function getNtpTime(): number; 467} 468 469export default systemDateTime;