InitializeDateItem

Create a new, validated date item from a FILETIME or LARGE_INTEGER

Documentation / Functions / InitializeDateItem

Overview

InitializeDateItem creates a new DATE_ITEM_HANDLE from either a FILETIME or a LARGE_INTEGER, after verifying that the resulting date is not a market holiday according to the holidays handle associated with (or directly supplied as) hDateLogHandle.

Purpose

Ensures date items are never constructed for holiday dates, centralizing holiday validation at creation time rather than relying on callers to check separately. The new item is a standalone item that can be compared (CompareDateItem), queried with the GetDateItem* accessors, used for lookups, or passed to LoadDateLogHandle as a start or end date.

Key Features

Function Signature


HRESULT _Must_inspect_result_ _Success_(hDateItem != NULL && SUCCEEDED(return)) InitializeDateItem(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE hDateLogHandle,
    _In_opt_ PFILETIME pFileTime,
    _In_opt_ PLARGE_INTEGER pLargeInteger,
    _Out_    DATE_ITEM_HANDLE * hDateItem
);

Parameters

hDateLogHandle

[In] DATE_COLLECTION_HANDLE

A valid DATE_LOG_HANDLE, DATE_RANGE_HANDLE, or HOLIDAYS_HANDLE supplying the market calendar for holiday verification (see datelog.h, where the same parameter is declared DATE_LOG_HANDLE).

Must not be NULL and must be valid (_Pre_valid_). The handle is locked for the duration of the call and is not closed or modified. Ownership stays with the caller.

pFileTime

[In, Optional] PFILETIME

FILETIME representation of the date. Required if pLargeInteger is NULL. The value is read and copied; the caller keeps ownership of the buffer.

pLargeInteger

[In, Optional] PLARGE_INTEGER

LARGE_INTEGER representation of the date (100-nanosecond intervals since January 1, 1601). Required if pFileTime is NULL. The value is read and copied; the caller keeps ownership of the buffer.

Supply exactly one of pFileTime and pLargeInteger; if both are NULL the call fails with ERROR_INVALID_PARAMETER.

hDateItem

[Out] DATE_ITEM_HANDLE *

Receives the newly allocated date item handle. Must not be NULL. Set to NULL on failure.

The caller owns the returned item and must release it exactly once with FreeDateItem. The item remains valid after hDateLogHandle is closed.

Return Values

ValueMeaning
S_OKDate item created successfully; *hDateItem is non-NULL.
HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)Both pFileTime and pLargeInteger are NULL, or hDateLogHandle/hDateItem is NULL.
ERR_DATE_IS_HOLIDAYThe supplied date resolves to a market holiday (or weekend).
ERR_INVALID_DATELOG_HANDLEhDateLogHandle is invalid or of the wrong type.
ERR_INVALID_HOLIDAY_HANDLEThe associated holidays handle is invalid.
ERR_* values are defined in date_error_h. Always use FAILED/SUCCEEDED on the result.

Behavior and Operations

Validate & Lock Handle
→
Resolve Holidays Handle
→
Check Holiday Status
→
NewDateItem()
→
Unlock & Return

Holidays Resolution

If the handle passed directly is itself a HOLIDAYS_HANDLE, it is used as-is (already locked). Otherwise, the holidays handle from the DATE_LOG/RANGE context is separately validated and locked, then unlocked once the holiday check completes — independent of the outer handle's own lock/unlock cycle.

Notes

On failure, any partially-created date item is freed via FreeDateItem() before returning, so *hDateItem is guaranteed NULL on failure.

Remarks

Thread Safety

The handle is validated and locked internally, so the call can be made while other threads use the same context through their own handles (see DuplicateDateLogHandle). If the handle is busy, other functions report ERR_DATE_LOG_PENDING_IO; check the result of this call and retry if appropriate.

Ownership and Lifetime

Each successful call allocates one standalone date item. Free it with FreeDateItem. Items stored inside a date log are owned by the log and are not released by FreeDateItem; GetDateItemCopy returns a standalone copy that must be freed.

Ordering

Create the holidays handle and the date log first with InitializeDateLogHandle. Create items, use them, free them, and only then close the date log with CloseDateLogHandle.

Other pages in this help set (for example DATE_ITEM and FreeDateItem) show older call forms such as InitializeDateItem(2026, 10, 13). Those do not match the signature above, which agrees with datelog.h.

See Also

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 hOtherItem = NULL;
    FILETIME ft = { 0 };
    LARGE_INTEGER li = { 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;
    }

    /* 1. Create an item from a FILETIME (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;
    }

    if (GetDateItemSystemTime(hDateItem, &st)) {
        printf("Created item for %04u-%02u-%02u\n", st.wYear, st.wMonth, st.wDay);
    }

    /* 2. Create a second item from a LARGE_INTEGER (Wednesday, October 14, 2026). */
    if (!MakeFiletime(2026, 10, 14, &ft)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        goto cleanup;
    }
    li.LowPart = ft.dwLowDateTime;
    li.HighPart = (LONG)ft.dwHighDateTime;

    hr = InitializeDateItem(hDateLog, NULL, &li, &hOtherItem);
    if (SUCCEEDED(hr)) {
        printf("CompareDateItem: %d\n", CompareDateItem(hDateItem, hOtherItem));
        FreeDateItem(hOtherItem);
        hOtherItem = NULL;
    } else if (hr == ERR_DATE_IS_HOLIDAY) {
        printf("October 14, 2026 is a holiday.\n");
    } else {
        printf("Creating item from LARGE_INTEGER failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* 3. A Saturday is rejected as a non-market day; hOtherItem stays NULL. */
    if (!MakeFiletime(2026, 10, 17, &ft)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        goto cleanup;
    }

    hr = InitializeDateItem(hDateLog, &ft, NULL, &hOtherItem);
    if (hr == ERR_DATE_IS_HOLIDAY) {
        printf("Saturday rejected with ERR_DATE_IS_HOLIDAY (item is %s).\n",
               hOtherItem == NULL ? "NULL" : "not NULL");
    } else if (SUCCEEDED(hr)) {
        FreeDateItem(hOtherItem);
        hOtherItem = NULL;
    }

    /* 4. Supplying neither a FILETIME nor a LARGE_INTEGER is an invalid call. */
    hr = InitializeDateItem(hDateLog, NULL, NULL, &hOtherItem);
    if (hr == HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)) {
        printf("No date supplied: ERROR_INVALID_PARAMETER.\n");
    }

    exitCode = 0;

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