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 {
 
        /** Success code */
        constant int SUCCESS                                    =  0;
 
        /** NTP server check errors */
        constant int ERR_NTP_CHECK_INTERNAL                     =  1;
        constant int ERR_NTP_CHECK_INVALID_ARGUMENT             =  2;
        constant int ERR_NTP_CHECK_ADDRESS_RESOLVE_ERROR        =  3;
        constant int ERR_NTP_CHECK_AUTH_KEY_ID_UNKNOWN          =  4;
        constant int ERR_NTP_CHECK_NETWORK_OR_HOST_UNREACHABLE  =  5;
        constant int ERR_NTP_CHECK_CONNECTION_REFUSED           =  6;
        constant int ERR_NTP_CHECK_NO_RESPONSE                  =  7;
        constant int ERR_NTP_CHECK_RESPONSE_FORMAT_INVALID      =  8;
        constant int ERR_NTP_CHECK_SERVER_VERSION_UNSUPPORTED   =  9;
        constant int ERR_NTP_CHECK_MAC_MISSING_OR_INVALID       = 10;
        constant int ERR_NTP_CHECK_MODE_INVALID                 = 11;
        constant int ERR_NTP_CHECK_SERVER_NOT_SYNCHRONIZED      = 12;
        constant int ERR_NTP_CHECK_ROOT_DISTANCE_TOO_LARGE      = 13;
        constant int ERR_NTP_CHECK_ORIGIN_TIME_DOES_NOT_MATCH   = 14;
        constant int ERR_NTP_CHECK_RECV_OR_XMIT_TIME_NOT_SET    = 15;
 
        /**
         * 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
        };
 
        /** NTP authentication key type */
        enumeration NtpAuthKeyType {
            SHA256,                     ///< SHA-256 authentication key
            SHA512,                     ///< SHA-512 authentication key
            AES128CMAC,                 ///< AES128-CMAC authentication key
            AES256CMAC                  ///< AES256-CMAC authentication key
        };
 
        /** NTP authentication key */
        structure NtpAuthKey {
            NtpAuthKeyType type;        ///< NTP authentication key type
                                        ///<   (only honoured on write if dataHex is provided as well)
            string dataHex;             ///< NTP authentication key data as case insensitive hex string
                                        ///<   (write-only; leave empty to keep current value)
        };
 
        /** Static NTP server configuration */
        structure NtpCfg {
            string server1;             ///< Primary NTP server
            int server1AuthKeyId;       ///< Primary NTP server authetication key id
                                        ///<   (interpreted as 32bit unsigned int; 0 means no authentication)
            string server2;             ///< Secondary NTP server
            int server2AuthKeyId;       ///< Secondary NTP server authetication key id
                                        ///<   (interpreted as 32bit unsigned int; 0 means no authentication)
            map<int, NtpAuthKey> authKeys; ///< NTP authentication keys indext by the key id.
                                           ///< The key id is to be treated as unsigned 32bit integer.
        };
 
        /** 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.
         *
         * When calling this method a potentially referenced authentication key must have been defined first.
         *
         * @param ntpServer           NTP server to be checked
         * @param ntpAuthKeyId        NTP authentication key id (0 for no authentication)
         * @param ntpAuthKeyOverride  NTP authentication key (leave key data empty to use existing key & type)
         *
         * @return \c SUCCESS or one of the ERR_NTP_CHECK_* error codes
         */
        int checkNtpServer(in string ntpServer, in int ntpAuthKeyId, in NtpAuthKey ntpAuthKeyOverride);
 
        /**
         * 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 configuration
         */
        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);
 
    };
 
}