Share via

PathCchCanonicalizeEx 함수(pathcch.h)

  • 아티클

"." 및 ".."와 같은 탐색 요소를 제거하여 경로를 간소화하여 직접적이고 올바른 형식의 경로를 생성합니다.

이 함수는 더 긴 최종 경로를 생성할 수 있다는 점에서 PathCchCanonicalize 와 다릅니다.

이 함수는 호출자가 스택에 저장된 반환된 문자열의 크기를 선언해야 한다는 점에서 PathAllocCanonicalize 와 다릅니다.

이 함수는 "\", "\?" 및 "\?\UNC" 접두사를 사용하여 경로를 허용한다는 점에서 PathCanonicalize 와 다릅니다.

참고 이 함수인 PathCchCanonicalize 또는 PathAllocCanonicalize 는 버퍼 오버런 가능성을 방지하기 위해 PathCanonicalize 대신 사용해야 합니다.

구문

WINPATHCCHAPI HRESULT PathCchCanonicalizeEx(
  [out] PWSTR  pszPathOut,
  [in]  size_t cchPathOut,
  [in]  PCWSTR pszPathIn,
  [in]  ULONG  dwFlags
);

매개 변수

[out] pszPathOut

이 함수가 성공적으로 반환될 때 편집된 경로 문자열을 수신하는 버퍼에 대한 포인터입니다.

[in] cchPathOut

pszPathOut이 가리키는 버퍼의 크기(문자)입니다.

[in] pszPathIn

원래 경로 문자열에 대한 포인터입니다. 이 값이 NULL이거나, 빈 문자열을 가리키거나, "." 및 ".." 요소가 제거되면 빈 문자열이 생성되면 단일 백슬래시가 pszPathOut이 가리키는 버퍼에 복사됩니다.

[in] dwFlags

다음 플래그 중 하나 이상:

값 의미
PATHCCH_NONE
0x0000000
 MAX_PATH 보다 긴 \\?\ 경로(예: 긴 경로)의 생성을 허용하지 않습니다.
PATHCCH_ALLOW_LONG_PATHS
0x00000001
 MAX_PATH 보다 긴 \\?\ 경로 빌드를 허용합니다. cchPathOut은 MAX_PATH 보다 커야 합니다. 그렇지 않은 경우 이 플래그는 무시됩니다.
PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS
0x00000002
 API가 프로세스의 긴 이름 사용 상태와 관계없이 호출자를 긴 경로 사용으로 처리하도록 합니다. 이 옵션은 PATHCCH_ALLOW_LONG_PATHS 지정된 경우에만 사용할 수 있으며 PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS 사용할 수 없습니다.

참고 이 값은 Windows 10 버전 1703부터 사용할 수 있습니다.
PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS
0x00000004
 API가 프로세스의 긴 이름 사용 상태와 관계없이 호출자를 긴 경로 사용 안 함으로 처리하도록 합니다. 이 옵션은 PATHCCH_ALLOW_LONG_PATHS 지정된 경우에만 사용할 수 있으며 PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS 사용할 수 없습니다.

참고 이 값은 Windows 10 버전 1703부터 사용할 수 있습니다.
PATHCCH_DO_NOT_NORMALIZE_SEGMENTS
0x00000008
 후행 점과 공백 제거를 포함하는 경로 세그먼트의 정규화를 사용하지 않도록 설정합니다. 이렇게 하면 win32 경로 정규화가 차단되는 경로에 액세스할 수 있습니다.

참고 이 값은 Windows 10 버전 1703부터 사용할 수 있습니다.
PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH
0x00000010
 입력 경로를 확장된 길이 DOS 디바이스 경로 양식(\\?\ 접두사 포함)으로 변환합니다(해당 형식이 아직 없는 경우). 이렇게 하면 Win32 정규화 규칙(후행 점과 공백을 제거할 수 있음) 및 경로 길이 제한으로 인해 주소를 지정할 수 없는 경로에 액세스할 수 있습니다. 이 옵션은 PATHCCH_DO_NOT_NORMALIZE_SEGMENTS 동일한 동작을 의미합니다.

참고 이 값은 Windows 10 버전 1703부터 사용할 수 있습니다.
PATHCCH_ENSURE_TRAILING_SLASH
0x00000020
 경로를 결합하거나 정규화할 때 후행 백슬래시가 있는지 확인합니다.

참고 이 값은 Windows 10 버전 1703부터 사용할 수 있습니다.

반환 값

이 함수가 성공하면 S_OK 반환합니다. 그렇지 않으면 다음을 포함하지만 이에 국한되지 않는 HRESULT 코드를 반환합니다.

반환 코드 설명
E_INVALIDARG
 cchPathOut 값이 PATHCCH_MAX_CCH보다 큽니다.
PATHCCH_E_FILENAME_TOO_LONG
 경로 세그먼트는 PATHCCH_MAX_CCH 문자를 초과하거나 , PATHCCH_ALLOW_LONG_PATHS 플래그가 설정되지 않은 경우 표준 경로 세그먼트 길이 제한인 256자를 초과합니다.
E_OUTOFMEMORY
 함수가 필요한 크기의 버퍼를 할당할 수 없습니다.

설명

이 함수는 경로에 포함된 문자열 "." 및 ".."에 응답합니다. ".." 문자열은 바로 앞의 경로 세그먼트를 제거하도록 나타냅니다. "." 문자열은 다음 경로 세그먼트를 건너뛰도록 나타냅니다. 경로의 루트 세그먼트는 제거할 수 없습니다. 경로 세그먼트보다 더 많은 ".." 문자열이 있는 경우 함수는 S_OK 반환하고 pszPathOut 에서 가리키는 버퍼에는 단일 백슬래시 "\"가 포함됩니다.

"" 와일드 카드 문자 앞에 오는 경우를 제외하고 모든 후행 마침표가 경로에서 제거됩니다. 이 경우 '' 문자 뒤에 단일 마침표가 유지되지만 다른 모든 후행 마침표는 제거됩니다.

결과 경로가 루트 드라이브("x:")인 경우 백슬래시가 추가됩니다("x:\").

이 함수는 슬래시(/)를 슬래시(\)로 변환하지 않습니다. 신뢰할 수 없는 입력을 사용하면 이 함수 자체를 사용하여 경로를 하위 경로 또는 ID의 다른 경로와 비교할 수 있는 형식으로 변환할 수 없습니다. 이 기능이 필요한 호출자는 이 함수를 사용하기 전에 슬래시로 앞으로 변환해야 합니다.

다음 예제에서는 이러한 문자열의 효과를 보여 줍니다.

원본 문자열 정식화된 문자열
C:\name_1\.\name_2\.. \name_3 C:\name_1\name_3
C:\name_1\.. \name_2\.\name_3 C:\name_2\name_3
C:\name_1\name_2\.\name_3\.. \name_4 C:\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:\

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 8 [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2012 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 pathcch.h
라이브러리 Pathcch.lib

추가 정보

PathCchCanonicalize