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