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