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