FILE_PATH_DESC Structure


   	 typedef struct FILE_PATH_DESC {
		DWORD			dwType;	
		BOOL				bNewFile;
		DWORD			dwEncodingFlags;			
		PUNICODE_STRING		pFilePath;					
		PCRYPT_DATA_BLOB                 pTag;							
   	} FILE_PATH_DESC, *PFILE_PATH_DESC;
} PROG_FILE_PATH_DESC;

The PROG_FILE_PATH_DESC structure is a descriptor container that encapsulates all essential metadata required to identify, classify, and process a file within the mdts_io DLL framework. This structure serves as a bridge between high-level file operations and the underlying file system, carrying contextual information that determines how a file should be accessed, encrypted, or decrypted.

Structure Purpose and Usage

The primary purpose of PROG_FILE_PATH_DESC is to provide a unified representation of a file's identity and operational context. Rather than passing individual parameters (path, type, encoding state) across function boundaries, callers can bundle this information into a single structure, improving code clarity and maintainability.

This is particularly valuable in scenarios involving file cryptography, where encoding/decoding decisions depend on both the file's type and its current processing state.

Member Descriptions

dwType (DWORD)

A generic type identifier that categorizes the file. Values range from 0 to 63 (a 6-bit constraint), allowing the application to define up to 64 distinct file classifications. This may distinguish between log files, configuration files, encrypted payloads, temporary files, or other application-specific categories. The specific values are determined by the application's file type enumeration.

bNewFile (BOOL)

Indicates whether the file represents a newly created entity (TRUE) or an existing file being opened (FALSE). This distinction is critical for initialization logic: new files may require default metadata, while existing files must be validated and have their metadata read from storage.

dwEncodingFlags (DWORD)

A bitmask containing encoding/cryptographic operation flags derived from Win32 encoding functions. Common values include:

This field drives the cryptographic workflow, determining whether the file should be encrypted, decrypted, or left untouched.

pFilePath (PUNICODE_STRING)

Pointer to a dynamically allocated UNICODE_STRING structure containing the full file path in wide-character format. The caller must allocate this structure (typically via NewUnicodeString()) and ensure the path remains valid throughout the descriptor's lifetime.

The path must be properly null-terminated and reference a file accessible via Win32 APIs. A NULL pointer indicates an invalid or uninitialized descriptor.

pTag (PCRYPT_DATA_BLOB)

Pointer to a CRYPT_DATA_BLOB containing cryptographic metadata such as a decryption tag or initialization vector. This field is optional and may be NULL if no cryptographic context is required.

The tag is typically used during decryption operations to validate authenticity or reconstruct cryptographic context. This member is marked for future removal, indicating that cryptographic handling may be refactored in upcoming versions.

Typical Usage Pattern

A function receiving a PROG_FILE_PATH_DESC would:

For example, a file-processing function might open the file referenced by pFilePath, validate its type, and then conditionally encrypt or decrypt its contents based on dwEncodingFlags. If bNewFile is TRUE, the function may initialize default metadata; otherwise, it reads and validates existing metadata.