SYSTIME-FILETIME.md

Windows API Time Structures Reference

Overview

Windows API provides two main structures for handling date and time: FILETIME and SYSTEMTIME. Each serves different purposes in time representation and manipulation.

---

FILETIME Structure

Description

Contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).

Syntax

typedef struct _FILETIME {
    DWORD dwLowDateTime;
    DWORD dwHighDateTime;
} FILETIME, *PFILETIME, *LPFILETIME;

Members

• dwLowDateTime: The low-order part of the file time
• dwHighDateTime: The high-order part of the file time

Key Points

Time Representation

• Represents time as 64-bit value (100-nanosecond intervals)
• Epoch: January 1, 1601 00:00:00 UTC
• Used internally by Windows for file timestamps

Working with FILETIME

✅ DO:

• Copy to ULARGE_INTEGER structure for arithmetic operations
• Use FileTimeToSystemTime() to convert to human-readable format
• Perform 64-bit arithmetic on the QuadPart member

❌ DON'T:

• Don't add/subtract values directly from FILETIME structure
• Don't cast pointer to ULARGE_INTEGER* or __int64* (causes alignment faults on 64-bit Windows)

File System Considerations

• Not all file systems record creation and last access time
• Different file systems have different time resolutions:
  • FAT: Create time (10ms), write time (2s), access time (1 day)
  • NTFS: Access time (1 hour)
• FAT stores times in local time
• NTFS stores times in UTC

Special Values

• Can use values outside typical range (e.g., 0xFFFFFFFF in SetFileTime() to preserve previous access time)

Requirements

• Minimum client: Windows 2000 Professional
• Minimum server: Windows 2000 Server
• Header: minwinbase.h (include Windows.h)

---

SYSTEMTIME Structure

Description

Specifies a date and time using individual members for month, day, year, weekday, hour, minute, second, and millisecond. Time can be in UTC or local time depending on the function used.

Syntax

typedef struct _SYSTEMTIME {
    WORD wYear;
    WORD wMonth;
    WORD wDayOfWeek;
    WORD wDay;
    WORD wHour;
    WORD wMinute;
    WORD wSecond;
    WORD wMilliseconds;
} SYSTEMTIME, *PSYSTEMTIME, *LPSYSTEMTIME;

Members

Member	Description	Valid Range
wYear	The year	1601 - 30827
wMonth	The month	1 (January) - 12 (December)
wDayOfWeek	Day of the week	0 (Sunday) - 6 (Saturday)
wDay	Day of the month	1 - 31
wHour	The hour	0 - 23
wMinute	The minute	0 - 59
wSecond	The second	0 - 59
wMilliseconds	The millisecond	0 - 999

Important Warnings

⚠️ SYSTEMTIME does NOT validate dates! You must ensure the date is valid, especially in leap year scenarios.

Best Practices for Date Arithmetic

❌ WRONG: Adding/subtracting values directly from SYSTEMTIME

✅ CORRECT: Follow this process:

1. Convert SYSTEMTIME to FILETIME using SystemTimeToFileTime()
2. Copy FILETIME to ULARGE_INTEGER
3. Perform 64-bit arithmetic on QuadPart member
4. Copy back to FILETIME if needed
5. Convert to SYSTEMTIME using FileTimeToSystemTime() if needed

Example Usage

#include <windows.h>
#include <stdio.h>

void main()
{
    SYSTEMTIME st, lt;
    GetSystemTime(&st);    // Gets UTC time
    GetLocalTime(&lt);      // Gets local time
    
    printf("The system time is: %02d:%02d\n", st.wHour, st.wMinute);
    printf(" The local time is: %02d:%02d\n", lt.wHour, lt.wMinute);
}

Requirements

• Minimum client: Windows 2000 Professional
• Minimum server: Windows 2000 Server
• Header: minwinbase.h (include Windows.h)

---

SystemTimeToFileTime Function

Description

Converts a system time to file time format. System time is based on Coordinated Universal Time (UTC).

Syntax

BOOL SystemTimeToFileTime(
    [in]  const SYSTEMTIME *lpSystemTime,
    [out] LPFILETIME       lpFileTime
);

Parameters

• lpSystemTime [in]: Pointer to SYSTEMTIME structure containing the UTC time to convert

  • Note: wDayOfWeek member is ignored

• lpFileTime [out]: Pointer to FILETIME structure to receive the converted time

Return Value

• Nonzero: Function succeeded
• Zero: Function failed (call GetLastError() for details)

⚠️ Important: A FALSE return can indicate an invalid date in the SYSTEMTIME structure (e.g., February 30, invalid leap year dates).

Requirements

• Header: timezoneapi.h (include Windows.h)
• Library: Kernel32.lib
• DLL: Kernel32.dll

---

Conversion Functions Summary

Function	Converts From	Converts To	Purpose
SystemTimeToFileTime()	SYSTEMTIME	FILETIME	Human-readable → Internal format
FileTimeToSystemTime()	FILETIME	SYSTEMTIME	Internal format → Human-readable
GetSystemTime()	-	SYSTEMTIME	Get current UTC time
GetLocalTime()	-	SYSTEMTIME	Get current local time
GetSystemTimeAsFileTime()	-	FILETIME	Get current UTC as FILETIME

---

Quick Reference: When to Use What

• Use SYSTEMTIME when:

  • Displaying dates/times to users
  • Parsing user input
  • Working with individual date components

• Use FILETIME when:

  • Performing date arithmetic
  • Working with file timestamps
  • Comparing dates/times
  • Need high precision (100-nanosecond resolution)

---

Common Pitfalls

1. Not validating SYSTEMTIME dates - Structure doesn't check validity
2. Direct arithmetic on SYSTEMTIME - Always convert to FILETIME first
3. Pointer casting FILETIME - Causes alignment issues
4. Ignoring file system differences - Time resolution varies by file system
5. Leap year handling - Be careful with February 29 dates