GetDateCollectionMaximumLength

Overview

GetDateCollectionMaximumLength returns the allocated capacity (maximum number of date items the core can hold) of the date log core underlying the given handle, as opposed to GetDateCollectionLength() which returns the current populated count.

Purpose

Use it together with GetDateCollectionLength() to determine how much room a collection has left, or to confirm the capacity of a collection created with a given maximum length. The library-wide upper bound for any collection is DATE_LOG_MAX (0x591C8, 370,120 items).

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) GetDateCollectionMaximumLength(
    _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 capacity is read from the underlying core with the internal GetDateLogCoreMaxLength(), and the handle is unlocked again before returning.

Remarks

• Thread safety: the read happens under the handle's lock. The value can change if another thread alters the collection afterwards, so do not cache it across operations that may resize or reload the collection.
• 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().
• Length versus capacity: GetDateCollectionLength() counts the date items currently stored; this function reports how many the core can hold. Compare the two (after checking both for > DATE_LOG_MAX) to compute remaining room.
• Limits: operations that would push a collection beyond DATE_LOG_MAX fail with ERR_MAX_DATELOG_REACHED (see date_error.h).

See Also

• GetDateCollectionLength
• LoadDateLogHandle
• InitializeDateLogHandle
• DuplicateDateLogHandle
• CloseDateLogHandle
• IsValidDateLogHandle
• GetDateLogHolidayHandle
• datelog.h
• date_error.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;
}