Export (0) Print
Expand All

PathCchCanonicalizeEx function

Simplifies a path by removing navigation elements such as "." and ".." to produce a direct, well-formed path.

This function differs from PathCchCanonicalize in that it allows for a longer final path to be constructed.

This function differs from PathAllocCanonicalize in that the caller must declare the size of the returned string, which is stored on the stack.

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

Note  This function, PathCchCanonicalize, or PathAllocCanonicalize should be used in place of PathCanonicalize to prevent the possibility of a buffer overrun.

Syntax


HRESULT PathCchCanonicalizeEx(
  _Out_  PWSTR pszPathOut,
  _In_   size_t cchPathOut,
  _In_   PCWSTR pszPathIn,
  _In_   unsigned long dwFlags
);

Parameters

pszPathOut [out]

A pointer to a buffer that, when this function returns successfully, receives the edited path string.

cchPathOut [in]

The size of the buffer pointed to by pszPathOut, in characters.

pszPathIn [in]

A pointer to the original path string. If this value is NULL, points to an empty string, or results in an empty string once the "." and ".." elements are removed, a single backslash is copied to the buffer pointed to by pszPathOut.

dwFlags [in]

The following flag is recognized; otherwise, set this value to 0.

ValueMeaning
PATHCCH_ALLOW_LONG_PATHS
0x00000001

Allow the building of \\?\ paths longer than MAX_PATH. Note that cchPathOut must be greater than MAX_PATH. If it is not, this flag is ignored.

 

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT code, including but not limited to the following.

Return codeDescription
E_INVALIDARG

The cchPathOut value is greater than PATHCCH_MAX_CCH.

PATHCCH_E_FILENAME_TOO_LONG

A path segment has more than PATHCCH_MAX_CCH characters, or, if the PATHCCH_ALLOW_LONG_PATHS flag is not set, exceeds the standard path segment length limit of 256 characters.

E_OUTOFMEMORY

The function could not allocate a buffer of the neccessary size.

 

Remarks

This function responds to the strings "." and ".." embedded in a path. The ".." string indicates to remove the immediately preceding path segment. The "." string indicates to skip over the next path segment. Note that the root segment of the path cannot be removed. If there are more ".." strings than there are path segments, the function returns S_OK and the buffer pointed to by pszPathOut contains a single backslash, "\".

All trailing periods are removed from the path, except when preceded by the "*" wild card character. In that case, a single period is retained after the '*' character, but all other trailing periods are removed.

If the resulting path is a root drive ("x:"), a backslash is appended ("x:\").

The following examples show the effect of these strings.

Original stringCanonicalized string
C:\name_1\.\name_2\..\name_3C:\name_1\name_3
C:\name_1\..\name_2\.\name_3C:\name_2\name_3
C:\name_1\name_2\.\name_3\..\name_4C:\name_1\name_2\name_4
C:\name_1\.\name_2\.\name_3\..\name_4\..C:\name_1\name_2
C:\name_1\*...C:\name_1\*.
C:\..C:\

 

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Pathcch.h

Library

Pathcch.lib

See also

PathCchCanonicalize

 

 

Community Additions

ADD
Show:
© 2014 Microsoft