Greyware Automation Products, Inc.
Greyware Automation Products, Inc.   
     Home    Products    Store    Downloads    Customer Service    Site Search    
Log in  or   Create an account now -- FREE!        
Domain Time II > v5 > Configuration > Other > Software Development Kit (SDK)

Pricing   Buy Now

Download
30-Day Trial Version
Domain Time II
Version 5.2
History  Software Development Kit (SDK)

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.

      Sample program showing OS time on the left, Domain Time Hi-Res Time on the right
      Sample program showing OS time on the left, Domain Time Hi-Res Time on the right   [Click for larger size]

      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.

      Sample program showing some of the available PTP information
      Sample program showing some of the available PTP information   [Click for larger size]

      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.

     


My Account  |   Contact Us  |   Privacy Policy  |   Printer-Friendly Version
 
Copyright © 1995-2023 Greyware Automation Products, Inc.  All Rights Reserved
All Trademarks mentioned are the properties of their respective owners.