GetDateItemLargeInteger Function Documentation

Overview

GetDateItemLargeInteger copies the date represented by a date item into a caller-supplied LARGE_INTEGER. The value is derived from the item's internal FILETIME through the FILETIME_TO_LARGE_INTEGER macro, so it counts 100-nanosecond intervals since January 1, 1601 (UTC), exactly like the FILETIME returned by GetDateItemFiletime.

Purpose

A 64-bit integer is convenient for low-level comparison and arithmetic. For example, adding the DAY_IN_MILLISECONDS constant from datelog.h (the number of 100-nanosecond intervals in one day) moves the value forward by one calendar day. The result can be passed back to InitializeDateItem through its pLargeInteger parameter.

Key Features

Read-only: the date item is not modified.
Returns a plain BOOL; no HRESULT or extended error information is produced.
The output value is the same point in time as the item's FILETIME, SYSTEMTIME (see GetDateItemSystemTime) and the LargeInteger member described in DATE_ITEM.

Function Signature


BOOL _Check_return_ GetDateItemLargeInteger(
    _In_  DATE_ITEM_HANDLE hDateItem,
    _Out_ PLARGE_INTEGER   pLargeInteger
);

Parameters

hDateItem

[In] DATE_ITEM_HANDLE

The date item to query. Must be a valid date item handle, for example one returned by InitializeDateItem or GetDateItemCopy.

NULL is rejected: the function returns FALSE. The handle is only read; ownership is not transferred and the caller remains responsible for releasing standalone items with FreeDateItem.

pLargeInteger

[Out] PLARGE_INTEGER

Pointer to a caller-allocated LARGE_INTEGER that receives the date as a 64-bit value (QuadPart).

Must not be NULL (the function returns FALSE). The buffer is owned by the caller; the library does not retain the pointer.

Return Values

Value	Meaning
`TRUE`	`*pLargeInteger` was populated successfully.
`FALSE`	`hDateItem` or `pLargeInteger` is NULL, or the item's FILETIME is zero/uninitialized. The contents of `*pLargeInteger` must not be used.

The function is annotated _Check_return_: always test the result before using pLargeInteger.

Remarks

Thread Safety

The function takes a date item handle, not a date log handle, and the existing documentation does not describe any locking performed on the item. Do not call FreeDateItem on the same item from another thread while it is being queried.

Ownership and Lifetime

The value is copied into caller storage, so it stays valid after the date item is freed. The date item itself must remain valid for the duration of the call.

Ordering

Create the item first with InitializeDateItem (which requires a valid date log, range or holidays handle). Query it with this function, then release it with FreeDateItem.

Related Accessors

GetDateItemFiletime – same value as a FILETIME.
GetDateItemSystemTime – same value as a SYSTEMTIME.
GetDateItemDate – same date as a DATE_STRUCT.
GetDateItemNumber – ordinal number of the item.

Sample Code


#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;
    DATE_ITEM_HANDLE hNextItem = NULL;
    FILETIME ft = { 0 };
    FILETIME itemFt = { 0 };
    LARGE_INTEGER value = { 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;
    }

    /* Create a date item for Tuesday, October 13, 2026. */
    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;
    }

    /* Read the date as a LARGE_INTEGER. */
    if (!GetDateItemLargeInteger(hDateItem, &value)) {
        printf("GetDateItemLargeInteger failed.\n");
        goto cleanup;
    }
    printf("LARGE_INTEGER value: %lld\n", value.QuadPart);

    /* The value matches the FILETIME of the same item. */
    if (GetDateItemFiletime(hDateItem, &itemFt)) {
        ULARGE_INTEGER u;
        u.LowPart = itemFt.dwLowDateTime;
        u.HighPart = itemFt.dwHighDateTime;
        printf("Matches FILETIME: %s\n", ((LONGLONG)u.QuadPart == value.QuadPart) ? "yes" : "no");
    }

    /* Advance by one day and build a second item from the LARGE_INTEGER. */
    value.QuadPart += DAY_IN_MILLISECONDS;
    hr = InitializeDateItem(hDateLog, NULL, &value, &hNextItem);
    if (SUCCEEDED(hr)) {
        printf("Next calendar day accepted: CompareDateItem = %d\n", CompareDateItem(hDateItem, hNextItem));
        FreeDateItem(hNextItem);
        hNextItem = NULL;
    } else if (hr == ERR_DATE_IS_HOLIDAY) {
        printf("Next calendar day is a weekend or holiday.\n");
    } else {
        printf("Creating item from LARGE_INTEGER failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    exitCode = 0;

cleanup:
    if (hDateItem != NULL) {
        FreeDateItem(hDateItem);
    }
    if (hDateLog != NULL) {
        CloseDateLogHandle(hDateLog);
    }
    if (hHolidays != NULL) {
        CloseDateLogHandle(hHolidays);
    }
    return exitCode;
}