HRESULT _Must_inspect_result_ _Success_(SUCCEEDED(return)) BuildKnownFolderPath(
_In_ REFKNOWNFOLDERID *rfid,
_In_ KNOWN_FOLDER_FLAG dwFolderFlags,
_In_reads_opt_z_(dwPathBufferLength) LPWSTR pszPathBuffer,
_In_opt_ _Pre_satisfies_(dwPathBufferLength == 0 || (dwPathBufferLength > 0 && dwPathBufferLength <= MAX_PATH)) DWORD dwPathBufferLength,
_In_reads_opt_z_(dwFileNameLength) LPWSTR pszFileName,
_In_opt_ _Pre_satisfies_(dwFileNameLength == 0 || (dwFileNameLength > 0 && dwFileNameLength <= MAX_PATH)) DWORD dwFileNameLength,
_Outptr_ PUNICODE_STRING* pNewPath,
_In_ DWORD dwFlags
); ;
The BuildKnownFolderPath function is a path construction utility that assembles a complete
file system path by combining a Windows known folder location, optional subdirectories, and an optional
filename, returning the result as a newly allocated UNICODE_STRING.
�It serves as a centralized mechanism for generating standardized application file paths��
BuildKnownFolderPath abstracts the platform-dependent process of locating system folders and
constructing paths to them. Instead of requiring callers to invoke SHGetKnownFolderPath and
manually concatenate path components, this function encapsulates the entire workflow: retrieving the known
folder, validating lengths, optionally generating a GUID-based filename, formatting the final path, and
returning a fully validated UNICODE_STRING.
�The function validates all intermediate results and applies strict length constraints��
Pointer to a known folder identifier such as FOLDERID_AppData,
FOLDERID_LocalAppData, FOLDERID_Temp, or FOLDERID_Documents.
Passed directly to SHGetKnownFolderPath. A NULL pointer causes immediate failure.
�A NULL pointer causes immediate validation failure��
Flags controlling folder retrieval behavior, such as KF_FLAG_CREATE or
KF_FLAG_DEFAULT. Passed directly to SHGetKnownFolderPath.
Optional subdirectory path to append after the known folder. Length is validated via
dwPathBufferLength and must not exceed MAX_PATH.
Length of pszPathBuffer. Must be 0 if pszPathBuffer is NULL, otherwise
non-zero and = MAX_PATH.
�Violations� cause ERROR_INVALID_PARAMETER return.�
Optional filename to append. If PATH_ADD_RANDOM_FILE_NAME is set, this must be NULL.
Length of pszFileName. Must follow the same rules as dwPathBufferLength.
Output pointer receiving the newly allocated UNICODE_STRING. Always initialized to NULL
before any operations.
Optional behavior flags:
0 � no special processingPATH_ADD_TRAILING_BACKSLASH � append trailing backslashPATH_ADD_RANDOM_FILE_NAME � generate GUID filename
These flags are mutually exclusive.
�Setting both� is invalid and causes ERROR_INVALID_FLAGS return.�
The function performs validation and construction in a strict order:
pNewPath and rfid (must be non-NULL).dwFlags (must be one of the allowed values).pszPathBuffer and pszFileName.SHGetKnownFolderPath.MAX_PATH.UNICODE_STRING with MAX_PATH capacity.GenerateTempFileName.StringCbPrintfEx.Length and MaximumLength fields.S_OK and assign *pNewPath.�The constructed path is validated� and MaximumLength is set to MAX_PATH.�
A centralized cleanup block frees all temporary resources, including the known folder path returned by
SHGetKnownFolderPath, any generated filename, and any temporary UNICODE_STRING.
Ownership is transferred to the caller only on success.
�This ensures that all allocated resources� are freed regardless of which step fails.�
Example usage:
BuildKnownFolderPath(&FOLDERID_LocalAppData, KF_FLAG_CREATE,
L"MyApp\\Logs", 12, L"debug.log", 9, &pPath, 0)
Produces:
C:\Users\User\AppData\Local\MyApp\Logs\debug.log
BuildKnownFolderPath(&FOLDERID_Temp, KF_FLAG_DEFAULT,
NULL, 0, NULL, 0, &pPath, PATH_ADD_RANDOM_FILE_NAME)
Produces a GUID-based filename such as:
C:\Users\User\AppData\Local\Temp\12345678-1234-1234-1234-123456789012
When finished, callers must free the returned path via FreeUnicodeString(pPath).