Edit

PathCchAppendEx function (pathcch.h)

  • Article

Appends one path to the end of another.

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

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

Note This function, or PathCchAppend, should be used in place of PathAppend to prevent the possibility of a buffer overrun.

Syntax

WINPATHCCHAPI HRESULT PathCchAppendEx(
  [in, out]      PWSTR  pszPath,
  [in]           size_t cchPath,
  [in, optional] PCWSTR pszMore,
  [in]           ULONG  dwFlags
);

Parameters

[in, out] pszPath

A pointer to a buffer that, on entry, contains the original path. When this function returns successfully, the buffer contains the original path plus the appended path.

[in] cchPath

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

[in, optional] pszMore

A pointer the path to append to the end of the path pointed to by pszPath. UNC paths and paths that begin with the sequence \?\ are accepted and recognized as fully-qualified paths. These paths replace the string pointed to by pszPath instead of being appended to it.

[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.

Return value

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

Return code Description
E_INVALIDARG
 Either pszPath or pszMore is NULL, cchPath is 0, or cchPath is greater than PATHCCH_MAX_CCH.
PATHCCH_E_FILENAME_TOO_LONG
 The resulting string would exceed PATHCCH_MAX_CCH.
E_OUTOFMEMORY
 The function could not allocate a buffer of the necessary size.

Remarks

This function inserts a backslash between the two strings, if one is not already present.

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

See also

PathCchAppend