NewUnicodeString Function Overview

	PUNICODE_STRING _Must_inspect_result_ _Success_(SUCCEEDED(return)) NewUnicodeString(
		_Pre_satisfies_(Length >= 1 && Length <= MAX_STRING_LENGTH) USHORT const Length,
		_Pre_satisfies_(MaximumLength >= 1 && MaximumLength <= MAX_STRING_LENGTH) USHORT const MaximumLength,
		_In_opt_z_ LPCWSTR Buffer
	);

The NewUnicodeString function is a memory-safe factory constructor that dynamically allocates and initializes a UNICODE_STRING structure with a wide-character (UTF-16) buffer. It serves as the primary mechanism for creating properly formatted Unicode string objects throughout the mdts_io DLL, ensuring consistent initialization and defensive validation of input parameters.

Function Purpose and Design Philosophy

NewUnicodeString encapsulates the creation logic for UNICODE_STRING structures, which are fundamental Win32 types used throughout the Windows API for representing variable-length Unicode text. Rather than requiring callers to manually allocate memory, initialize fields, and validate constraints, this function provides a single, controlled entry point that guarantees well-formed output or unambiguous failure (NULL return).

This design reduces the likelihood of buffer overruns, uninitialized fields, and off-by-one errors that commonly plague manual string management in C.

The function implements a two-phase initialization strategy: it first validates all input parameters defensively, then allocates and initializes memory only after confirming that the input contract will be satisfiable. This fail-fast approach prevents partial allocations or corrupted state when invalid inputs are detected.

Parameter Descriptions

Operational Sequence

The function executes in the following order:

• Validate Length and MaximumLength (non-zero, within bounds, and Length = MaximumLength).
• Allocate the UNICODE_STRING structure; initialize fields to safe defaults.
• Re-validate MaximumLength defensively.
• Allocate the buffer with (MaximumLength + 1) * sizeof(wchar_t).
• Initialize the buffer with a NUL terminator at index 0.
• If a source buffer is provided, copy exactly Length characters using wcsncpy_s.
• On copy success, set Length; on failure, free all memory and return NULL.
• If no source buffer is provided, leave Length = 0 and keep the allocated capacity.
• Return the fully initialized UNICODE_STRING or NULL on failure.

Typical Usage Pattern

A caller may invoke:

• NewUnicodeString(256, 256, L"C:\\Users\\Example\\File.txt") � creates a populated string with 256-character capacity.
• NewUnicodeString(512, 512, NULL) � creates an empty string with 512-character capacity.

The returned pointer is valid only on success. NULL indicates failure and requires no cleanup. When the string is no longer needed, the caller must invoke FreeUnicodeString to release both the buffer and the structure.

Error Handling and Contract Guarantees

On any failure (validation, allocation, or copy), the function returns NULL. No partial structure is returned, and no exception is raised. This simplifies error handling: NULL is unambiguous.

On success, all fields are fully initialized, the buffer is NUL-terminated, and the caller has exclusive ownership of the structure and must free it later using FreeUnicodeString.