doc: Add API description for clock interface

diff --git a/doc/clock-api.txt b/doc/clock-api.txt
new file mode 100644 (file)
index 0000000..4ec3160
--- /dev/null
+++ b/doc/clock-api.txt
@@ -0,0 +1,87 @@
+Clock hierarchy
+===============
+
+Service                net.connman
+Interface      net.connman.Clock
+Object path    /
+
+Methods                dict GetProperties()
+
+                       Returns all system clock properties. See the
+                       properties section for available properties.
+
+                       Possible Errors: [service].Error.InvalidArguments
+
+               void SetProperty(string name, variant value)
+
+                       Changes the value of the specified property. Only
+                       properties that are listed as read-write are
+                       changeable. On success a PropertyChanged signal
+                       will be emitted.
+
+                       Possible Errors: [service].Error.InvalidArguments
+                                        [service].Error.InvalidProperty
+
+Signals                PropertyChanged(string name, variant value)
+
+                       This signal indicates a changed value of the given
+                       property.
+
+
+Properties     uint64 Time [readonly or readwrite]
+
+                       Current system time in seconds since epoch.
+
+                       This value is present for changing the system time
+                       if TimeUpdates is set to manual.
+
+                       It is not present for driving an updated display
+                       of the system time. PropertyChanged signal for this
+                       value are only send out if it gets changed or jumps
+                       unexpectedly.
+
+                       In general application interested in the current
+                       time should be using gettimeofday() and related
+                       system calls.
+
+               string TimeUpdates [readwrite]
+
+                       Possible values are "manual" and "auto" to indicate
+                       time update policy.
+
+                       With the "auto" setting the system tries to use as
+                       many sources as possible to determine the correct
+                       and updated time.
+
+               string Timezone [readonly or readwrite]
+
+                       Current system timezone string. Allowed values
+                       are from the standard timezone data (tzdata)
+                       package under /usr/share/zoneinfo. For example
+                       strings like "America/Vancouver" or "Europe/Berlin".
+
+                       This value is present for changing the timezone
+                       if TimezoneUpdates is set to manual.
+
+                       When the timezone gets changed a PropertyChanged
+                       signal will be send out.
+
+               string TimezoneUpdates [readwrite]
+
+                       Possible values are "manual" and "auto" to indicate
+                       timezone update policy.
+
+                       With the "auto" setting the system tries to use as
+                       many sources as possible to determine the correct
+                       timezone.
+
+               array{string} Timeservers [readwrite]
+
+                       List of global default NTP servers. The list should
+                       be sorted in order of preference.
+
+                       If a service configuration provides NTP servers,
+                       then they are preferred over the global ones.
+
+                       This list of servers is used when TimeUpdates is set
+                       to auto.