Retrieve a date item's value as a SYSTEMTIME
GetDateItemSystemTime converts the date item's internal FILETIME to a SYSTEMTIME by calling the Windows API FileTimeToSystemTime() and stores the result in a caller-supplied structure.
Gives callers a broken-down calendar representation (year, month, day, day of week, and time of day) of a date item for display, logging or calendar arithmetic, without converting the FILETIME themselves.
BOOL; on failure the output structure is zeroed so stale or uninitialized data is never observed.
BOOL _Check_return_ _Success_(return == TRUE) GetDateItemSystemTime(
_In_ DATE_ITEM_HANDLE hDateItem,
_Out_ LPSYSTEMTIME pSystemTime
);
[In] DATE_ITEM_HANDLE
The date item to query. Must not be NULL (the function returns FALSE).
The handle is only read; ownership is unchanged. Standalone items from InitializeDateItem must still be released with FreeDateItem.
[Out] LPSYSTEMTIME
Pointer to a caller-allocated SYSTEMTIME that receives the converted date. Must not be NULL (the function returns FALSE).
The library does not retain the pointer. On failure the structure is cleared with memset().
| Value | Meaning |
|---|---|
TRUE | *pSystemTime was populated successfully. |
FALSE | hDateItem or pSystemTime is NULL, or FileTimeToSystemTime() failed. |
*pSystemTime is explicitly zeroed via memset() so callers never observe stale/garbage data.wMonth and wDay are 0). Always check the return value rather than testing the structure.The function operates on a date item handle and a caller-owned buffer; no locking is described. Do not free the date item concurrently with this call, and do not share the output structure between threads.
The SYSTEMTIME is a copy owned by the caller and remains valid after the date item is freed.
The value is the direct FileTimeToSystemTime() conversion of the item's FILETIME; no local time zone conversion is performed by this function.
#include <stdio.h>
#include <Windows.h>
#include "datelog.h"
/* Builds a FILETIME for midnight (UTC) of the given calendar date. */
static BOOL MakeFiletime(WORD wYear, WORD wMonth, WORD wDay, FILETIME *pFileTime)
{
SYSTEMTIME st = { 0 };
st.wYear = wYear;
st.wMonth = wMonth;
st.wDay = wDay;
return SystemTimeToFileTime(&st, pFileTime);
}
int main(void)
{
HRESULT hr = E_FAIL;
HOLIDAYS_HANDLE hHolidays = NULL;
DATE_LOG_HANDLE hDateLog = NULL;
DATE_ITEM_HANDLE hDateItem = NULL;
FILETIME ft = { 0 };
SYSTEMTIME st = { 0 };
int exitCode = 1;
/* A holidays handle is created with HandleIsForHolidays; hHolidays must be NULL for that type. */
hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, NULL, &hHolidays, HandleIsForHolidays);
if (FAILED(hr)) {
printf("Holidays handle creation failed: 0x%08lX\n", (unsigned long)hr);
goto cleanup;
}
/* The date log duplicates hHolidays internally; the caller still owns hHolidays. */
hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hDateLog, HandleIsForDatelog);
if (FAILED(hr)) {
printf("Date log creation failed: 0x%08lX\n", (unsigned long)hr);
goto cleanup;
}
if (!MakeFiletime(2026, 10, 13, &ft)) {
printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
goto cleanup;
}
hr = InitializeDateItem(hDateLog, &ft, NULL, &hDateItem);
if (FAILED(hr)) {
printf("InitializeDateItem failed: 0x%08lX\n", (unsigned long)hr);
goto cleanup;
}
if (!GetDateItemSystemTime(hDateItem, &st)) {
printf("GetDateItemSystemTime failed.\n");
goto cleanup;
}
printf("Date: %04u-%02u-%02u (day of week %u)\n",
st.wYear, st.wMonth, st.wDay, st.wDayOfWeek);
printf("Time: %02u:%02u:%02u.%03u\n",
st.wHour, st.wMinute, st.wSecond, st.wMilliseconds);
exitCode = 0;
cleanup:
if (hDateItem != NULL) {
FreeDateItem(hDateItem);
}
if (hDateLog != NULL) {
CloseDateLogHandle(hDateLog);
}
if (hHolidays != NULL) {
CloseDateLogHandle(hHolidays);
}
return exitCode;
}