FindDateItemHandle Function Documentation

Overview

FindDateItemHandle is a dispatcher function that searches for a date item within a date collection using one of four supported search criteria. It provides a unified interface for flexible date item lookup operations with automatic synchronization and handle validation.

Purpose

This function enables applications to locate specific date items within a date log collection using different search strategies:

By Handle: Direct lookup using another DATE_ITEM_HANDLE
By FILETIME: Locate by Windows FILETIME value (optimized binary search on sorted array)
By LARGE_INTEGER: Locate by arbitrary large integer date representation
By GUID: Locate by unique identifier (linear search on unsorted array)

Key Features

Multiple search strategies optimized for different key types
Automatic handle validation before dispatch
Mutex-protected search operations for thread safety
Efficient binary search for sorted FILETIME/LARGE_INTEGER keys
Linear scan with timeout protection for GUID lookup

Function Signature

DATE_ITEM_HANDLE _Check_return_ _Success_(return != NULL) FindDateItemHandle(
    _In_ _Pre_valid_ DATE_COLLECTION_HANDLE  hDateCollection,
    _In_opt_ _When_(pFiletime == NULL && pLargeInt == NULL && rfDateId == NULL, _Notnull_) 
        DATE_ITEM_HANDLE hDateItem,
    _In_opt_ _When_(hDateItem == NULL && pLargeInt == NULL && rfDateId == NULL, _Notnull_) 
        PFILETIME pFiletime,
    _In_opt_ _When_(hDateItem == NULL && pFiletime == NULL && rfDateId == NULL, _Notnull_) 
        PLARGE_INTEGER pLargeInt,
    _In_opt_ _When_(hDateItem == NULL && pFiletime == NULL && pLargeInt == NULL, _Notnull_) 
        GUID * rfDateId
);

Calling Convention

Standard C calling convention with SAL annotations enforcing exclusive search criteria.

Parameters

hDateCollection

[In] DATE_COLLECTION_HANDLE

Handle to the date collection to search.

Must be a valid DATE_COLLECTION_HANDLE obtained from NewDateLogHandle() or ConvertToDateLogHandle()
Must have been validated by prior IsValidDateLogHandle()
Must contain a valid context with initialized date log core
Precondition: Pre-validated, not NULL

hDateItem

[In, Optional] DATE_ITEM_HANDLE

Handle to the date item to find.

When provided: performs handle-based lookup (fastest)
When NULL: one of the other three search criteria must be provided
SAL annotation ensures this is the only search parameter when present
Used by SearchDateItem() internal helper

pFiletime

[In, Optional] PFILETIME

Pointer to FILETIME value to search for.

When provided: performs optimized binary search on sorted date array
When NULL: one of the other three search criteria must be provided
SAL annotation ensures this is the only search parameter when present
Used by SearchDateItemByFileTime() with O(log n) performance
Requires date array to be sorted by FILETIME (guaranteed by initialization)

pLargeInt

[In, Optional] PLARGE_INTEGER

Pointer to LARGE_INTEGER value to search for.

When provided: performs optimized binary search using custom comparator
When NULL: one of the other three search criteria must be provided
SAL annotation ensures this is the only search parameter when present
Used by SearchDateItemByLargeInteger() with O(log n) performance
Compatible with FILETIME representation as 64-bit integer

rfDateId

[In, Optional] GUID *

Pointer to GUID (unique identifier) to search for.

When provided: performs linear search with GUID comparison
When NULL: one of the other three search criteria must be provided
SAL annotation ensures this is the only search parameter when present
Used by SearchDateItemByGuid() with O(n) performance
GUIDs are not sorted; binary search cannot be applied
Search is protected by mutex with 30-second timeout

Return Values

Success Case

DATE_ITEM_HANDLE (non-NULL)

A valid handle to the found date item. This handle can be used with other date-item functions for further operations.

Failure Cases

Validation Errors

NULL

Returned when:

Collection handle is invalid (failed IsValidDateLogHandle() check)
All search criteria parameters are NULL (no search key provided)
Collection context is NULL or date log core is NULL (defensive check)

Search Failures

NULL

Returned when the search criteria does not match any date item in the collection:

Provided handle was not found in the collection
Provided FILETIME value does not match any date item
Provided LARGE_INTEGER value does not match any date item
Provided GUID value does not match any date item

Synchronization Errors

NULL

Returned if the underlying search helper fails to acquire necessary mutexes within the 30-second timeout. This may indicate system resource contention or other operations holding locks.

Return Value Checking


// Simple usage pattern
DATE_ITEM_HANDLE hFound = FindDateItemHandle(
    hDateCollection,
    hSearchItem,    // Search by handle
    NULL,           // Not searching by FILETIME
    NULL,           // Not searching by LARGE_INTEGER
    NULL            // Not searching by GUID
);

if (hFound != NULL) {
    // Item found, can now use hFound with other functions
    printf("Found date item\n");
} else {
    // Item not found or validation error
    printf("Date item not found or error occurred\n");
}

Behavior and Operations

Execution Flow

Validate Collection

→

Check Criteria

→

Dispatch Search

→

Return Result

Validation Process

Before dispatching to the appropriate search helper, the function performs three validation checks:

Collection Handle Validation: Calls IsValidDateLogHandle(hDateCollection)
- Verifies the handle pointer is valid
- Checks the handle signature/magic number
- Returns NULL immediately if validation fails
Search Criteria Validation: Ensures at least one search criterion is provided
- Rejects calls where all four parameters are NULL
- Returns NULL if no search key is available
Context Validation: Defensive check of internal structures
- Verifies pDateLog->pContext is not NULL
- Verifies pContext->hDateLogCore is not NULL
- Returns NULL if context is invalid (should not occur after handle validation)

Search Dispatch

After validation, the function dispatches to the appropriate search helper based on the first non-NULL criterion in this priority order:

If hDateItem != NULL: Call SearchDateItem(hDateLogCore, hDateItem)
Else if pFiletime != NULL: Call SearchDateItemByFileTime(hDateLogCore, pFiletime)
Else if pLargeInt != NULL: Call SearchDateItemByLargeInteger(hDateLogCore, pLargeInt)
Else if rfDateId != NULL: Call SearchDateItemByGuid(hDateLogCore, rfDateId)
Else: Return NULL (should not occur due to earlier validation)

Thread Safety

All underlying search helpers are protected by mutexes:

Mutex Acquisition: Each search helper acquires the date log core's internal mutex
Timeout: Mutex wait is bounded by 30-second timeout
Timeout Handling: If timeout occurs, search helper returns NULL
Automatic Release: Mutex is automatically released in the search helper

Caller Responsibility: The caller is responsible for maintaining the validity of the search criteria parameters during the function call. The collection handle and search parameters must not be freed or modified until the function returns.

Search Criteria Details

Handle-Based Search

Search by providing another DATE_ITEM_HANDLE:

Example: Search by Handle


DATE_ITEM_HANDLE hItemToFind = /* obtained from previous operation */;

DATE_ITEM_HANDLE hResult = FindDateItemHandle(
    hDateCollection,
    hItemToFind,    // Search for this handle
    NULL,           // Ignore FILETIME
    NULL,           // Ignore LARGE_INTEGER
    NULL            // Ignore GUID
);

Complexity: O(n) linear scan or O(1) hash lookup depending on implementation
Use Case: Verify if a specific date item exists in a collection
Performance: Generally fastest for single lookups

FILETIME-Based Search

Search by providing a FILETIME value (Windows 64-bit file time):

Example: Search by FILETIME


FILETIME ftSearchDate;
// Initialize ftSearchDate with target date
GetSystemTimeAsFileTime(&ftSearchDate);

DATE_ITEM_HANDLE hResult = FindDateItemHandle(
    hDateCollection,
    NULL,           // Ignore handle search
    &ftSearchDate,  // Search for this FILETIME
    NULL,           // Ignore LARGE_INTEGER
    NULL            // Ignore GUID
);

Complexity: O(log n) binary search on sorted array
Use Case: Find date item by calendar date
Performance: Optimal for large collections
Prerequisite: Date array must be sorted by FILETIME (guaranteed)

LARGE_INTEGER-Based Search

Search by providing a LARGE_INTEGER value:

Example: Search by LARGE_INTEGER


LARGE_INTEGER liSearchValue;
liSearchValue.QuadPart = 132500000000000000LL;  // Custom date representation

DATE_ITEM_HANDLE hResult = FindDateItemHandle(
    hDateCollection,
    NULL,           // Ignore handle search
    NULL,           // Ignore FILETIME
    &liSearchValue, // Search for this LARGE_INTEGER
    NULL            // Ignore GUID
);

Complexity: O(log n) binary search with custom comparator
Use Case: Find date item using non-standard date representations
Performance: Optimal for large collections
Compatibility: Works with FILETIME-compatible 64-bit integers

GUID-Based Search

Search by providing a GUID (unique identifier):

Example: Search by GUID


GUID guidSearchValue = {0x12345678, 0x1234, 0x1234, {0x12, 0x34, 0x56, 0x78, 0x9a, 0xbc, 0xde, 0xf0}};

DATE_ITEM_HANDLE hResult = FindDateItemHandle(
    hDateCollection,
    NULL,           // Ignore handle search
    NULL,           // Ignore FILETIME
    NULL,           // Ignore LARGE_INTEGER
    &guidSearchValue // Search for this GUID
);

Complexity: O(n) linear scan through all items
Use Case: Find date item by unique identifier (less common)
Performance: Linear search; slower for large collections
Limitation: GUIDs are not sorted; binary search cannot be applied
Thread Safety: Protected by mutex with 30-second timeout

Usage Examples

Example 1: Find Item by Current Date


// Find today's date in the collection
SYSTEMTIME stNow;
GetLocalTime(&stNow);

FILETIME ftNow;
SystemTimeToFileTime(&stNow, &ftNow);

DATE_ITEM_HANDLE hTodayItem = FindDateItemHandle(
    hMyDateCollection,
    NULL,
    &ftNow,
    NULL,
    NULL
);

if (hTodayItem != NULL) {
    printf("Found today's date in collection\n");
} else {
    printf("Today's date not found in collection\n");
}

Example 2: Find Item by GUID with Error Handling


// Search for item by GUID
GUID targetGuid = /* obtained from data source */;

DATE_ITEM_HANDLE hFoundItem = FindDateItemHandle(
    hMyDateCollection,
    NULL,
    NULL,
    NULL,
    &targetGuid
);

switch (hFoundItem == NULL) {
    case TRUE:
        printf("Item with GUID not found in collection\n");
        break;
    case FALSE:
        printf("Found item, handle = %p\n", hFoundItem);
        // Use hFoundItem for further operations
        break;
}

Example 3: Multiple Sequential Searches


// Perform multiple searches for different criteria
FILETIME ftSearch1, ftSearch2, ftSearch3;
// Initialize search dates...

// First search
DATE_ITEM_HANDLE h1 = FindDateItemHandle(hCollection, NULL, &ftSearch1, NULL, NULL);

// Second search
DATE_ITEM_HANDLE h2 = FindDateItemHandle(hCollection, NULL, &ftSearch2, NULL, NULL);

// Third search
DATE_ITEM_HANDLE h3 = FindDateItemHandle(hCollection, NULL, &ftSearch3, NULL, NULL);

// Verify results
if (h1 != NULL && h2 != NULL && h3 != NULL) {
    printf("All three items found\n");
}

Remarks and Notes

SAL Annotation Implications

The function uses exclusive SAL annotations to enforce that exactly one search criterion is provided:

_Check_return_ - Caller must check the return value
_Success_(return != NULL) - Function succeeds when returning non-NULL
_When_ clauses - Enforce mutual exclusivity of search parameters
_Notnull_ - The appropriate criterion must be non-NULL

Static Analysis: Code analysis tools (like PREFast or Clang Static Analyzer) will flag violations of these annotations, helping detect incorrect usage at compile time.

Performance Considerations

Search Type	Time Complexity	Best For
Handle	O(n) or O(1)	Verifying existing handles
FILETIME	O(log n)	Calendar date lookups
LARGE_INTEGER	O(log n)	Custom date representations
GUID	O(n)	Unique identifier lookups

Related Functions

SearchDateItem() - Low-level handle-based search helper
SearchDateItemByFileTime() - Low-level FILETIME search with binary search
SearchDateItemByLargeInteger() - Low-level LARGE_INTEGER search
SearchDateItemByGuid() - Low-level GUID search helper
IsValidDateLogHandle() - Validate collection handle
GetDateItemPrevious() - Navigate to previous item
GetDateItemNext() - Navigate to next item

Thread Safety Guarantees

Thread-Safe: This function is thread-safe. Multiple threads may call FindDateItemHandle() concurrently on the same collection. Each search operation acquires necessary mutexes atomically and releases them before returning.

Common Usage Patterns


                // Pattern 1: Check before using
                if (FindDateItemHandle(hColl, hItem, NULL, NULL, NULL) != NULL) {
                // Item exists, safe to use hItem
                }

                // Pattern 2: Store result for further operations
                DATE_ITEM_HANDLE hFound = FindDateItemHandle(hColl, NULL, &ft, NULL, NULL);
                if (hFound != NULL) {
                // Use hFound with other functions
                }

                // Pattern 3: Search with multiple criteria (try each in order)
                DATE_ITEM_HANDLE hResult = FindDateItemHandle(hColl, hItem, NULL, NULL, NULL);
                if (hResult == NULL && pFiletime != NULL) {
                hResult = FindDateItemHandle(hColl, NULL, pFiletime, NULL, NULL);
                }

Important Caveat: The returned DATE_ITEM_HANDLE is only valid during the lifetime of the collection handle. If the collection is closed or modified (items removed), previously returned handles may become invalid.