README.md
1# Timing and Time
2
3## Introduction
4
5The timing and time module provides APIs for managing the system time.
6
7**Figure 1** Subsystem architecture
8
9
10
11## Directory Structure
12
13```
14/base/time/time_service
15├── etc # Process configuration files
16├── figures # Architecture diagram
17├── framework/js/napi # the js interface resolves to the napi interface
18├── interfaces/inner_api # external interface code provided by the component
19├── services # time service realization
20│ └── sa_profile # module contains the config files of system services and processes
21├── test # unit test of interface
22└── utils # module contains log printing and constants for ordered commonEvent
23```
24
25
26## Usage
27
28### Available JS APIs
29
30**Table 1** Major functions of systemTime
31
32| Interface name | describe |
33| ------------------------------------------------------------ | ------------------------------------------------------------ |
34| setTime(time : number) : Promise<boolean> | Set the system time (1970-01-01 to the present in milliseconds), Promise method. |
35| setTime(time : number, callback : AsyncCallback<boolean>) : void | Set the system time (1970-01-01 to the present in milliseconds), callback mode. |
36| setDate(date: Date, callback: AsyncCallback<boolean>): void; | Set the system time (Date format), Promise method. |
37| setDate(date: Date): Promise<boolean> | Set system time (Date format), callback method. |
38| setTimezone(timezone: string, callback: AsyncCallback<boolean>): void | Set the system time zone, callback method. |
39| setTimezone(timezone: string): Promise<boolean> | Set the system time zone, Promise method. |
40
41**表 2** Major functions of systemTimer
42
43| Interface name | describe |
44| ------------------------------------------------------------ | ------------------------------------- |
45| createTimer(options: TimerOptions, callback: AsyncCallback<number>): void | Create timer, callback method |
46| createTimer(options: TimerOptions): Promise<number> | Create timer, promise method |
47| startTimer(timer: number, triggerTime: number, callback: AsyncCallback<boolean>): void | Start the timer, callback mode |
48| startTimer(timer: number, triggerTime: number): Promise<boolean> | Start the timer, promise mode |
49| stopTimer(timer: number, callback: AsyncCallback<boolean>): void | Stop the timer, callback mode |
50| stopTimer(timer: number): Promise<boolean> | Stop the timer, promise mode |
51| destroyTimer(timer: number, callback: AsyncCallback<boolean>): void | Destroy the timer, callback method |
52| destroyTimer(timer: number): Promise<boolean> | Destroy the timer, the promise method |
53
54**表 3** parameter TimerOptions description of systemTimer
55
56| name | type | illustrate |
57| --------- | --------- | ------------------------------------------------------------ |
58| type | number | Timer type. <br/>If the value is 1, it is represented as the system startup time timer (the timer start time cannot be later than the currently set system time); <br/>If the value is 2, it is indicated as a wake-up timer; <br/>When the value is 4, it is represented as a precision timer; <br/>If the value is 5, it is represented as an IDLE mode timer (not supported). |
59| repeat | boolean | true Is a cyclic timer, false is a single timer. |
60| interval | number | If it is a cyclic timer, the repeat value should be greater than 5000 milliseconds, and the non-repeated timer is set to 0. |
61| wantAgent | wantAgent | Set the wantagent to notify, and notify when the timer expires. |
62| callback | => void | Set the callback function, which will be triggered after the timer expires. |
63
64### Sample Code
65
66Example fo using systemTime
67
68```javascript
69// Import the module.
70import systemTime from '@ohos.systemTime';
71
72// Set the system time asynchronously with a Promise.
73var time = 1611081385000;
74systemTime.setTime(time).then((value) => {
75 console.log(`success to systemTime.setTime: ${value}`);
76}).catch((err) => {
77 console.error(`failed to systemTime.setTime because ${err.message}`)
78});
79
80// Set the system time asynchronously with a callback.
81var time = 1611081385000;
82systemTime.setTime(time, (err, value) => {
83 if (err) {
84 console.error(`failed to systemTime.setTime because ${err.message}`);
85 return;
86 }
87 console.log(`success to systemTime.setTime: ${value}`);
88});
89```
90Example fo using systemTimer
91```javascript
92// Import the module
93import systemTimer from '@ohos.systemTimer';
94
95console.log("start");
96var options:TimerOptions{
97 type:TIMER_TYPE_REALTIME,
98 repeat:false,
99 interval:Number.MAX_VALUE/2,
100 persistent:false
101}
102
103console.log("create timer")
104let timerId = systemTimer.Timer(options)
105console.log("start timer")
106let startTimerRes = systemTimer.startTimer(timerId, 100000)
107console.log("stop timer")
108let stopTimerRes = systemTimer.stopTimer(timerId)
109console.log("destroy timer")
110let destroyTimerRes = systemTimer.destroyTimer(timerId)
111console.log('end');
112```
113
114## Repositories Involved
115
116**Time/Timezone subsystem**
117
118[time\_time\_service](https://gitee.com/openharmony/time_time_service/tree/master/)
119
120
README_zh.md
1# 时间时区部件
2
3## 简介
4
5在整个OpenHarmony架构中提供管理系统时间时区和定时的能力，支持设置定时器和获取时间、时区和日期。
6
7**图 1** 子系统架构图
8
9
10
11## 目录
12
13```
14/base/time/time_service
15├── etc # 组件包含的进程的配置文件
16├── figures # 构架图
17├── framework/js/napi # js接口解析成napi接口
18├── interfaces/inner_api # 组件对外提供的接口代码
19├── services # 时间服务实现
20│ └── sa_profile # 组件包含的系统服务的配置文件和进程的配置文件
21├── test # 接口的单元测试
22└── utils # 组件包含日志打印和有序公共事件定义的常量
23```
24
25## 说明
26
27### js接口说明
28
29> **说明：**
30>
31> - 从API Version 9 开始，模块接口[@ohos.systemTime](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-system-time.md)不再维护，推荐使用新模块接口[@ohos.systemDateTime](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-system-date-time.md)
32
33**表 1** js组件systemDateTime开放的主要方法
34
35| 接口名 | 描述 |
36| ------------------------------------------------------------ | ---------------------------------------------------- |
37| setTime(time : number) : Promise | 设置系统时间（1970-01-01至今毫秒数），Promise方式。 |
38| setTime(time : number, callback : AsyncCallback<boolean>) : void | 设置系统时间（1970-01-01至今毫秒数），callback方式。 |
39| getCurrentTime(isNano?: boolean): Promise<number> | 获取自Unix纪元以来经过的时间，Promise方式。 |
40| getCurrentTime(isNano: boolean, callback: AsyncCallback<number>): void | 获取自Unix纪元以来经过的时间，callback方式。 |
41| getCurrentTime(callback: AsyncCallback<number>): void | 获取自Unix纪元以来经过的时间，callback方式。 |
42| getRealActiveTime(isNano?: boolean): Promise<number> | 获取自系统启动以来经过的时间，不包括深度睡眠时间，Promise方式。 |
43| getRealActiveTime(isNano: boolean, callback: AsyncCallback<number>): void | 获取自系统启动以来经过的时间，不包括深度睡眠时间，callback方式。 |
44| getRealActiveTime(callback: AsyncCallback<number>): void | 获取自系统启动以来经过的时间，不包括深度睡眠时间，callback方式。 |
45| getRealTime(isNano?: boolean): Promise<number> | 获取自系统启动以来经过的时间，包括深度睡眠时间，Promise方式。 |
46| getRealTime(isNano: boolean, callback: AsyncCallback<number>): void | 获取自系统启动以来经过的时间，包括深度睡眠时间，callback方式。 |
47| getRealTime(callback: AsyncCallback<number>): void | 获取自系统启动以来经过的时间，包括深度睡眠时间，callback方式。 |
48| setDate(date: Date, callback: AsyncCallback<boolean>): void; | 设置系统时间（Date格式），Promise方式。 |
49| setDate(date: Date): Promise<boolean> | 设置系统时间（Date格式），callback方式。 |
50| getDate(callback: AsyncCallback<Date>): void | 获取当前系统日期，Promise方式。 |
51| getDate(): Promise<Date> | 获取当前系统日期，callback方式。 |
52| setTimezone(timezone: string, callback: AsyncCallback<boolean>): void | 设置系统时区，callback方式。 |
53| setTimezone(timezone: string): Promise<boolean> | 设置系统时区，Promise方式。 |
54| getTimezone(callback: AsyncCallback<string>): void | 获取系统时区，callback方式。 |
55| getTimezone(): Promise<string> | 获取系统时区，Promise方式。 |
56
57**表 2** js组件systemTimer开放的主要方法
58
59| 接口名 | 描述 |
60| ------------------------------------------------------------ | -------------------------- |
61| createTimer(options: TimerOptions, callback: AsyncCallback<number>): void | 创建定时器，callback方式。 |
62| createTimer(options: TimerOptions): Promise<number> | 创建定时器，promise方式。 |
63| startTimer(timer: number, triggerTime: number, callback: AsyncCallback<boolean>): void | 开启定时器，callback方式。 |
64| startTimer(timer: number, triggerTime: number): Promise<boolean> | 开启定时器，promise方式。 |
65| stopTimer(timer: number, callback: AsyncCallback<boolean>): void | 停止定时器，callback方式。 |
66| stopTimer(timer: number): Promise<boolean> | 停止定时器，promise方式。 |
67| destroyTimer(timer: number, callback: AsyncCallback<boolean>): void | 销毁定时器，callback方式。 |
68| destroyTimer(timer: number): Promise<boolean> | 摧毁定时器，promise方式。 |
69
70**表 3** systemTimer组件参数TimerOptions说明
71
72| 名称 | 类型 | 说明 |
73| --------- | --------- | ------------------------------------------------------------ |
74| type | number | 定时器类型。<br/>取值为1时，表示为系统启动时间定时器（定时器启动时间不能晚于当前设置的系统时间）；<br/>取值为2时，表示为唤醒定时器；<br/>取值为4时，表示为精准定时器；<br/>取值为5时，表示为IDLE模式定时器（暂不支持）。 |
75| repeat | boolean | true 为循环定时器，false为单次定时器。 |
76| interval | number | 如果是循环定时器，repeat值应大于5000毫秒，非重复定时器置为0。 |
77| wantAgent | wantAgent | 设置通知的wantagent，定时器到期后通知。 |
78| callback | => void | 设置回调函数，定时器到期后触发。 |
79
80### js接口使用说明
81
82systemDateTime模块使用示例：
83
84```javascript
85// 导入模块
86import systemDateTime from '@ohos.systemDateTime';
87
88// Promise方式的异步方法设置时间
89// time对应的时间为2021-01-20 02:36:25
90let time = 1611081385000;
91try {
92 systemDateTime.setTime(time).then(() => {
93 console.info(`Succeeded in setting time.`);
94 }).catch((error) => {
95 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`);
96 });
97} catch(e) {
98 console.info(`Failed to set time. message: ${e.message}, code: ${e.code}`);
99}
100
101// callback方式的异步方法设置时间
102// time对应的时间为2021-01-20 02:36:25
103let time = 1611081385000;
104try {
105 systemDateTime.setTime(time, (error) => {
106 if (error) {
107 console.info(`Failed to set time. message: ${error.message}, code: ${error.code}`);
108 return;
109 }
110 console.info(`Succeeded in setting time`);
111 });
112} catch(e) {
113 console.info(`Failed to set time. message: ${e.message}, code: ${e.code}`);
114}
115```
116
117systemTimer模块使用示例：
118
119```javascript
120// 导入模块
121import systemTimer from '@ohos.systemTimer';
122
123console.log("start");
124var options:TimerOptions{
125 type:TIMER_TYPE_REALTIME,
126 repeat:false,
127 interval:Number.MAX_VALUE/2,
128}
129
130console.log("create timer")
131let timerId = systemTimer.Timer(options)
132console.log("start timer")
133let startTimerRes = systemTimer.startTimer(timerId, 100000)
134console.log("stop timer")
135let stopTimerRes = systemTimer.stopTimer(timerId)
136console.log("destroy timer")
137let destroyTimerRes = systemTimer.destroyTimer(timerId)
138console.log('end');
139```
140
141## 相关仓
142
143时间时区子系统
144
145[**time\_time\_service**](https://gitee.com/openharmony/time_time_service/tree/master/)
146
147
