Legrand / Raritan / Server Technology Xerus™ JSON-RPC API
Loading...
Searching...
No Matches
DateTime.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2009 Raritan Inc. All rights reserved.
4 */
5
6#include <Event.idl>
7
8/**
9 * Device Date and Time Configuration
10 */
11module datetime {
12
13 /** Date and time configuration methods
14 *
15 * Example to set timezone (id-based approach): @anchor set-timezone-example
16 *
17 * @code{.py}
18 * zoneinfos = getZoneInfos(False)
19 * cfg = getCfg()
20 * cfg.zoneCfg.id = ... # choose zone id from returned zoneinfos
21 * status = setCfg(cfg)
22 * if status != 0: ... # error handling
23 * @endcode
24 */
25 interface DateTime {
26
27 /** Time zone information (see also ZoneCfg)
28 *
29 * There are two different approaches on how to identify timezones. See the ZoneCfg description.
30 *
31 * For timezones with non-trivial daylight saving time rules #hasDSTInfo is \c false.
32 */
33 structure ZoneInfo {
34 int id; ///< Time zone id
35 string name; ///< Time zone name
36 boolean hasDSTInfo; ///< \c true if the time zone has daylight saving time rules
37 };
38
39 /** Time zone configuration
40 *
41 * There are two approaches on how timezones are identified:
42 * 1. id-based
43 *
44 * - timezone data identified with a numeric non-zero id
45 * - #id != 0
46 * - #name is the display name of the timezone and ignored on setCfg()
47 *
48 * 2. name-based (see NOTES below!)
49 *
50 * - timezone data identified with a name from the IANA timezone database (aka Olson database)
51 * - #id == 0
52 * - #name is the official IANA timezone name, e.g. Europe/Berlin or America/New_York
53 *
54 * **NOTES**:
55 * - The user frontends currently only support the id-based approach and may not work correctly with
56 * the name-based approach.
57 * - Setting #enableAutoDST to \c true has only an effect if the according ZoneInfo::hasDSTInfo
58 * field is also \c true.
59 */
60 structure ZoneCfg {
61 int id; ///< Selected time zone id
62 string name; ///< Selected time zone name (ignored on setCfg() if id != 0)
63 boolean enableAutoDST; ///< Enable automatic daylight saving time adjustment
64 };
65
66 /** Time synchronization protocol */
67 enumeration Protocol {
68 STATIC, ///< Device time is configured locally
69 NTP ///< Device time is synchronized via NTP
70 };
71
72 /** Static NTP server configuration */
73 structure NtpCfg {
74 string server1; ///< Primary NTP server
75 string server2; ///< Secondary NTP server
76 };
77
78 /** Device date and time configuration */
79 structure Cfg {
80 ZoneCfg zoneCfg; ///< Time zone configuration
81 Protocol protocol; ///< Time synchronization protocol
82 time deviceTime; ///< Device date and time (local time)
83 NtpCfg ntpCfg; ///< NTP server configuration
84 };
85
86 /** Event that is sent when the configuration changes */
87 valueobject ConfigurationChangedEvent extends idl.Event {
88 };
89
90 /** Event that is sent when the device time is changed */
91 valueobject ClockChangedEvent extends idl.Event {
92 time oldTime; ///< Device time before change (UNIX timestamp, UTC)
93 time newTime; ///< Device time after change (UNIX timestamp, UTC)
94 };
95
96 /**
97 * List all supported time zones.
98 *
99 * @param zoneInfos Result: List of time zones
100 * @param useOlson Use Olson timezone names (see also ZoneCfg)
101 */
102 void getZoneInfos(out vector<ZoneInfo> zoneInfos, in boolean useOlson);
103
104 /**
105 * Check if a specified NTP server is usable.
106 *
107 * @param ntpServer NTP server to be checked
108 *
109 * @return \c true if the NTP server is usable
110 */
111 boolean checkNtpServer(in string ntpServer);
112
113 /**
114 * Get active NTP servers.
115 *
116 * @return List of currently active NTP servers (IP addresses and/or hostnames)
117 */
118 vector<string> getActiveNtpServers();
119
120 /**
121 * Retrieve the device date and time configuration.
122 *
123 * @param cfg Result: Current date and time configration
124 */
125 void getCfg(out Cfg cfg);
126
127 /**
128 * Set the device date and time configuration.
129 * Depending on the value of the \e protocol field either \e deviceTime
130 * or \e ntpCfg will be used from the \e cfg parameter.
131 *
132 * Specific @ref set-timezone-example "example" to set timezone.
133 *
134 * @param cfg New date and time configuration.
135 *
136 * @return 0 if OK
137 * @return 1 if the configuration is invalid
138 */
139 int setCfg(in Cfg cfg);
140
141 /**
142 * Retrieve the current device date and time.
143 *
144 * @param useOlson Use Olson timezone name (see also ZoneCfg)
145 * @param zone Result: Active time zone
146 * @param dstEnabled if false, the time zone daylight saving time flag is not used
147 * @param utcOffset Result: Offset (in minutes) between local time and UTC
148 * @param currentTime Result: Device date and time (UNIX timestamp, UTC)
149 */
150 void getTime(in boolean useOlson, out ZoneInfo zone,
151 out boolean dstEnabled, out int utcOffset,
152 out time currentTime);
153
154 };
155
156}
Date and time configuration methods.
Definition: DateTime.idl:25
int setCfg(in Cfg cfg)
Set the device date and time configuration.
Protocol
Time synchronization protocol.
Definition: DateTime.idl:67
@ STATIC
Device time is configured locally.
Definition: DateTime.idl:68
void getZoneInfos(out vector< ZoneInfo > zoneInfos, in boolean useOlson)
List all supported time zones.
boolean checkNtpServer(in string ntpServer)
Check if a specified NTP server is usable.
vector< string > getActiveNtpServers()
Get active NTP servers.
void getCfg(out Cfg cfg)
Retrieve the device date and time configuration.
void getTime(in boolean useOlson, out ZoneInfo zone, out boolean dstEnabled, out int utcOffset, out time currentTime)
Retrieve the current device date and time.
Device Date and Time Configuration.
Definition: DateTime.idl:11
Basic IDL definitions.
Definition: Event.idl:10
Device date and time configuration.
Definition: DateTime.idl:79
time deviceTime
Device date and time (local time)
Definition: DateTime.idl:82
NtpCfg ntpCfg
NTP server configuration.
Definition: DateTime.idl:83
Protocol protocol
Time synchronization protocol.
Definition: DateTime.idl:81
ZoneCfg zoneCfg
Time zone configuration.
Definition: DateTime.idl:80
Event that is sent when the device time is changed.
Definition: DateTime.idl:91
time oldTime
Device time before change (UNIX timestamp, UTC)
Definition: DateTime.idl:92
time newTime
Device time after change (UNIX timestamp, UTC)
Definition: DateTime.idl:93
Event that is sent when the configuration changes.
Definition: DateTime.idl:87
Static NTP server configuration.
Definition: DateTime.idl:73
string server1
Primary NTP server.
Definition: DateTime.idl:74
string server2
Secondary NTP server.
Definition: DateTime.idl:75
Time zone configuration.
Definition: DateTime.idl:60
boolean enableAutoDST
Enable automatic daylight saving time adjustment.
Definition: DateTime.idl:63
int id
Selected time zone id.
Definition: DateTime.idl:61
string name
Selected time zone name (ignored on setCfg() if id != 0)
Definition: DateTime.idl:62
Time zone information (see also ZoneCfg)
Definition: DateTime.idl:33
string name
Time zone name.
Definition: DateTime.idl:35
boolean hasDSTInfo
true if the time zone has daylight saving time rules
Definition: DateTime.idl:36
Common base for all events.
Definition: Event.idl:13