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
