GetDateItemCopy Function Documentation

Overview

GetDateItemCopy allocates a new DATE_ITEM and deep-copies all fields from hDateItem via the COPY_DATE macro, returning a handle that is entirely independent of (not linked to) the source item or its owning date log core.

Purpose

Handles returned by FindDateItemHandle() point directly into a collection's internal array and are only valid while that collection is neither freed nor mutated. GetDateItemCopy turns such a handle into a caller-owned item that can be kept, passed between components, or modified independently.

Key Features

Failure is reported by a NULL return; no HRESULT is produced
The copy is a separate allocation, not part of any core's array
Must be released with FreeDateItem()

Function Signature


DATE_ITEM_HANDLE _Check_return_ _Success_(return != NULL) GetDateItemCopy(
    _In_ DATE_ITEM_HANDLE hDateItem
);

Parameters

hDateItem

[In] DATE_ITEM_HANDLE

The date item to copy.

Type: DATE_ITEM_HANDLE (opaque void*).
NULL: allowed; the function then returns NULL.
Valid values: a standalone item (from InitializeDateItem() or an earlier copy) or an item that lives inside a collection (from FindDateItemHandle()).
Ownership/lifetime: the source is not modified, not freed, and not retained by the copy. If the source lives inside a collection, it must stay valid for the duration of the call.

Return Values

The function returns a handle, not an HRESULT. Test the result against NULL; do not use FAILED/SUCCEEDED on it.

Return value	Meaning
`Non-NULL DATE_ITEM_HANDLE`	A newly allocated, standalone copy owned by the caller.
`NULL`	`hDateItem` is NULL, or the internal allocation failed.

Behavior and Operations

Check Source

→

Allocate DATE_ITEM

→

COPY_DATE Deep Copy

→

Return Copy

No date log handle is involved, so no handle validation or locking is performed. The source item is only read.

Remarks

The returned handle must be released with FreeDateItem() when no longer needed, since it is allocated independently and is not part of any date log core's array.

Thread safety: the function takes no handle lock. If the source lives inside a collection that other threads may mutate or free, keep the collection valid (for example, by holding your own duplicated handle) while copying.
Handle lifetime: the copy is independent of the source item and of its owning core. It is not reference counted and does not change the reference count of any date log handle.
Searching: the copy is a different allocation than the entry in the collection. Do not use it where a handle that points into the collection is required; look up the entry again with FindDateItemHandle() using a FILETIME, LARGE_INTEGER, or GUID instead.
Related: InitializeDateItem() creates a new item from a FILETIME or LARGE_INTEGER (with holiday validation); GetDateItemFiletime() and GetDateItemDate() read values from either the source or the copy.

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 hSource = NULL;
    DATE_ITEM_HANDLE hCopy = NULL;
    FILETIME         ft = { 0 };
    FILETIME         ftCopy = { 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, &ft)) {
        printf("SystemTimeToFileTime failed: %lu\n", GetLastError());
        goto cleanup;
    }

    hr = InitializeDateItem(hDateLog, &ft, NULL, &hSource);
    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;
    }

    /* GetDateItemCopy reports failure by returning NULL (it has no HRESULT). */
    hCopy = GetDateItemCopy(hSource);
    if (hCopy == NULL) {
        printf("GetDateItemCopy failed (NULL source or allocation failure).\n");
        goto cleanup;
    }

    /* The copy is a distinct allocation holding the same date. */
    if (hCopy == hSource) {
        printf("Unexpected: copy and source share the same handle.\n");
        goto cleanup;
    }
    if (CompareDateItem(hSource, hCopy) != 0) {
        printf("Unexpected: copy does not compare equal to the source.\n");
        goto cleanup;
    }

    if (!GetDateItemFiletime(hCopy, &ftCopy)) {
        printf("GetDateItemFiletime failed on the copy.\n");
        goto cleanup;
    }
    printf("Copy FILETIME: 0x%08lX%08lX\n",
           (unsigned long)ftCopy.dwHighDateTime, (unsigned long)ftCopy.dwLowDateTime);
    exitCode = 0;

cleanup:
    /* Both items are standalone, so each is released with FreeDateItem. */
    FreeDateItem(hCopy);
    FreeDateItem(hSource);
    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;
}