Windows API Reference - Kernel-User Base

Time Services

This section details the Windows API functions and structures related to time management. These services allow applications to query system time, manage time zones, and perform time-related calculations.

Core Concepts

The Windows operating system provides robust mechanisms for handling time. Key concepts include:

System Time: The current time as maintained by the system clock.
UTC Time: Coordinated Universal Time, a standard time scale.
Local Time: Time adjusted for the system's configured time zone and daylight saving rules.
File Times: A 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).

Key Functions

Querying System Time

These functions retrieve the current time from the system.

Note: For most applications, using GetSystemTimeAsFileTime or GetLocalTime is sufficient. For high-resolution timing, consider using QueryPerformanceCounter.

Function Name	Description
`GetSystemTime`	Retrieves the current system time in UTC.
`GetLocalTime`	Retrieves the current local time.
`GetSystemTimeAsFileTime`	Retrieves the current system time as a `FILETIME` structure.
`GetTickCount`	Retrieves the number of milliseconds that have elapsed since the system was started. (Deprecated, use `GetTickCount64`)
`GetTickCount64`	Retrieves the number of milliseconds that have elapsed since the system was started as a 64-bit value.
`QueryPerformanceCounter`	Retrieves the current value of the high-resolution performance counter.
`QueryPerformanceFrequency`	Retrieves the current frequency of the high-resolution performance counter.

Time Conversions and Formatting

These functions convert between different time representations and format them for display.

Function Name	Description
`FileTimeToSystemTime`	Converts a `FILETIME` structure to a `SYSTEMTIME` structure.
`SystemTimeToFileTime`	Converts a `SYSTEMTIME` structure to a `FILETIME` structure.
`FileTimeToLocalFileTime`	Converts a `FILETIME` structure representing UTC time to a `FILETIME` structure representing local time.
`LocalFileTimeToFileTime`	Converts a `FILETIME` structure representing local time to a `FILETIME` structure representing UTC time.
`SystemTimeToTzSpecificLocalTime`	Converts a `SYSTEMTIME` structure representing UTC time to a `SYSTEMTIME` structure representing local time in a specified time zone.
`FormatMessage`	Can be used to format system error messages, including time-related ones, into human-readable strings.

Time Zones and Daylight Saving

Manage and query information about time zones and daylight saving time.

Function Name	Description
`GetTimeZoneInformation`	Retrieves information about the current time zone, including its display name, standard name, daylight name, and bias.
`GetDynamicTimeZoneInformation`	Retrieves information about the current time zone, including whether daylight saving time is currently in effect.
`SetTimeZoneInformation`	Sets the current time zone information. Requires administrative privileges.
`GetTimeZoneInformationBySystemTimeZoneId`	Retrieves time zone information using a standard time zone identifier.

Structures

Key data structures used by time services:

SYSTEMTIME: Represents a date and time using individual year, month, day, hour, minute, second, and millisecond members.
FILETIME: Represents a date and time as a 64-bit value.
TIME_ZONE_INFORMATION: Contains information about a time zone.
DYNAMIC_TIME_ZONE_INFORMATION: Extends TIME_ZONE_INFORMATION with additional daylight saving time information.

`SYSTEMTIME` Structure

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

`FILETIME` Structure

typedef struct _FILETIME {
    DWORD dwLowDateTime;
    DWORD dwHighDateTime;
} FILETIME;

`TIME_ZONE_INFORMATION` Structure

typedef struct _TIME_ZONE_INFORMATION {
    LONG       Bias;
    WCHAR      StandardName[32];
    WCHAR      DaylightName[32];
    SYSTEMTIME StandardDate;
    SYSTEMTIME DaylightDate;
} TIME_ZONE_INFORMATION;

Important: When dealing with time, always consider potential issues like time zone conversions, daylight saving time transitions, and leap seconds to ensure accurate timekeeping.

Example: Getting and Displaying Local Time

Here's a basic C++ example demonstrating how to get the local time and display it.

#include <windows.h>
#include <iostream>
#include <locale>
#include <codecvt>

int main() {
    SYSTEMTIME st;
    GetLocalTime(&st);

    // Use locale to handle potential wide characters from names
    std::locale loc("");
    std::wcout.imbue(loc);
    std::wcout.clear();
    std::wcout.fill('0');

    std::wcout << L"Local Time: "
               << st.wHour << L":"
               << std::setw(2) << st.wMinute << L":"
               << std::setw(2) << st.wSecond << L"."
               << std::setw(3) << st.wMilliseconds << std::endl;

    std::wcout << L"Date: "
               << st.wMonth << L"/"
               << st.wDay << L"/"
               << st.wYear << std::endl;

    return 0;
}