InitializeDateItem

Overview

InitializeDateItem creates and initializes a new date item from either a FILETIME or LARGE_INTEGER representation, with automatic validation to ensure the date is a valid market day (not a weekend or holiday).

Purpose

This function serves as the primary interface for creating date items within the date log system. It ensures that all created date items represent valid market trading days by:

• Validating the supplied date log handle and parameter consistency
• Checking that the date is not a weekend (Saturday or Sunday)
• Verifying that the date is not in the holidays list
• Creating and allocating a new DATE_ITEM structure
• Enforcing a post-call contract to guarantee valid output

Key Features

• Flexible date input: accepts either FILETIME or LARGE_INTEGER
• Automatic weekend and holiday detection
• SAL annotations for parameter validation and return value inspection
• Comprehensive error reporting with distinct error codes
• Post-call contract validation ensuring output consistency

Function Signature

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

Calling Convention

Standard C calling convention with SAL annotations for strict parameter validation and output guarantees.

Parameters

Return Values

Success Cases

Date item was successfully created and initialized. The *hDateItem parameter contains a valid handle to the new date item representing a market day.

Error Cases - Input Validation

The hDateLogHandle is invalid or does not reference a valid date log context. This occurs when:

• IsValidDateLogHandle(hDateLogHandle) returns FALSE
• The handle context is NULL or corrupted
• The post-call contract validation fails (handle claims success but output is NULL)

Invalid parameter combination. This occurs when:

• Both pFileTime and pLargeInteger are NULL
• hDateItem is NULL
• The selected handle type is HOLIDAYS_HANDLE (cannot create items from holidays)

Error Cases - Date Validation

The provided date represents a weekend (Saturday or Sunday) or is listed in the holidays collection. Market trading does not occur on these days, so the date item cannot be created.

Unexpected error during holiday or market day validation. This typically indicates a failure in IsFiletimeMarketHoliday() or internal date conversion routines.

Error Cases - Internal Operations

The handle type is invalid or not supported for date item creation. This can occur if:

• A HOLIDAYS_HANDLE is passed instead of a DATE_LOG_HANDLE or DATE_RANGE_HANDLE
• The magic number validation fails

Return Value Checking

// Recommended error checking pattern
DATE_ITEM_HANDLE hNewDate = NULL;

HRESULT hr = InitializeDateItem(
    hDateLog,
    &fileTime,
    NULL,
    &hNewDate
);

if (SUCCEEDED(hr) && hNewDate != NULL) {
    // Date item successfully created
    printf("Date item created successfully\n");
    // Use hNewDate...
    FreeDateItem(hNewDate);
} else if (hr == ERR_DATE_IS_HOLIDAY) {
    printf("Cannot create date item - weekend or holiday\n");
} else if (FAILED(hr)) {
    printf("Failed to create date item: 0x%08X\n", hr);
}

Behavior and Operations

Execution Flow

Step 1: Parameter Validation

The function first validates input parameters:

• hDateLogHandle must be valid via IsValidDateLogHandle()
• At least one of pFileTime or pLargeInteger must be provided (mutual exclusivity)
• hDateItem output pointer must not be NULL
• Output is initialized to NULL for safety

Step 2: Handle Type Verification

The function determines and validates the handle type:

• HOLIDAYS_HANDLE: Rejected immediately; holidays cannot be used to initialize date items
• DATE_LOG_HANDLE: Validated and accepted; uses embedded holidays reference
• DATE_RANGE_HANDLE: Validated and accepted; uses embedded holidays reference

Step 3: Date Validation Against Holidays

The function checks that the provided date is a valid market day:

If pFileTime is provided:

• Call IsFiletimeMarketHoliday(pFileTime, pHolidays)
• Return value -1 indicates error; return ERROR_UNIDENTIFIED_ERROR
• Return value > 0 indicates holiday/weekend; return ERR_DATE_IS_HOLIDAY
• Return value 0 indicates market day; proceed to creation

If pLargeInteger is provided:

• Convert LARGE_INTEGER to FILETIME via LARGE_INTEGER_TO_FILETIME macro
• Call IsFiletimeMarketHoliday() on the converted FILETIME
• Apply same validation logic as above

Step 4: Date Item Creation

Once validated, create the new date item:

• Call NewDateItem(pFileTime, pLargeInteger, hDateItem)
• Returns HRESULT with status code

Step 5: Post-Call Contract Verification

Immediately after creation, enforce the output contract:

• If function reports success (SUCCEEDED(hr)) but *hDateItem == NULL, return ERROR_INVALID_HANDLE
• This catches violations in NewDateItem() implementation
• Guarantees to caller that success always means non-NULL output

Holiday and Weekend Checking

The function classifies dates as holidays if they are:

1. Weekends: Day of week is SATURDAY (6) or SUNDAY (0)
2. Market Holidays: Date appears in the holidays collection provided by the context

Validation Details

Holiday Resolution Process

When IsFiletimeMarketHoliday() is called, it returns one of three values:

Handle Validation Sequence

The function validates handles in this order:

1. Check IsValidDateLogHandle(hDateLogHandle) — immediate rejection if false
2. Extract context from handle and verify it is not NULL
3. Determine handle type from context magic number
4. For DATE_LOG and DATE_RANGE types, extract holidays reference from context
5. For HOLIDAYS type, immediately return ERR_INVALID_DATELOG_HANDLE
6. Verify holidays handle is valid before using it

Parameter Mutual Exclusivity

The SAL annotations enforce that exactly one date input is provided:

• If pFileTime is provided, pLargeInteger must be NULL
• If pLargeInteger is provided, pFileTime must be NULL
• If both are NULL, function returns ERROR_INVALID_PARAMETER

Usage Examples

// Get current date in FILETIME format
SYSTEMTIME st = { 0 };
GetLocalTime(&st);
st.wHour = st.wMinute = st.wSecond = st.wMilliseconds = 0;

FILETIME ft = { 0 };
SystemTimeToFileTime(&st, &ft);

// Create date item (will fail if today is a weekend or holiday)
DATE_ITEM_HANDLE hDate = NULL;
HRESULT hr = InitializeDateItem(hDateLog, &ft, NULL, &hDate);

if (SUCCEEDED(hr) && hDate != NULL) {
    printf("Successfully created date item for today\n");
    FreeDateItem(hDate);
} else if (hr == ERR_DATE_IS_HOLIDAY) {
    printf("Today is not a market day\n");
} else {
    printf("Error: 0x%08X\n", hr);
}

// Create a date for a specific day using LARGE_INTEGER
// Windows FILETIME = 100-nanosecond intervals since 1601-01-01
LARGE_INTEGER li = { 0 };

// For example: 132700000000000000 represents a specific date
li.QuadPart = 132700000000000000LL;

DATE_ITEM_HANDLE hDate = NULL;
HRESULT hr = InitializeDateItem(hDateLog, NULL, &li, &hDate);

if (SUCCEEDED(hr) && hDate != NULL) {
    printf("Date item created from LARGE_INTEGER\n");
    FreeDateItem(hDate);
}

// Try to create a date item, retry with next day if it's a holiday
DATE_ITEM_HANDLE hDate = NULL;
LARGE_INTEGER liDate = { 0 };

// Start with a target date
liDate.QuadPart = 132700000000000000LL;

// Attempt creation; if it's a holiday, try the next day
for (int attempts = 0; attempts < 10; attempts++) {
    HRESULT hr = InitializeDateItem(hDateLog, NULL, &liDate, &hDate);
    
    if (SUCCEEDED(hr) && hDate != NULL) {
        printf("Found valid market day\n");
        FreeDateItem(hDate);
        break;
    } else if (hr == ERR_DATE_IS_HOLIDAY) {
        // Skip to next day (86400000000000 = 1 day in 100-nanosecond units)
        liDate.QuadPart += 86400000000000LL;
        printf("Skipping holiday, trying next day\n");
    } else {
        printf("Error creating date item: 0x%08X\n", hr);
        break;
    }
}

DATE_ITEM_HANDLE hDate = NULL;
FILETIME ft = { 0 };
SystemTimeToFileTime(&st, &ft);

// Works with DATE_LOG_HANDLE
HRESULT hr1 = InitializeDateItem(hDateLog, &ft, NULL, &hDate);

// Works with DATE_RANGE_HANDLE
HRESULT hr2 = InitializeDateItem(hDateRange, &ft, NULL, &hDate);

// FAILS with HOLIDAYS_HANDLE - returns ERR_INVALID_DATELOG_HANDLE
HRESULT hr3 = InitializeDateItem(hHolidays, &ft, NULL, &hDate);
if (hr3 == ERR_INVALID_DATELOG_HANDLE) {
    printf("Cannot use holidays handle to create date items\n");
}

Notes and Remarks

Thread Safety

InitializeDateItem is thread-safe. It acquires the holidays context mutex internally via IsFiletimeMarketHoliday() to safely access the shared holidays list. Multiple threads can simultaneously call this function on the same date log handle.

Resource Management

On successful return, the caller assumes ownership of the returned DATE_ITEM_HANDLE and must call FreeDateItem(hDate) when done to release memory and resources.

Date Arithmetic

When constructing LARGE_INTEGER dates, remember:

• Windows FILETIME uses 100-nanosecond intervals since January 1, 1601
• One day = 86,400,000 seconds = 864,000,000,000,000 (0xC32A43F0) 100-nanosecond intervals
• Use LARGE_INTEGER_TO_FILETIME macro to convert safely

Time Components Ignored

The function ignores all time components (hours, minutes, seconds, milliseconds) from the input. It extracts only the date portion for validation and storage. This ensures that all date items represent "day-level" granularity regardless of input time precision.

Error Precedence

The function checks errors in this priority order:

1. Handle validation errors (ERROR_INVALID_HANDLE)
2. Parameter consistency errors (ERROR_INVALID_PARAMETER)
3. Handle type incompatibility (ERR_INVALID_DATELOG_HANDLE)
4. Market day validation errors (ERR_DATE_IS_HOLIDAY)
5. Internal operation errors (ERROR_UNIDENTIFIED_ERROR)
6. Post-call contract violations (ERROR_INVALID_HANDLE)

Contract Guarantee

The _Success_ SAL annotation documents the contract: hDateItem != NULL && SUCCEEDED(return). This means:

• If the function returns success, *hDateItem is guaranteed to be non-NULL
• If the function returns failure, *hDateItem is guaranteed to be NULL
• This contract is enforced at runtime by the post-call validation check

Related Functions

• NewDateItem() — Low-level date item creation (called internally)
• FreeDateItem() — Release date item resources
• IsFiletimeMarketHoliday() — Market day validation
• InitializeDateLogHandle() — Create date log context
• IsValidDateLogHandle() — Validate handle integrity