Some notes on working with MAPPS and Microsoft Windows Filetime

#Overview

The MAPPS software suite easily combines data for visualization and analysis. Its tools make recording video, eye-tracking, HID, and 3rd-party hardware data with in a networked environment a snap.

Data synchronized by MAPPS relies on timestamps sent with the data. As a Windows focused product, MAPPS uses 64-bit Windows Filetime for its timestamp format. FILETIME is a 64-bit integer that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (UTC). When capturing data, MAPPS Adapters and Video Streamer record the current FILETIME of the PC they're running on as the capture time.

It's also possible to create custom MAPPS adapters and send your own data stream. Custom data should be timestamped with the current Windows FILETIME.

IMPORTANT NOTE: Data capture time is critical when synchronizing streams from different network sources. To minimize clock skew, the clocks of all data sources must be synchronized with a good NTP client such as Meinberg NTP. eyesDx recommends synchronizing all PCs with Meinberg NTP.

Data exported from MAPPS will have a UTC Time (ticks) column. This column is the Windows FILETIME timestamp of the data. It is presented as a 64-bit number. If you want to process exported data in your own software, you can use this column to get the capture time of each data row.

#Obtaining the current FILETIME on Windows / WIN32

As a Microsoft format, FILETIME is fully supported by Win32 and .NET/

#C/C++

The simplest way to get the current system time as a FILETIME struct is to use the GetSystemTimeAsFileTime function from sysinfoapi.h:

  #include <sysinfoapi.h>
  #include <stdint.h>

...

  FILETIME ft;
  GetSystemTimeAsFileTime(&ft);
  ULARGE_INTEGER ul;
  ul.LowPart = ft.dwLowDateTime;
  ul.HighPart = ft.dwHighDateTime;
  uint64_t result = ul.QuadPart;

You can also get the current system time with GetSystemTime() from sysinfoapi.h and convert it to a FILETIME struct with SystemTimeToFileTime() from timezoneapi.h

	SYSTEMTIME st;
	GetSystemTime(&st);
	FILETIME ft;
	SystemTimeToFileTime(&st, &ft);  // converts to file time format
	ULARGE_INTEGER ui;
	ui.LowPart = ft.dwLowDateTime;
	ui.HighPart = ft.dwHighDateTime;
	int64_t  fileTime= ui.QuadPart;

#String Conversion

You may want to see the FILETME as a human readable string. A simple way to do this to convert it to SYSTEMTIME and access the parts of the date as needed

	SYSTEMTIME st;
	FileTimeToSystemTime(&ft, &st);

	char buffer[32];
	// Format: YYYY.MM.DD_HH.MM.SS.millisecond
	snprintf(buffer, sizeof(buffer), "%04d.%02d.%02d_%02d.%02d.%02d.%03d",
		st.wYear, st.wMonth, st.wDay,
		st.wHour, st.wMinute, st.wSecond, st.wMilliseconds);
	std::cout << buffer << std::endl;

#Getting FILETIME in C#

C# makes it very easy to get the current time as a FILETIME. You just call ToFileTimeUtc()

var timestamp = DateTime.UtcNow.ToFileTimeUtc();

You can also use ToFileTime()

var timestamp = DateTime.UtcNow.ToFileTime();

#String Conversion

Just like C++, convert the FILETIME to a DateTime object. DateTime has ToString() method for formatting your output.

DateTime dateTime = DateTime.FromFileTime(timestamp);
Console.WriteLine(dateTime.ToString("yyyy.MM.dd_HH.mm.ss.fff"));

#Getting a FILETIME on Other Platforms

Some MAPPS customers use platforms other than Windows. These platforms generally don't support windows FILETIME, but their timestamps can be converted to FILETIME with a little bit of math.

FILETIME is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. Other time functions often return a time in microseconds from January 1, 1970. We can convert these timestamps by adding a 116444736000000000 to the seconds and multiplying by 10,000,000 to convert seconds to 100s of nanoseconds.

#C

C can get the current time with gettimeofday(). gettimeofday() returns a timeval struct, which has microseconds and seconds since 1970/01/01.

    struct timeval {
         time_t      tv_sec;     /* seconds */
         suseconds_t tv_usec;    /* microseconds */
     };

We just need to

#include <sys/time.h>
#define FT_TO_UNIX 11644473600LL
 ...
    struct timeval tv;

    unsigned long long filetime = FT_TO_UNIX ;
    gettimeofday(&tv, NULL);
    filetime += tv.tv_sec;
    filetime *= 10000000LL;       // seconds to 100s of nanosecnds
    filetime += tv.tv_usec * 10;  // micro-seconds to 100's nanoseconds

#Python

Get FILETIME from time.time()

import time

# get current time in seconds and convert to 100s of nanoseconds
t = time.time() * 10000000
filetime = t + 116444736000000000 

Get FILETIME from datetime.now()

from datetime import datetime, tzinfo, timezone
import calendar
now = datetime.now(timezone.utc)

ft = 116444736000000000 + calendar.timegm(now.timetuple()   ) * 10_000_000
ft = ft + now.microsecond * 10


dt = datetime.fromtimestamp((ft - 116444736000000000  ) / 10_000_000  , UTC)
strtime = dt.strftime("%Y.%m.%d_%H.%M.%S.%f")[:-3]

#Getting FILETIME In Java

static final long FILETIME_EPOCH_DIFF = 11644473600000L

long msTime = System.currentTimeMillis();
long fileTIme = (millis * 10000) + FILETIME_EPOCH_DIFF;

#iOS time to Windows FILETIME

Get time since 1970.

    // in miliseconds
    NSTimeInterval ntpInMiliseconds = [date timeIntervalSince1970]*1000;

    // convert to windows filetime
    int64_t filetime = ntpInMiliseconds * 10000 + 116444736000000000;

#Swift

var msSinceEpoch:int64 = Date.timeIntervalSince1970 * 1000.0
var filetime:int64 = milliseconds_since_epoch * 10000 + 116444736000000000;

#C++

using std::chrono

 unsigned long milliseconds_since_epoch =
    std::chrono::system_clock::now().time_since_epoch() / 
    std::chrono::milliseconds(1);


    int64_t filetime = milliseconds_since_epoch * 10000 + 116444736000000000;

 

#JavaScript

function filetimeFromDate(date) {  
    return date.getTime() * 1e4 + 116444736e9;
}
const now = new Date();
const filetimeNow = filetimeFromDate(now);
console.log(filetimeNow);