1# @ohos.systemDateTime (System Time and Time Zone) (System API) 2<!--Kit: Basic Services Kit--> 3<!--Subsystem: Time--> 4<!--Owner: @huaxin05--> 5<!--Designer: @hu-kai45--> 6<!--Tester: @murphy1984--> 7<!--Adviser: @zhang_yixin13--> 8 9The **systemDateTime** module provides system time and time zone features. You can use the APIs of this module to set and obtain the system time and time zone. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```ts 18import { systemDateTime } from '@kit.BasicServicesKit'; 19``` 20 21## TimeType<sup>10+</sup> 22 23Enumerates the types of time to obtain. 24 25**System capability**: SystemCapability.MiscServices.Time 26 27| Name | Value | Description | 28| ------- | ---- | ------------------------------------------------ | 29| STARTUP | 0 | Number of milliseconds elapsed since system startup, including the deep sleep time. | 30| ACTIVE | 1 | Number of milliseconds elapsed since system startup, excluding the deep sleep time.| 31 32## systemDateTime.setTime 33 34setTime(time : number, callback : AsyncCallback<void>) : void 35 36Sets the system time. This API uses an asynchronous callback to return the result. 37 38**System API**: This is a system API. 39 40**System capability**: SystemCapability.MiscServices.Time 41 42**Required permissions**: ohos.permission.SET_TIME 43 44**Parameters** 45 46| Name | Type | Mandatory| Description | 47| -------- | ----------- | ---- | ---------------- | 48| time | number | Yes | Timestamp to set, in milliseconds. | 49| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 50 51**Error codes** 52 53For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 54 55| ID| Error Message | 56| -------- |-------------------------------------------------------------------------------------------------------------| 57| 201 | Permission denied. | 58| 202 | Permission verification failed. A non-system application calls a system API. | 59| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 60 61**Example** 62 63```ts 64import { BusinessError } from '@kit.BasicServicesKit'; 65 66// Set the system time to 2021-01-20 02:36:25. 67let time = 1611081385000; 68try { 69 systemDateTime.setTime(time, (error: BusinessError) => { 70 if (error) { 71 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 72 return; 73 } 74 console.info(`Succeeded in setting time`); 75 }); 76} catch(e) { 77 let error = e as BusinessError; 78 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 79} 80``` 81 82## systemDateTime.setTime 83 84setTime(time : number) : Promise<void> 85 86Sets the system time. This API uses a promise to return the result. 87 88**System API**: This is a system API. 89 90**System capability**: SystemCapability.MiscServices.Time 91 92**Required permissions**: ohos.permission.SET_TIME 93 94**Parameters** 95 96| Name| Type | Mandatory| Description | 97| ------ | ------ | ---- | ------------------ | 98| time | number | Yes | Timestamp to set, in milliseconds.| 99 100**Return value** 101 102| Type | Description | 103| ------------------- | ------------------------- | 104| Promise<void> | Promise that returns no value.| 105 106**Error codes** 107 108For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 109 110| ID| Error Message | 111| -------- |-------------------------------------------------------------------------------------------------------------| 112| 201 | Permission denied. | 113| 202 | Permission verification failed. A non-system application calls a system API. | 114| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 115 116**Example** 117 118```ts 119import { BusinessError } from '@kit.BasicServicesKit'; 120 121// Set the system time to 2021-01-20 02:36:25. 122let time = 1611081385000; 123try { 124 systemDateTime.setTime(time).then(() => { 125 console.info(`Succeeded in setting time.`); 126 }).catch((error: BusinessError) => { 127 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 128 }); 129} catch(e) { 130 let error = e as BusinessError; 131 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`); 132} 133``` 134 135## systemDateTime.setDate<sup>(deprecated)</sup> 136 137setDate(date: Date, callback: AsyncCallback<void>): void 138 139Sets the system date. This API uses an asynchronous callback to return the result. 140 141> **NOTE** 142> 143> This API is supported since API version 9 and deprecated since API version 10. You are advised to use [systemDateTime.setTime](#systemdatetimesettime) instead. 144 145**System API**: This is a system API. 146 147**System capability**: SystemCapability.MiscServices.Time 148 149**Required permissions**: ohos.permission.SET_TIME 150 151**Parameters** 152 153| Name | Type | Mandatory| Description | 154| -------- | ------------- | ---- |-------------| 155| date | Date | Yes | Target date. The value must be greater than 0.| 156| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 157 158**Error codes** 159 160For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 161 162| ID| Error Message | 163| -------- |----------------------------------------------------------------------------------------------------------------------------------------------| 164| 201 | Permission denied. | 165| 202 | Permission verification failed. A non-system application calls a system API. | 166| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 167 168**Example** 169 170```ts 171import { BusinessError } from '@kit.BasicServicesKit'; 172 173let date = new Date(); 174try { 175 systemDateTime.setDate(date, (error: BusinessError) => { 176 if (error) { 177 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 178 return; 179 } 180 console.info(`Succeeded in setting date.`); 181 }); 182} catch(e) { 183 let error = e as BusinessError; 184 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 185} 186``` 187 188## systemDateTime.setDate<sup>(deprecated)</sup> 189 190setDate(date: Date): Promise<void> 191 192Sets the system date. This API uses a promise to return the result. 193 194> **NOTE** 195> 196> This API is supported since API version 9 and deprecated since API version 10. You are advised to use [systemDateTime.setTime](#systemdatetimesettime) instead. 197 198**System API**: This is a system API. 199 200**System capability**: SystemCapability.MiscServices.Time 201 202**Required permissions**: ohos.permission.SET_TIME 203 204**Parameters** 205 206| Name| Type| Mandatory| Description | 207| ------ | ---- | ---- | ---------- | 208| date | Date | Yes | Target date. The value must be greater than 0.| 209 210**Return value** 211 212| Type | Description | 213| ------------------- | -------------------- | 214| Promise<void> | Promise that returns no value.| 215 216**Error codes** 217 218For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 219 220| ID| Error Message | 221| -------- |----------------------------------------------------------------------------------------------------------------------------------------------| 222| 201 | Permission denied. | 223| 202 | Permission verification failed. A non-system application calls a system API. | 224| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 225 226**Example** 227 228```ts 229import { BusinessError } from '@kit.BasicServicesKit'; 230 231let date = new Date(); 232try { 233 systemDateTime.setDate(date).then(() => { 234 console.info(`Succeeded in setting date.`); 235 }).catch((error: BusinessError) => { 236 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 237 }); 238} catch(e) { 239 let error = e as BusinessError; 240 console.info(`Failed to set date. message: ${error.message}, code: ${error.code}`); 241} 242``` 243 244## systemDateTime.setTimezone 245 246setTimezone(timezone: string, callback: AsyncCallback<void>): void 247 248Sets the system time zone. This API uses an asynchronous callback to return the result. 249 250**System API**: This is a system API. 251 252**System capability**: SystemCapability.MiscServices.Time 253 254**Required permissions**: ohos.permission.SET_TIME_ZONE 255 256**Parameters** 257 258| Name | Type | Mandatory| Description | 259| -------- | ------------- | ---- | -------------------------- | 260| timezone | string | Yes | System time zone to set. For details, see [Supported System Time Zones](#supported-system-time-zones). | 261| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 262 263**Error codes** 264 265For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 266 267| ID| Error Message | 268| -------- |-------------------------------------------------------------------------------------------------------------| 269| 201 | Permission denied. | 270| 202 | Permission verification failed. A non-system application calls a system API. | 271| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 272 273**Example** 274 275```ts 276import { BusinessError } from '@kit.BasicServicesKit'; 277 278try { 279 systemDateTime.setTimezone('Asia/Shanghai', (error: BusinessError) => { 280 if (error) { 281 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 282 return; 283 } 284 console.info(`Succeeded in setting timezone.`); 285 }); 286} catch(e) { 287 let error = e as BusinessError; 288 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 289} 290``` 291 292## systemDateTime.setTimezone 293 294setTimezone(timezone: string): Promise<void> 295 296Sets the system time zone. This API uses a promise to return the result. 297 298**System API**: This is a system API. 299 300**System capability**: SystemCapability.MiscServices.Time 301 302**Required permissions**: ohos.permission.SET_TIME_ZONE 303 304**Parameters** 305 306| Name | Type | Mandatory| Description | 307| -------- | ------ | ---- | ---------- | 308| timezone | string | Yes | System time zone to set. For details, see [Supported System Time Zones](#supported-system-time-zones).| 309 310**Return value** 311 312| Type | Description | 313| ------------------- | -------------------- | 314| Promise<void> | Promise that returns no value.| 315 316**Error codes** 317 318For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 319 320| ID| Error Message | 321| -------- |-------------------------------------------------------------------------------------------------------------| 322| 201 | Permission denied. | 323| 202 | Permission verification failed. A non-system application calls a system API. | 324| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 325 326**Example** 327 328```ts 329import { BusinessError } from '@kit.BasicServicesKit'; 330 331try { 332 systemDateTime.setTimezone('Asia/Shanghai').then(() => { 333 console.info(`Succeeded in setting timezone.`); 334 }).catch((error: BusinessError) => { 335 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 336 }); 337} catch(e) { 338 let error = e as BusinessError; 339 console.info(`Failed to set timezone. message: ${error.message}, code: ${error.code}`); 340} 341``` 342 343## systemDateTime.updateNtpTime<sup>14+</sup> 344 345updateNtpTime(): Promise<void> 346 347Updates the NTP time from the NTP server This API returns the result asynchronously. In this way, the NTP time is updated from the NTP server only once within one hour. 348 349**System API**: This is a system API. 350 351**System capability**: SystemCapability.MiscServices.Time 352 353**Return value** 354 355| Type | Description | 356| ------------------- | -------------------- | 357| Promise<void> | Promise that returns no value.| 358 359**Error codes** 360 361For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md) and [Universal Error Codes](../errorcode-universal.md). 362 363| ID| Error Message | 364|-------|-------------------------------------------------------------------------------------------------------------| 365| 13000001 | Network connection error or OS error. | 366| 202 | Permission verification failed. A non-system application calls a system API. | 367 368**Example** 369 370```ts 371import { BusinessError } from '@kit.BasicServicesKit'; 372 373try { 374 systemDateTime.updateNtpTime().then(() => { 375 console.info(`Succeeded in update ntp time.`); 376 }).catch((error: BusinessError) => { 377 console.error(`Failed to update ntp time. message: ${error.message}, code: ${error.code}`); 378 }); 379} catch(e) { 380 let error = e as BusinessError; 381 console.error(`Failed to update ntp time. message: ${error.message}, code: ${error.code}`); 382} 383``` 384 385## systemDateTime.getNtpTime<sup>14+</sup> 386 387getNtpTime(): number 388 389Obtains the actual time calculated based on the last updated NTP time. This API returns the result synchronously. 390 391**System API**: This is a system API. 392 393**System capability**: SystemCapability.MiscServices.Time 394 395**Return value** 396 397| Type | Description | 398| ------ |--------------------------------| 399| number | Unix epoch time (ms) calculated based on the last updated NTP time.| 400 401**Error codes** 402 403For details about the error codes, see [Time and Time Zone Service Error Codes](./errorcode-time.md) and [Universal Error Codes](../errorcode-universal.md). 404 405| ID| Error Message | 406|-------|-------------------------------------------------------------------------------------------------------------| 407| 13000002 | Location NTP time of the system is invalid. | 408| 202 | Permission verification failed. A non-system application calls a system API. | 409 410**Example** 411 412```ts 413import { BusinessError } from '@kit.BasicServicesKit'; 414 415try { 416 let time = systemDateTime.getNtpTime(); 417} catch(e) { 418 let error = e as BusinessError; 419 console.error(`Failed to get ntp time. message: ${error.message}, code: ${error.code}`); 420} 421``` 422 423## Supported System Time Zones 424 425For details about the supported system time zones, see API [I18n.SystemLocaleManager.getTimeZoneCityItemArray()](../apis-localization-kit/js-apis-i18n-sys.md#gettimezonecityitemarray10). 426