NewFileInfo Function Overview


	HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return)) NewFileInfo(
		_In_	PUNICODE_STRING		  pFilePath,
		_In_	DWORD                 dwDesiredAccess,
		_In_	DWORD                 dwSharedMode,
		_In_opt_	LPSECURITY_ATTRIBUTES pSecAttr,
		_Inout_	PFILE_INFO* pNewFileInfo,
		_In_	DWORD                 dwCreationDisposition,
		_In_	DWORD                 dwFlagsAndAttributes,
		_In_opt_ PLOCK_FILE_INFO      pLockInfo	
	)	;

The NewFileInfo function is a comprehensive factory constructor that allocates, initializes, and validates a FILE_INFO structure representing an opened file with full metadata, security context, optional byte-range locking, and path descriptor information. It serves as the primary gateway for creating properly configured file handles within the mdts_io DLL, encapsulating Win32 file operations and defensive validation into a single, fail-safe entry point.
�It serves as the primary gateway for creating properly configured file handles��

Function Purpose and Design Philosophy

NewFileInfo abstracts away the complexity of file creation and initialization by bundling multiple Win32 API calls (CreateFile, GetFileInformationByHandle, LockFile operations, path parsing) into a single transaction-like operation. The function implements an all-or-nothing contract: if any step fails, all previously acquired resources are cleaned up and the caller receives a clear error code.
�This design eliminates the common error of partial initialization or leaked handles��

This design is especially valuable when both file access and explicit byte-range locking are required, ensuring that failure recovery always releases locks before closing the file handle.

Parameter Descriptions

pFilePath (PUNICODE_STRING, required)

Pointer to a well-formed UNICODE_STRING containing the file path. The buffer must be non-NULL, Length must be = MaximumLength, and MaximumLength must be = MAX_PATH. A malformed path causes immediate failure.
�The path must be well-formed (non-NULL buffer, logical Length = MaximumLength = MAX_PATH).�

dwDesiredAccess (DWORD)

Access rights passed directly to CreateFile. Common values include GENERIC_READ, GENERIC_WRITE, or both. Validation occurs implicitly during file opening.

dwSharedMode (DWORD)

File sharing constraints passed to CreateFile. Determines whether other processes may open the same file concurrently.

pSecAttr (PSECURITY_ATTRIBUTES, optional)

Optional security attributes validated via IsValidSecurityAttributes. Must contain absolute-format security descriptors. Copied into FILE_INFO on success.
�Invalid security attributes abort initialization with ERROR_INVALID_SECURITY_DESCR.�

pNewFileInfo (PFILE_INFO*, required output)

Output pointer receiving the newly allocated FILE_INFO structure. Always initialized to NULL before any operations to guarantee unambiguous failure semantics.

dwCreationDisposition (DWORD)

Creation behavior flags passed to CreateFile. Used to infer whether the file is newly created or existing for the bNewFile flag in PROG_FILE_PATH_DESC.

dwFlagsAndAttributes (DWORD)

File attributes and behavioral flags passed to CreateFile. FILE_FLAG_OVERLAPPED is propagated into the FILE_INFO attributes mask.

pLockInfo (PLOCK_FILE_INFO, optional)

Optional byte-range locking descriptor. If provided, all regions must be valid and within FILE_INFO_MAX_FILE_SIZE. Locking failures trigger rollback and cleanup.
�If any region fails to lock, all previously locked regions are unlocked via rollback��

Operational Sequence

The function performs initialization in a strict, fail-fast order:

�Finally, if all validations pass, the FILE_INFO pointer is assigned� and S_OK is returned.�

Cleanup and Error Handling

The function uses a centralized cleanup block that closes the file handle, unlocks regions, frees allocated UNICODE_STRING buffers, clears the path descriptor, frees temporary data, and finally frees the FILE_INFO structure.

�This ensures no resource leak occurs regardless of which validation step fails.�

Typical Usage Pattern

A caller may invoke:

On success, pFileInfo points to a fully initialized, validated, and optionally locked file structure. On failure, pFileInfo remains NULL and the caller checks the returned error code.

When finished, the caller must invoke FreeFileInfo(pFileInfo) to release all resources.