InitializeDateLogHandle

Overview

InitializeDateLogHandle creates and initializes a new DATE_LOG_HANDLE for managing date collections with support for three distinct handle types: DateLog, DateRange, and Holidays. The function establishes a thread-safe, shared context with mutex-based synchronization and reference counting to enable concurrent access from multiple threads.

Purpose

This is the primary entry point for creating date collection handles. It allocates necessary structures, initializes synchronization primitives, and establishes the foundation for all date operations within the MDTS library.

Key Features

• Three handle types: DateLog, DateRange, and Holidays
• Thread-safe through mutex-based synchronization
• Reference counting for shared context management
• Optional security attributes support
• Configurable maximum collection size
• Automatic critical section initialization

Function Signature

                HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return)) InitializeDateLogHandle(
                 _In_opt_  PSECURITY_ATTRIBUTES                                                pSecAttr,
                 _In_opt_ _Pre_satisfies_(dwMaximumLength <= DATE_LOG_MAX) const DWORD         dwMaximumLength,
                 _In_opt_ _When_(HandleType == HandleIsForDatelog, _Notnull_ _Valid_)          HOLIDAYS_HANDLE hHolidays,
                 _Out_ DATE_LOG_HANDLE                                                         *hDateLogHandle,
                 _In_ DateHandleType                                                           HandleType
                );
            

Calling Convention

Standard C calling convention with SAL annotations for parameter validation and return value inspection.

Parameters

Return Values

Success

Handle created successfully. hDateLogHandle contains valid pointer to new handle.

Validation Errors

Invalid parameter provided:

• dwMaximumLength exceeds DATE_LOG_MAX
• HandleType is not a valid DateHandleType value
• hDateLogHandle is NULL
• For DateLog/DateRange: hHolidays is NULL
• For Holidays: hHolidays is not NULL

hHolidays handle is invalid or corrupted. Handle must be previously created by InitializeDateLogHandle.

Resource Allocation Errors

Insufficient memory to allocate handle structures, context, or mutexes. Check available system memory.

System error from mutex creation or security validation. Wrapped as HRESULT.

Behavior and Operations

Initialization Process

1. Validate input parameters
2. Allocate DATE_CONTEXT structure
3. Create primary mutex for context protection
4. Initialize critical section for handle reference counting
5. Allocate DATE_LOG_CORE for date item storage
6. Create core protection mutex
7. Set magic number based on handle type
8. If holidays provided: duplicate holidays handle
9. Create DATE_LOG structure (public handle)
10. Return new handle to caller

Memory Allocation

The function allocates the following structures:

• DATE_CONTEXT: ~256 bytes (context management)
• DATE_LOG_CORE: ~64 bytes (collection metadata)
• DATE_LOG: ~128 bytes (public handle)
• Mutexes: 2 system objects (context + core)
• Critical Section: 1 synchronization object

Synchronization

Three levels of synchronization are established:

• Context Mutex: Protects DATE_CONTEXT and reference counting
• Core Mutex: Protects DATE_LOG_CORE and date items array
• Critical Section: Synchronizes handle count updates

Usage Examples

                    // First, create holidays handle
                    HOLIDAYS_HANDLE hHolidays = NULL;
                    HRESULT hr = InitializeDateLogHandle(
                        NULL,                          // Default security
                        0,                             // Default size (MAX_HOLIDAYS)
                        NULL,                          // No parent holidays needed
                        &hHolidays,
                        HandleIsForHolidays
                    );

                    if (SUCCEEDED(hr)) {
                        // Now create DateLog handle
                        DATE_LOG_HANDLE hDateLog = NULL;
                        hr = InitializeDateLogHandle(
                            NULL,                      // Default security
                            100000,                    // Max 100,000 dates
                            hHolidays,                 // Holidays for validation
                            &hDateLog,
                            HandleIsForDatelog
                        );

                        if (SUCCEEDED(hr)) {
                            printf("DateLog handle created successfully\n");
                            FreeDateCollectionHandle(hDateLog);
                        }

                        FreeDateCollectionHandle(hHolidays);
                    }
               

                    // Create a temporary date range for merging
                    DATE_RANGE_HANDLE hDateRange = NULL;

                    HRESULT hr = InitializeDateLogHandle(
                         NULL,                          // Default security
                        10000,                         // Max 10,000 items for range
                        hHolidays,                     // Holidays handle
                        &hDateRange,
                        HandleIsForRange
                    );

                    if (SUCCEEDED(hr)) {
                        printf("DateRange created successfully\n");
                        FreeDateCollectionHandle(hDateRange);
                    }
                

                    DATE_LOG_HANDLE hDateLog = NULL;

                    HRESULT hr = InitializeDateLogHandle(
                        NULL,                      // pSecAttr
                        500000,                    // dwMaximumLength - EXCEEDS LIMIT!
                        hHolidays,
                        &hDateLog,
                        HandleIsForDatelog
                    );

                    if (hr == HRESULT_FROM_WIN32(ERROR_INVALID_PARAMETER)) {
                            printf("Maximum length exceeds DATE_LOG_MAX\n");
                            // Use default size instead
                        hr = InitializeDateLogHandle(
                            NULL,
                            0,                     // Use default
                            hHolidays,
                            &hDateLog,
                            HandleIsForDatelog
                        );
                    }
               

Thread Safety

Synchronization Primitives

• Mutex per Context: Protects handle count and context state
• Mutex per Core: Protects date items array
• Critical Section: Synchronizes reference count updates
• Interlocked Operations: Used for atomic counter updates

Reference Counting

The context uses reference counting to manage lifetime:

• Initial count: 1 (for creating handle)
• Incremented by: DuplicateDateLogHandle()
• Decremented by: FreeDateCollectionHandle()
• Context freed when count reaches 0

Important Notes

Related Functions

• FreeDateCollectionHandle() - Release handle and decrement reference count
• DuplicateDateLogHandle() - Create additional reference to same context
• LoadDateLogHandle() - Populate handle with dates from file or range
• MergeDateLogHandle() - Merge two handles together