PathAllocCanonicalize function (pathcch.h)

Article
11/22/2022

Converts a path string into a canonical form.

This function differs from PathCchCanonicalize and PathCchCanonicalizeEx in that it returns the result on the heap. This means that the caller does not have to declare the size of the returned string and reduces stack use.

This function differs from PathCanonicalize in that it accepts paths with "\", "\?" and "\?\UNC" prefixes.

Note This function, PathCchCanonicalize, or PathCchCanonicalizeEx, should be used in place of PathCanonicalize.

Syntax

WINPATHCCHAPI HRESULT PathAllocCanonicalize(
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags,
  [out] PWSTR  *ppszPathOut
);

Parameters

[in] pszPathIn

A pointer to a buffer that contains the original string. This value cannot be NULL.

[in] dwFlags

One or more of the following flags:

Value	Meaning
PATHCCH_NONE 0x0000000	Do not allow for the construction of \\?\ paths (ie, long paths) longer than MAX_PATH .
PATHCCH_ALLOW_LONG_PATHS 0x00000001	Allow the building of \\?\ paths longer than MAX_PATH .
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 0x00000002	Forces the API to treat the caller as long path enabled, independent of the process's long name enabled state. This option can be used only when PATHCCH_ALLOW_LONG_PATHS is specified, and cannot be used with PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS. Note This value is available starting in Windows 10, version 1703.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 0x00000004	Forces the API to treat the caller as long path disabled, independent of the process's long name enabled state. This option can be used only when PATHCCH_ALLOW_LONG_PATHS is specified, and cannot be used with PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS. Note This value is available starting in Windows 10, version 1703.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 0x00000008	Disables the normalization of path segments that includes removing trailing dots and spaces. This enables access to paths that win32 path normalization will block. Note This value is available starting in Windows 10, version 1703.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH 0x00000010	Converts the input path into the extended length DOS device path form (with the \\?\ prefix) if not already in that form. This enables access to paths that are otherwise not addressable due to Win32 normalization rules (that can strip trailing dots and spaces) and path length limitations. This option implies the same behavior of PATHCCH_DO_NOT_NORMALIZE_SEGMENTS. Note This value is available starting in Windows 10, version 1703.
PATHCCH_ENSURE_TRAILING_SLASH 0x00000020	When combining or normalizing a path, ensure there is a trailing backslash. Note This value is available starting in Windows 10, version 1703.

[out] ppszPathOut

The address of a pointer to a buffer that, when this function returns successfully, receives the canonicalized path string. It is the responsibility of the caller to free this resource, when it is no longer needed, by calling the LocalFree function. This value cannot be NULL.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This function supports these alternate path forms:

\\?\
\\?\\UNC\
\\?\Volume{guid}\

This function does not convert forward slashes (/) into back slashes (\). With untrusted input, this function by itself, cannot be used to convert paths into a form that can be compared with other paths for sub-path or identity. Callers that need that ability should convert forward to back slashes before using this function.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	pathcch.h
Library	Pathcch.lib

Share via