Specifies a date and time, using individual members for the month, day, year, weekday, hour, minute, second, and millisecond. The time is either in coordinated universal time (UTC) or local time, depending on the function that is being called.
Syntax
Members
The year. The valid values for this member are 1601 through 30827.
The month. This member can be one of the following values.
Value
Meaning
1
January
2
February
3
March
4
April
5
May
6
June
7
July
8
August
9
September
10
October
11
November
12
December
The day of the week. This member can be one of the following values.
Value
Meaning
0
Sunday
1
Monday
2
Tuesday
3
Wednesday
4
Thursday
5
Friday
6
Saturday
The day of the month. The valid values for this member are 1 through 31.
The hour. The valid values for this member are 0 through 23.
The minute. The valid values for this member are 0 through 59.
The second. The valid values for this member are 0 through 59.
The millisecond. The valid values for this member are 0 through 999.
Remarks
The SYSTEMTIME does not check to see if the date represented is a real and valid date. When working with this API, you should ensure its validity, especially in leap year scenarios. See leap day readiness for more information.
It is not recommended that you add and subtract values from the SYSTEMTIME structure to obtain relative times. Instead, you should
Convert the SYSTEMTIME structure to a FILETIME structure.
Copy the resulting FILETIME structure to a ULARGE_INTEGER structure.
Use normal 64-bit arithmetic on the ULARGE_INTEGER value.
The system can periodically refresh the time by synchronizing with a time source. Because the system time can be adjusted either forward or backward, do not compare system time readings to determine elapsed time. Instead, use one of the methods described in Windows Time.
Examples
The following example demonstrates the difference between the time values retrieved by the GetSystemTime and GetLocalTime functions.
MMTIME structure
The MMTIME structure contains timing information for different types of multimedia data.
Syntax
Members
wType Time format. It can be one of the following values.
Format
Description
TIME_BYTES
Current byte offset from beginning of the file.
Time in milliseconds.
Number of waveform-audio samples.
SMPTE (Society of Motion Picture and Television Engineers) time.
Ticks within a MIDI stream.
u A union that contains the following members.
ms Number of milliseconds. Used when wType is TIME_MS.
sample Number of samples. Used when wType is TIME_SAMPLES.
cb Byte count. Used when wType is TIME_BYTES.
ticks Ticks in MIDI stream. Used when wType is TIME_TICKS.
smpte SMPTE time structure. Used when wType is TIME_SMPTE.
hour Hours.
min Minutes.
sec Seconds.
frame Frames.
fps Frames per second (24, 25, 29 (30 drop), or 30).
dummy Dummy byte for alignment.
pad Padding.
midi MIDI time structure. Used when wType is TIME_MIDI.
Requirements
Minimum supported client
WindowsВ 2000 Professional [desktop apps only]
Date & time in Windows API
last modified July 16, 2020
In this part of the Windows API tutorial, we will work with date and time. ZetCode has an article dealing with date and time in ANSI C.
The SYSTEMTIME structure is used to work with date and time in Windows API. The time can be either coordinated universal time (UTC) or local time. It has the following members:
The SYSTEMTIME structure is filled either with the GetSystemTime() function or the GetLocalTime() function. We can then access the members of the structure to get the current date or time.
The FILETIME structure contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC). With this value we are able to compute the Windows API epoch or the datetime differences.
The FILETIME structure has two members: the dwLowDateTime is the low-order part of the file time and the dwHighDateTime is the high-order part of the file time. To get a single value from the two members, we utilise the LARGE_INTEGER union.
The FileTimeToSystemTime() and the SystemTimeToFileTime() functions are used to convert between the two structures.
Local time
Local time is defined as the current time in the user’s time zone.
The program prints the local time.
We declare the SYSTEMTIME structure. The members of this structure are filled by calling a specific time function.
The GetLocalTime() retrieves the current local date and time. It fills the members of the SYSTEMTIME structure with current date & time values.
We print the current local time in the hh:mm:ss format.
This is the sample output.
UTC time
Our planet is a sphere. It revolves round its axis. The Earth rotates towards the east. So the Sun rises at different times in different locations. The Earth rotates once in about 24 hours. Therefore, the world was divided into 24 time zones. In each time zone, there is a different local time. This local time is often further modified by the daylight saving.
There is a pragmatic need for one global time. One global time helps to avoid confusion about time zones and daylight saving time. The UTC (Universal Coordinated time) was chosen to be the primary time standard. UTC is used in aviation, weather forecasts, flight plans, air traffic control clearances, and maps. Unlike local time, UTC does not change with a change of seasons.
The Windows API has the GetSystemTime() function to get the UTC time.
In the example we compute the UTC time.
The UTC time will be stored in the SYSTEMTIME structure.
We retrieve the UTC time using the GetSystemTime() function.
The UTC time is printed to the console in the hh:mm:ss format.
This is the output for the UTC time.
Arithmetic
It is not recommended to do arithmetic operations on values from the SYSTEMTIME structure to obtain relative times. Instead, we convert the SYSTEMTIME structure to a FILETIME structure, copy the resulting FILETIME structure to a ULARGE_INTEGER structure, and use normal 64-bit arithmetic on the ULARGE_INTEGER value. In the end, we convert the FILETIME structure back to SYSTEMTIME structure.
In the example we add three hours to the current local time value.
The three hours are expressed in seconds.
With the GetLocalTime() function, we retrieve the current local time.
We call the SystemTimeToFileTime() function to convert the SYSTEMTIME structure to the FILETIME structure.
The ULARGE_INTEGER structure is created.
We add three hours to the QuadPart member of the ULARGE_INTEGER structure. The member is expressed in 100-nanosecond ticks; therefore, we multiply the NSECS by 10000000LLU .
We translate the FILETIME structure back to the SYSTEMTIME structure.
This is a sample output of the Arithmetic.exe . Three hours were correctly added to the current local time.
The GetLocalTime() function is also used to determine the current date.
The above program prints today’s date.
We declare a SYSTEMTIME structure.
We fill the SYSTEMTIME members with current local time and date values.
The current date is printed to the console. We have chosen the Gregorian big-endian date format.
This is the output of the Today.exe program.
Formatting date
The GetDateFormatEx() function formats a date as a date string for the specified locale.
The program prints the current local time in a localized format.
The local time is retrieved.
The GetDateFormatEx() formats the date in the default locale specified in the regional and language options. The date is printed in a long date format.
The date is printed to the console.
The program prints the date in the Slovak language.
Determining a leap year
A leap year is a year containing an additional day. The reason for an extra day in the calendar is the difference between the astronomical and the calendar year. The calendar year has exactly 365 days, while the astronomical year, the time for the earth to make one revolution around the Sun, is 365.25 days. The difference is 6 hours which means that in four years time we are missing one day. Because we want to have our calendar synchronised with the seasons, we add one day to February each four years. (There are exceptions.) In the Gregorian calendar, February in a leap year has 29 days instead of the usual 28. And the year lasts 366 days instead of the usual 365.
We have an array of years. We check all years if they are leap years or not. There is no built-in function to check for a leap year. We have created a custom isLeapYear() function.
This is an array of years that we will check. The years must be in the Gregorian calendar.
With the for loop we traverse the array. We check if a year is a leap year using the isLeapYear() function.
This is the function for determining a leap year. Leap years are integer multiples of 4. A year that is an integer multiple of 100 is not a leap year, unless it is also an integer multiple of 400, in which case it is also a leap year.
Output of the LeapYear.exe program.
Uptime
The GetTickCount() function can be used to get the uptime of a computer. It retrieves the number of milliseconds that have elapsed since the system has started.
The function returns a DWORD value, so the maximum number of days returned is 49.7. To get over this limitation, we can use the GetTickCount64() . The function is available since Windows Vista.
The program prints the uptime of a computer. We use the GetTickCount() function. It works correctly if the computer is running less than 49.71 days or 4294967296 ms. After that the DWORD value overflows.
We get the number of milliseconds the computer is running. The maximum number a DWORD variable can store is ULONG_MAX .
We compute the seconds, minutes, hours, days, and weeks.
If the computer is running one or more weeks, we either print the weeks variable or «1 week» string to the console.
Day of week
The wDayOfWeek member of the SYSTEMTIME structure stores the day of the week. The values are 1..7 where 1 is Sunday, 2 Monday. 7 Saturday.
The code prints the current day of the week to the console.
We store the names of the days in a string array.
These lines retrieve and print the current day of the week.
This is the output.
The epoch
An epoch is an instant in time chosen as the origin of a particular era. For example in western Christian countries the time epoch starts from day 0, when Jesus was born (is believed to be born). Another example is the French Republican Calendar which was used for twelve years. The epoch was the beginning of the Republican Era which was proclaimed on September 22, 1792, the day the First Republic was declared and the monarchy abolished. Computers have their epochs too. One of the most popular is the Unix time. The Unix epoch is the time 00:00:00 UTC on 1 January 1970 (or 1970-01-01T00:00:00Z ISO 8601). The date and time in a computer is determined according to the number of seconds or clock ticks that have elapsed since the defined epoch for that computer or platform.
Windows operating system has several epochs. Microsoft Excel, MS SQL Server or FAT32 filesystem have different time epochs. The Windows API epoch is January 1, 1601, 00:00:00 UTC. The reason for choosing this date was the 400th anniversary of accepting of the Gregorian calendar. The anniversary fall at the time when Windows NT was designed. The FILETIME structure contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).
The code example computes the number of 100-nanosecond intervals elapsed from the Windows API epoch till this moment.
We declare the FILETIME structure. It has two members. The dwLowDateTime holds the low-order part of the file time. The dwHighDateTime holds the high-order part of the file time.
The LARGE_INTEGER is a union which helps us to convert the members of the FILETIME structure to 100-nanosecond intervals.
The values of the FILETIME structure are copied to the large integer union members.
The QuadPart member stores the number of hundreds of nanoseconds determined from the LowPart and HighPart members. It is a huge number stored as a 64-bit integer.
The value is printed to the console.
This is the sample output.
The following example converts the Windows API time into Unix time.
The example prints the Windows API time and the Unix time to console.
The difference between the two epochs is 11644473600LL . Note that leap seconds were introduced in 1972, so we do not take them into account.
The function translates windows ticks into unix time seconds.
This is the output of the UnixTime.exe example.
Days until XMas
The Windows API does not have any functions to calcuate the difference between two days. We have to do the math ourselves.
The code example computes the number of days until the Christmas.
We need FILETIME , SYSTEMTIME structures and LARGE_INTEGER unions to do our computations.
The SYSTEMTIME structure is filled with the values for the Christmas day.
The system time for the Christmas day is converted to file time.
We get the current date as a file time using the GetSystemTimeAsFileTime() function.
We fill the two unions with the low-order and high-order parts of the file time.
The difference between the two dates is computed.
The difference is expressed in 100-nanoseconds. This value is converted to days.
On January 31, 2016 we get this output.
Comparing times
The CompareFileTime() function can be used to compare two file times. The function returns -1 when the first time specified is earlier. It returns 0, when the two times are equal. And it returns 1 when the first time is later than the second file time.
We have two time values. We use the CompareFileTime() to figure out which time is earlier.
The two times are defined.
The system times are converted to file times using the SystemTimeToFileTime() function calls.
The two file times are compared with the CompareFileTime() function.
Depending on the returned value, we print a message to the console.
This is the output of the CompareTime.exe program.
Time zones
A time zone is a region throughout which the same standard time is used. There are 24 time zones in the world.
The bias is the difference, in minutes, between UTC time and local time.
Retrieving time zone
The GetTimeZoneInformation() is used to get time zone information. The information is stored in the TIME_ZONE_INFORMATION structure.
The example prints the user’s time zone.
The TIME_ZONE_INFORMATION structure stores settings for a time zone.
The GetTimeZoneInformation() function retrieves the current time zone settings.
The StandardName member of the TIME_ZONE_INFORMATION structure stores the name of our time zone.
We print the bias value.
Our time zone is Central Europe Standard Time (CEST) and the bias is -60 minutes.
Converting local time to universal time
The TzSpecificLocalTimeToSystemTime() function converts local time to UTC time. The function takes into account whether daylight saving time (DST) is in effect for the local time to be converted.
The example converts the local time into the universal time.
The current local time is retrieved with the GetLocalTime() function.
The time zone settings are determined with the GetTimeZoneInformation() function.
The TzSpecificLocalTimeToSystemTime() translates local time into universal time, taking daylight saving into account.
The local time is printed to console.
The universal time is printed to console.
In the CEST time zone, on February 1, 2016, we get the above output.
In this part of the Windows API tutorial, we have worked with date & time.
