| // Copyright 2021 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.intl; |
| |
| using zx; |
| |
| type TimeZonesError = flexible enum : int32 { |
| /// An internal error has occurred within the service. |
| INTERNAL_ERROR = 1; |
| /// The requested time zone ID is invalid. |
| UNKNOWN_TIME_ZONE = 2; |
| /// The provided date is out of range or invalid. |
| INVALID_DATE = 3; |
| }; |
| |
| /// During a transition from daylight savings to standard time (when the clock is turned back), a |
| /// civil time can correspond to two possible absolute times. This setting determines which of those |
| /// times should be assumed during the conversion to absolute time. |
| /// |
| /// TODO(https://fxbug.dev/42162861): Implement `AFTER_TRANSITION`. |
| type RepeatedTimeConversion = flexible enum : int32 { |
| /// Returns the wall clock time before the transition. |
| /// |
| /// For example, in "America/New_York" on the night of the fall transition to standard time, |
| /// `1:30 AM` is interpreted as `01:30-04:00` (EDT), which is `05:30Z`. |
| BEFORE_TRANSITION = 1; |
| }; |
| |
| /// During a transition from standard time to daylight savings time (when the clock is turned |
| /// forward), a span of civil times is skipped (usually one hour). This setting determines how |
| /// invalid civil times within this span should be treated. |
| /// |
| /// TODO(https://fxbug.dev/42162861): Implement `BEFORE_TRANSITION` and `AFTER_TRANSITION`. |
| type SkippedTimeConversion = flexible enum : int32 { |
| /// Returns `TimeZonesError::INVALID_DATE` when trying to convert a skipped civil time. |
| REJECT = 1; |
| |
| /// Returns the closest valid time after the requested time. |
| /// |
| /// For example, in "America/New_York" on the night of the spring transition to daylight savings |
| /// time, `2:30 AM` doesn't exist, so the next valid time, `3:00 AM` (EDT) is returned instead. |
| NEXT_VALID_TIME = 2; |
| }; |
| |
| /// Options for `TimeZones.CivilToAbsoluteTime`. |
| type CivilToAbsoluteTimeOptions = table { |
| /// Optional setting for handling repeated times during backward daylight savings time |
| /// transitions. |
| /// |
| /// Default: `BEFORE_TRANSITION`. |
| 1: repeated_time_conversion RepeatedTimeConversion; |
| /// Optional setting for handling skipped times during forward daylight savings time |
| /// transitions. |
| /// |
| /// Default: `NEXT_VALID_TIME`. |
| 2: skipped_time_conversion SkippedTimeConversion; |
| }; |
| |
| /// Provides information about time zones and offers date-time conversion methods. |
| /// |
| /// TODO(https://fxbug.dev/42162409): Add time zone info methods, including offsets from UTC. |
| @discoverable |
| closed protocol TimeZones { |
| |
| /// Converts the given absolute time to a civil date and time in the given time zone, using the |
| /// Gregorian calendar. |
| strict AbsoluteToCivilTime(struct { |
| /// The time zone in which to calculate a civil date and time. |
| time_zone_id TimeZoneId; |
| /// The number of nanoseconds since the Unix epoch. |
| /// For example, `at_time == 0` corresponds to 1970-01-01T00:00:00.000000000Z. |
| absolute_time zx.Time; |
| }) -> (struct { |
| civil_time CivilTime; |
| }) error TimeZonesError; |
| |
| /// Converts the given civil date and time in the given time zone to nanoseconds since the Unix |
| /// epoch. |
| strict CivilToAbsoluteTime(struct { |
| /// The civil date and time to convert. |
| /// |
| /// Note that `civil_time.weekday` and `civil_time.year_day` may be omitted for this method. |
| /// If present, they must be consistent with the other fields. |
| civil_time CivilTime; |
| /// Conversion options for civil times that cross a daylight savings transition. |
| options CivilToAbsoluteTimeOptions; |
| }) -> (struct { |
| absolute_time zx.Time; |
| }) error TimeZonesError; |
| |
| /// Retrieves details about a time zone at a specified one. |
| strict GetTimeZoneInfo(struct { |
| /// The time zone ID for which to retrieve information. |
| time_zone_id TimeZoneId; |
| /// The date and time at which to calculate values, in nanoseconds since the Unix epoch. |
| /// For example, `at_time == 0` corresponds to 1970-01-01T00:00:00.000000000Z. |
| at_time zx.Time; |
| }) -> (struct { |
| time_zone_info TimeZoneInfo; |
| }) error TimeZonesError; |
| }; |
| |
| /// Describes a time on a civil calendar (Gregorian), with nanosecond precision. This is roughly |
| /// equivalent to the `tm` struct in `time.h` in the C standard library, and is intended as a |
| /// structured intermediate format for printing or parsing dates. |
| type CivilTime = table { |
| /// Year, in the closed range `[1678, 2262]`. |
| 1: year uint16; |
| /// Month of the year. |
| 2: month Month; |
| /// Day of the month, in the closed range `[1, 31]`. |
| 3: day uint8; |
| /// Hour of the day, in the closed range `[0, 23]`. |
| 4: hour uint8; |
| /// Minute of the hour, in the closed range `[0, 59]`. |
| 5: minute uint8; |
| /// Second of the minute, in the closed range `[0, 59]`. |
| /// |
| /// (Note that Fuchsia does not currently calculate leap seconds when converting dates.) |
| 6: second uint8; |
| /// Nanosecond, in the closed range `[0, 999_999_999]`. |
| 7: nanos uint64; |
| /// Day of the week. |
| 8: weekday DayOfWeek; |
| /// Day of the year, in the closed range `[0, 365]`. |
| 9: year_day uint16; |
| /// The time zone corresponding to this time. If omitted, the default is UTC. |
| 10: time_zone_id TimeZoneId; |
| }; |
| |
| /// Describes a Time Zone's properties at a particular moment in time. |
| /// |
| /// TODO(https://fxbug.dev/42162409): Additional fields with a breakdown of offsets and DST status. |
| type TimeZoneInfo = table { |
| /// The time zone's IANA ID. |
| 1: id TimeZoneId; |
| /// The total offset (including Daylight Savings, if the time zone is in Daylight Savings Time) |
| /// from UTC at the queried time (`at_time`). If the time zone is ahead of UTC, this will be a |
| /// positive value; if behind UTC, a negative value. |
| 2: total_offset_at_time zx.Duration; |
| /// Indicates whether the time zone is in Daylight Savings Time at the queried time |
| /// (`at_time`). |
| 3: in_dst_at_time bool; |
| }; |