Legrand / Raritan Xerus™ JSON-RPC API for Remote Access Devices like KX4-101, KX3G2

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}
datetime::DateTime
Date and time configuration methods.
Definition DateTime.idl:25
datetime::DateTime::setCfg
int setCfg(in Cfg cfg)
Set the device date and time configuration.
datetime::DateTime::Protocol
Protocol
Time synchronization protocol.
Definition DateTime.idl:67
datetime::DateTime::NTP
@ NTP
Device time is synchronized via NTP.
Definition DateTime.idl:69
datetime::DateTime::STATIC
@ STATIC
Device time is configured locally.
Definition DateTime.idl:68
datetime::DateTime::getZoneInfos
void getZoneInfos(out vector< ZoneInfo > zoneInfos, in boolean useOlson)
List all supported time zones.
datetime::DateTime::checkNtpServer
boolean checkNtpServer(in string ntpServer)
Check if a specified NTP server is usable.
datetime::DateTime::getActiveNtpServers
vector< string > getActiveNtpServers()
Get active NTP servers.
datetime::DateTime::getCfg
void getCfg(out Cfg cfg)
Retrieve the device date and time configuration.
datetime::DateTime::getTime
void getTime(in boolean useOlson, out ZoneInfo zone, out boolean dstEnabled, out int utcOffset, out time currentTime)
Retrieve the current device date and time.
datetime
Device Date and Time Configuration.
Definition DateTime.idl:11
idl
Basic IDL definitions.
Definition Event.idl:10
datetime::DateTime::Cfg
Device date and time configuration.
Definition DateTime.idl:79
datetime::DateTime::Cfg::deviceTime
time deviceTime
Device date and time (local time)
Definition DateTime.idl:82
datetime::DateTime::Cfg::ntpCfg
NtpCfg ntpCfg
NTP server configuration.
Definition DateTime.idl:83
datetime::DateTime::Cfg::protocol
Protocol protocol
Time synchronization protocol.
Definition DateTime.idl:81
datetime::DateTime::Cfg::zoneCfg
ZoneCfg zoneCfg
Time zone configuration.
Definition DateTime.idl:80
datetime::DateTime::ClockChangedEvent
Event that is sent when the device time is changed.
Definition DateTime.idl:91
datetime::DateTime::ClockChangedEvent::oldTime
time oldTime
Device time before change (UNIX timestamp, UTC)
Definition DateTime.idl:92
datetime::DateTime::ClockChangedEvent::newTime
time newTime
Device time after change (UNIX timestamp, UTC)
Definition DateTime.idl:93
datetime::DateTime::ConfigurationChangedEvent
Event that is sent when the configuration changes.
Definition DateTime.idl:87
datetime::DateTime::NtpCfg
Static NTP server configuration.
Definition DateTime.idl:73
datetime::DateTime::NtpCfg::server1
string server1
Primary NTP server.
Definition DateTime.idl:74
datetime::DateTime::NtpCfg::server2
string server2
Secondary NTP server.
Definition DateTime.idl:75
datetime::DateTime::ZoneCfg
Time zone configuration.
Definition DateTime.idl:60
datetime::DateTime::ZoneCfg::enableAutoDST
boolean enableAutoDST
Enable automatic daylight saving time adjustment.
Definition DateTime.idl:63
datetime::DateTime::ZoneCfg::id
int id
Selected time zone id.
Definition DateTime.idl:61
datetime::DateTime::ZoneCfg::name
string name
Selected time zone name (ignored on setCfg() if id != 0)
Definition DateTime.idl:62
datetime::DateTime::ZoneInfo
Time zone information (see also ZoneCfg)
Definition DateTime.idl:33
datetime::DateTime::ZoneInfo::id
int id
Time zone id.
Definition DateTime.idl:34
datetime::DateTime::ZoneInfo::name
string name
Time zone name.
Definition DateTime.idl:35
datetime::DateTime::ZoneInfo::hasDSTInfo
boolean hasDSTInfo
true if the time zone has daylight saving time rules
Definition DateTime.idl:36
idl::Event
Common base for all events.
Definition Event.idl:13