GetDateCollectionLength

Overview

GetDateCollectionLength returns the current (populated) length of the date log core underlying a DATE_LOG_HANDLE, DATE_RANGE_HANDLE, or HOLIDAYS_HANDLE.

Purpose

Use it to find out how many date items a collection currently holds, for example to size a buffer, to report progress, or to test whether a collection has been populated yet. It reports the populated count; for the allocated capacity use GetDateCollectionMaximumLength().

Key Features

• Accepts any collection handle type (DATE_COLLECTION_HANDLE)
• Validates and locks the handle for a consistent read
• Reports failure in-band with DATE_LOG_SENTINEL, which is greater than DATE_LOG_MAX

Function Signature

DWORD _Check_return_ _On_failure_(return > DATE_LOG_MAX) GetDateCollectionLength(
    _In_ DATE_COLLECTION_HANDLE hDateCollection
);

Parameters

Return Values

The function returns a DWORD, not an HRESULT. Compare the result against DATE_LOG_MAX (the _On_failure_ contract), not with FAILED/SUCCEEDED.

Behavior and Operations

The handle is validated and locked, the length is read from the underlying core with the internal GetDateLogCoreLength(), and the handle is unlocked again before returning.

Remarks

• Thread safety: the read happens under the handle's lock, so it is consistent at the moment of the call. The value can be stale as soon as another thread loads or merges dates into the same collection, so do not treat it as a stable bound without external coordination.
• Handle lifetime / reference counting: the call neither duplicates nor closes the handle; the shared context is released only when the last handle referencing it is closed with CloseDateLogHandle().
• Lock contention: failure to acquire the lock (for example when another thread holds it) is reported as DATE_LOG_SENTINEL, the same as an invalid handle; retry later if the handle is known to be valid.
• Related: GetDateCollectionMaximumLength() returns the allocated capacity; IsValidDateLogHandle() can be used to separate "invalid handle" from a transient lock failure.

See Also

• GetDateCollectionMaximumLength
• LoadDateLogHandle
• InitializeDateLogHandle
• DuplicateDateLogHandle
• CloseDateLogHandle
• IsValidDateLogHandle
• GetDateLogHolidayHandle
• FindDateItemHandle
• datelog.h

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 hStart = NULL;
    DATE_ITEM_HANDLE hEnd = NULL;
    FILETIME         ftStart = { 0 };
    FILETIME         ftEnd = { 0 };
    HRESULT          hr = E_FAIL;
    int              exitCode = 1;
    DWORD            dwLength = 0;
    DWORD            dwMaximum = 0;

    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, 1, 5, &ftStart) || !MakeFiletime(2026, 3, 31, &ftEnd)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        goto cleanup;
    }

    /* Standalone date items; the caller owns them and frees them with FreeDateItem. */
    hr = InitializeDateItem(hHolidays, &ftStart, NULL, &hStart);
    if (FAILED(hr)) {
        printf("InitializeDateItem [start] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = InitializeDateItem(hHolidays, &ftEnd, NULL, &hEnd);
    if (FAILED(hr)) {
        printf("InitializeDateItem [end] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    /* The holidays collection is populated first, then the date log over the same range. */
    hr = LoadDateLogHandle(NULL, hStart, hEnd, hHolidays, NULL, 0);
    if (FAILED(hr)) {
        printf("LoadDateLogHandle [holidays] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    hr = LoadDateLogHandle(NULL, hStart, hEnd, hDateLog, NULL, 0);
    if (FAILED(hr)) {
        printf("LoadDateLogHandle [date log] failed: 0x%08lX\n", (unsigned long)hr);
        goto cleanup;
    }

    if (!IsValidDateLogHandle(hDateLog)) {
        printf("The date log handle is not valid.\n");
        goto cleanup;
    }

    /* Failure is reported in-band: DATE_LOG_SENTINEL, which is greater than DATE_LOG_MAX. */
    dwLength = GetDateCollectionLength(hDateLog);
    if (dwLength > DATE_LOG_MAX) {
        printf("GetDateCollectionLength failed (invalid handle or lock failure).\n");
        goto cleanup;
    }
    printf("Date log holds %lu date items.\n", (unsigned long)dwLength);

    /* Any collection handle works, including the holidays handle. */
    dwLength = GetDateCollectionLength(hHolidays);
    if (dwLength > DATE_LOG_MAX) {
        printf("GetDateCollectionLength failed for the holidays handle.\n");
        goto cleanup;
    }
    printf("Holidays collection holds %lu date items.\n", (unsigned long)dwLength);

    /* Re-read the date log length so it can be compared with the capacity. */
    dwLength = GetDateCollectionLength(hDateLog);
    dwMaximum = GetDateCollectionMaximumLength(hDateLog);
    if (dwLength > DATE_LOG_MAX || dwMaximum > DATE_LOG_MAX) {
        printf("Unable to read the collection length or capacity.\n");
        goto cleanup;
    }
    printf("Date log: %lu of %lu items in use.\n", (unsigned long)dwLength, (unsigned long)dwMaximum);
    exitCode = 0;

cleanup:
    FreeDateItem(hEnd);
    FreeDateItem(hStart);
    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;
}