FILE_INFO Structure Overview

    typedef struct FILE_INFO {
        DWORD						dwCategory;					
        SECURITY_ATTRIBUTES			SecAttr;
        HANDLE						hFile;						
        BY_HANDLE_FILE_INFORMATION  Fileinfo;					
        PROG_FILE_PATH_DESC			pPathDesc;					
        PWSTR						pszFileName;
        PFILETIME					pFiletime;					
    }FILE_INFO, * PFILE_INFO;

Encapsulates a file handle with comprehensive metadata, security context, and path information.

Structure Overview

This structure maintains a complete record of an open file, including the file handle, system metadata, custom timestamps, security attributes, and path information. It serves as the primary container for file operations throughout the mdts_io library.

Field Descriptions

dwCategory

• Generic classification number for the file (can be 0).
• Used for categorizing files by type or source without strict type constraints.

SecAttr

• Security attributes applied when the file was opened.
• Includes the security descriptor, inheritance flag, and structure length.
• Preserves the original security context.

hFile

• Windows file handle obtained from CreateFile().
• Must be valid and open; used for all file operations (read, write, lock, close).
• Validated as INVALID_HANDLE_VALUE when deallocated.

Fileinfo

• BY_HANDLE_FILE_INFORMATION structure populated by GetFileInformationByHandle().
• Contains file attributes, timestamps (creation, access, write), file size (high/low 32-bit components), and volume serial number.
• Queried once at file creation and not updated.

pPathDesc

• PROG_FILE_PATH_DESC pointer holding the file path as a UNICODE_STRING.
• Includes file type, encoding flags, and optional decryption tag.
• Always maintained as a separate allocation.
• Freed via FreeFileInfo().

pszFileName

• Direct pointer to the filename within the path buffer.
• Extracted via PathFindFileNameW() for quick access.
• Deprecated: Use usFileNameOffset and GET_FILEINFO_FILENAME() instead.

pFiletime

• Optional FILETIME pointer for a custom timestamp associated with the file.
• May be NULL if no custom time is set.
• If allocated, must be freed via FreeFileInfo().

Resource Management

• Allocated via NewFileInfo().
• Must be freed via FreeFileInfo() to release hFile, pPathDesc.pFilePath, and pFiletime.
• Closing hFile does not affect pPathDesc or pFiletime; they are independent allocations.
• Validation performed by IsValidFileInfo() checks handle validity, path consistency, and file existence.

Important Notes

• All pointer fields (pPathDesc, pszFileName, pFiletime) are owned by FILE_INFO and must not be freed independently.
• Use FreeFileInfo() to release the entire structure.
• pszFileName is transitional and deprecated use GET_FILEINFO_FILENAME() or usFileNameOffset.
• The BY_HANDLE_FILE_INFORMATION snapshot is static; file size or attributes may change on disk after creation without affecting the structure.