GetDateItemFiletime Function Documentation

Overview

GetDateItemFiletime copies the date item's internal FILETIME into the caller-supplied buffer.

Purpose

The FILETIME is the library's native representation of a date item (see DATE_ITEM): the 64-bit count of 100-nanosecond intervals since January 1, 1601. It is the key used by FindDateItemHandle() for binary-search lookups and by CompareDateItem() for ordering, so reading it is the usual first step when you need to search for, compare, or persist an item's date.

Function Signature


BOOL _Success_(pFiletime != NULL && return == TRUE) GetDateItemFiletime(
    _In_  DATE_ITEM_HANDLE hDateItem,
    _Out_ PFILETIME        pFiletime
);

Parameters

hDateItem

[In] DATE_ITEM_HANDLE

The date item to query.

NULL: not allowed; the function returns FALSE.
Valid values: an initialized date item, standalone or resident in a collection. An item whose FILETIME is zero/uninitialized is rejected.
Ownership/lifetime: not retained or modified.

pFiletime

[Out] PFILETIME

Receives the item's FILETIME value.

NULL: not allowed; the function returns FALSE.
Ownership: caller-allocated; the value is copied, so it stays valid after the item is freed.
On failure: the contents of *pFiletime are not specified; do not use them.

Return Values

The function returns a BOOL, not an HRESULT. Test it directly; do not use FAILED/SUCCEEDED.

Return value	Meaning
`TRUE`	`pFiletime` was populated successfully.
`FALSE`	`hDateItem` or `pFiletime` is NULL, or the item's FILETIME is zero/uninitialized.

Behavior and Operations

Validate arguments

→

Read item FILETIME

→

Copy to caller buffer

No error HRESULT is produced. The value is copied by value into *pFiletime; no pointer into the item is exposed.

Remarks

Thread safety: the function reads the item only and takes no date log handle lock. Date items are immutable after creation, so concurrent reads are safe provided the item is not freed in the meantime.
Handle lifetime: for a handle that points into a collection, the item is valid only while the collection is neither freed nor mutated; the returned FILETIME is a plain value and remains valid afterwards.
Searching: pass the retrieved value to FindDateItemHandle() as pFiletime to locate the entry in a collection.
Related: GetDateItemLargeInteger() returns the same value as a LARGE_INTEGER; GetDateItemSystemTime() and GetDateItemDate() return calendar forms.

Header note: datelog.h shows this function as void _Success_(pFiletime != NULL). This page documents the BOOL form, which reports failure for NULL arguments or an uninitialized item.

Sample Code


#include <Windows.h>
#include <stdio.h>
#include "datelog.h"

static BOOL MakeFiletime(WORD wYear, WORD wMonth, WORD wDay, PFILETIME pFiletime)
{
    SYSTEMTIME st = { 0 };

    st.wYear = wYear;
    st.wMonth = wMonth;
    st.wDay = wDay;
    return SystemTimeToFileTime(&st, pFiletime);
}

int main(void)
{
    HOLIDAYS_HANDLE  hHolidays = NULL;
    DATE_LOG_HANDLE  hDateLog = NULL;
    DATE_ITEM_HANDLE hItem = NULL;
    FILETIME         ftInput = { 0 };
    FILETIME         ftOutput = { 0 };
    HRESULT          hr = E_FAIL;
    int              exitCode = 1;

    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, NULL, &hHolidays, HandleIsForHolidays);
    if (FAILED(hr)) {
        printf("InitializeDateLogHandle [holidays] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = InitializeDateLogHandle(NULL, DATE_LOG_MAX, hHolidays, &hDateLog, HandleIsForDatelog);
    if (FAILED(hr)) {
        printf("InitializeDateLogHandle [date log] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    if (!MakeFiletime(2026, 10, 13, &ftInput)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        goto cleanup;
    }

    hr = InitializeDateItem(hDateLog, &ftInput, NULL, &hItem);
    if (hr == ERR_DATE_IS_HOLIDAY) {
        printf("2026-10-13 is a weekend or market holiday.\n");
        goto cleanup;
    }
    if (FAILED(hr)) {
        printf("InitializeDateItem failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* GetDateItemFiletime returns BOOL, so test it directly rather than with FAILED. */
    if (!GetDateItemFiletime(hItem, &ftOutput)) {
        printf("GetDateItemFiletime failed (NULL argument or uninitialized item).\n");
        goto cleanup;
    }

    printf("FILETIME: 0x%08lX%08lX\n",
           (unsigned long)ftOutput.dwHighDateTime, (unsigned long)ftOutput.dwLowDateTime);

    /* CompareFiletime follows strcmp() conventions: 0 means equal. */
    if (CompareFiletime(&ftInput, &ftOutput) != 0) {
        printf("The item's FILETIME differs from the one it was created with.\n");
    }
    exitCode = 0;

cleanup:
    FreeDateItem(hItem);
    if (hDateLog != NULL) {
        hr = CloseDateLogHandle(hDateLog);
        if (FAILED(hr)) {
            printf("CloseDateLogHandle [date log] failed: 0x%08lX\n", (unsigned long)hr);
        }
    }
    if (hHolidays != NULL) {
        hr = CloseDateLogHandle(hHolidays);
        if (FAILED(hr)) {
            printf("CloseDateLogHandle [holidays] failed: 0x%08lX\n", (unsigned long)hr);
        }
    }
    return exitCode;
}