Loading...
Searching...
No Matches
DateTime.idl
/* SPDX-License-Identifier: BSD-3-Clause */
/*
* Copyright 2009 Raritan Inc. All rights reserved.
*/
#include <Event.idl>
/**
* Device Date and Time Configuration
*/
module datetime {
/** Date and time configuration methods
*
* Example to set timezone (id-based approach): @anchor set-timezone-example
*
* @code{.py}
* zoneinfos = getZoneInfos(False)
* cfg = getCfg()
* cfg.zoneCfg.id = ... # choose zone id from returned zoneinfos
* status = setCfg(cfg)
* if status != 0: ... # error handling
* @endcode
*/
interface DateTime {
/** Time zone information (see also ZoneCfg)
*
* There are two different approaches on how to identify timezones. See the ZoneCfg description.
*
* For timezones with non-trivial daylight saving time rules #hasDSTInfo is \c false.
*/
structure ZoneInfo {
int id; ///< Time zone id
string name; ///< Time zone name
boolean hasDSTInfo; ///< \c true if the time zone has daylight saving time rules
};
/** Time zone configuration
*
* There are two approaches on how timezones are identified:
* 1. id-based
*
* - timezone data identified with a numeric non-zero id
* - #id != 0
* - #name is the display name of the timezone and ignored on setCfg()
*
* 2. name-based (see NOTES below!)
*
* - timezone data identified with a name from the IANA timezone database (aka Olson database)
* - #id == 0
* - #name is the official IANA timezone name, e.g. Europe/Berlin or America/New_York
*
* **NOTES**:
* - The user frontends currently only support the id-based approach and may not work correctly with
* the name-based approach.
* - Setting #enableAutoDST to \c true has only an effect if the according ZoneInfo::hasDSTInfo
* field is also \c true.
*/
structure ZoneCfg {
int id; ///< Selected time zone id
string name; ///< Selected time zone name (ignored on setCfg() if id != 0)
boolean enableAutoDST; ///< Enable automatic daylight saving time adjustment
};
/** Time synchronization protocol */
enumeration Protocol {
STATIC, ///< Device time is configured locally
NTP ///< Device time is synchronized via NTP
};
/** Static NTP server configuration */
structure NtpCfg {
string server1; ///< Primary NTP server
string server2; ///< Secondary NTP server
};
/** Device date and time configuration */
structure Cfg {
ZoneCfg zoneCfg; ///< Time zone configuration
Protocol protocol; ///< Time synchronization protocol
time deviceTime; ///< Device date and time (local time)
NtpCfg ntpCfg; ///< NTP server configuration
};
/** Event that is sent when the configuration changes */
valueobject ConfigurationChangedEvent extends idl.Event {
};
/** Event that is sent when the device time is changed */
valueobject ClockChangedEvent extends idl.Event {
time oldTime; ///< Device time before change (UNIX timestamp, UTC)
time newTime; ///< Device time after change (UNIX timestamp, UTC)
};
/**
* List all supported time zones.
*
* @param zoneInfos Result: List of time zones
* @param useOlson Use Olson timezone names (see also ZoneCfg)
*/
void getZoneInfos(out vector<ZoneInfo> zoneInfos, in boolean useOlson);
/**
* Check if a specified NTP server is usable.
*
* @param ntpServer NTP server to be checked
*
* @return \c true if the NTP server is usable
*/
boolean checkNtpServer(in string ntpServer);
/**
* Get active NTP servers.
*
* @return List of currently active NTP servers (IP addresses and/or hostnames)
*/
vector<string> getActiveNtpServers();
/**
* Retrieve the device date and time configuration.
*
* @param cfg Result: Current date and time configration
*/
void getCfg(out Cfg cfg);
/**
* Set the device date and time configuration.
* Depending on the value of the \e protocol field either \e deviceTime
* or \e ntpCfg will be used from the \e cfg parameter.
*
* Specific @ref set-timezone-example "example" to set timezone.
*
* @param cfg New date and time configuration.
*
* @return 0 if OK
* @return 1 if the configuration is invalid
*/
int setCfg(in Cfg cfg);
/**
* Retrieve the current device date and time.
*
* @param useOlson Use Olson timezone name (see also ZoneCfg)
* @param zone Result: Active time zone
* @param dstEnabled if false, the time zone daylight saving time flag is not used
* @param utcOffset Result: Offset (in minutes) between local time and UTC
* @param currentTime Result: Device date and time (UNIX timestamp, UTC)
*/
void getTime(in boolean useOlson, out ZoneInfo zone,
out boolean dstEnabled, out int utcOffset,
out time currentTime);
};
}
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::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