The Software Development Kit (SDK) allows programmatic access to Domain Time's internal time at an extremely high accuracy so
that you may include accurate, high-resolution timestamps in your applications. In addition, it provides an API that allows you
to easily obtin other information on Domain Time's synchronization status, and, with recent versions, statistical information on PTP
synchronization.
Obtaining the SDK
The SDK includes 32 and 64-bit high-resolution .dlls, sample programs, and full API documentation.
These are included in the \SDK folder of the free 30-day evaluation download package,
and are also downloadable as a distribution package from your online account once it's been registered.
The SDK license is a special site license to allow you to distribute the SDK .dlls within your organization. You must own
this license to deploy the SDK .dlls on your systems. The SDK license is available as a separate line item (Part #GW360358) for purchase on our
Online Store.
The .dll's require an installed version 5.1 or later of Domain Time Client or Domain Time Server. Newer features require a current version
of version 5.2.
Note, interpolated high-resolution timestamps are now available from the Windows API on Win8/Server 2012
and later. However, the SDK interoperates with these versions, so that if your application must run
on a mix of older platforms, for example Server 2008 and Server 2016, then using the SDK gives you a
single interface to obtain high-resolution time without changing your application based on the operating
system version, along with gaining the additional Domain Time status APIs.
Full Documentation
The full technical documentation for the SDK is contained in the sdk.doc file and the DTHres.h included in the SDK download.
Sample programs demonstrate how to use the API, and document the events and settings you may find useful.
Background Info
The Windows operating system only allows setting the time to the nearest millisecond (0.001 seconds).
The theoretical accuracy of time protocols goes to microseconds (0.0000001 second) and beyond. The
actual performance of software-based timekeeping rarely reaches the microsecond level due to the
non-realtime nature of the operating system, network performance variations, misbehaved hardware
interrupt handlers, and lack of good hardware timing support. Nevertheless, Domain Time’s practical
accuracy usually meets the one-millisecond level, and often exceeds it by several orders of magnitude.
Obtaining the time to the nearest microsecond doesn’t do much good if the system clock can only be set
to the nearest millisecond. For this reason, Domain Time only “sets” the clock when stepping. The rest
of the time, Domain Time slews the clock (adjusts the frequency) so that time passing on a wall clock
and time passing within the computer come into conformance with a high degree of accuracy.
The theoretical granularity of the operating system’s API to retrieve the time of day is in
hectonanoseconds (0.00000001 second, or a tenth of a microsecond). However, while Domain Time can
adjust the system’s clock to this level, the operating system cannot report it. The actual granularity
of the operating system’s API is the base interrupt frequency for the machine. This is usually 10 or 15
milliseconds. Rapid successive queries of the system time via GetSystemTimeAsFileTime will show the
clock holding still for 10 or 15 milliseconds, then jumping forward, then holding still again, and so
forth. The operating system simply calculates the number of hectonanoseconds per interrupt, and adds
that quantity at each interrupt.
Domain Time uses the performance counter in combination with the system clock to interpolate the points
between clock jumps. Thus, while the operating system sees the time moving forward in large discrete
jumps, Domain Time sees it moving forward in very small increments. (The size of increment Domain Time
can track depends on the hardware of the individual machine, but usually ranges from a few microseconds
to a few hundred microseconds.)
This interpolation allows Domain Time to compare time received from the network with the computer’s time
at a level far below the operating system’s native capacity, yielding more accurate corrections and more precise time.
The SDK allows other user-mode programs or services to take advantage of Domain Time’s internal clock.
By using the supplied DLL, other programs can have access to the same high-resolution clock used for
maintaining the time. This allows true sub-millisecond precision for timing loops or time of day retrieval.
While any program can do its own interpolation to get sub-millisecond timing, they cannot marry the elapsed
time counter to the time of day without Domain Time.
Status API and PTP Statistics
In versions of the SDK dated after 01 April 2019, a new function for obtaining PTP statistics
is available. GetPTPStats() tells you whether or not Domain Time is using PTP, the current
state (SLAVE, MASTER, etc.), the PTP domainNumber, the PTP profile in use, and Domain Time's
portIdentity on the network.
If the PTP statistics indicate Domain Time is a SLAVE, then you are also provided the
master's portIdentity and IP address. In addition, you may obtain the current offset from
the master (in tenths of a microsecond) and the current mean path delay (also in tenths
of a microsecond).
A new demonstration program, APITest, demonstrates loading the SDK DLL dynamically, and
obtaining the function pointers for various functions. It is heavily commented, especially
in regard to the new GetPTPStats() function, so you can easily incorporate this into your
own programs.
Software Development Kit (SDK)
