huwcampbell.com
Reactos
1/*
2 * PROJECT: ReactOS PSDK
3 * LICENSE: MIT (https://spdx.org/licenses/MIT)
4 * PURPOSE: "Secure" shell path manipulation functions
5 * COPYRIGHT: MinGW-64 and Microsoft Corporation.
6 * Copyright 2023-2025 Hermès Bélusca-Maïto <hermes.belusca-maito@reactos.org>
7 */
8
9/**
10 * This file is part of the mingw-w64 runtime package.
11 * No warranty is given; refer to the file DISCLAIMER within this package.
12 */
13
14#pragma once
15
16#ifndef WINBASEAPI
17#ifndef _KERNEL32_
18#define WINBASEAPI DECLSPEC_IMPORT
19#else
20#define WINBASEAPI
21#endif
22#endif
23
24#ifndef WINPATHCCHAPI
25#ifndef STATIC_PATHCCH
26#define WINPATHCCHAPI WINBASEAPI
27#else
28#define WINPATHCCHAPI
29#endif
30#endif
31
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37typedef enum PATHCCH_OPTIONS
38{
39 PATHCCH_NONE = 0x00,
40 PATHCCH_ALLOW_LONG_PATHS = 0x01,
41 PATHCCH_FORCE_ENABLE_LONG_NAME_PROCESS = 0x02,
42 PATHCCH_FORCE_DISABLE_LONG_NAME_PROCESS = 0x04,
43 PATHCCH_DO_NOT_NORMALIZE_SEGMENTS = 0x08,
44 PATHCCH_ENSURE_IS_EXTENDED_LENGTH_PATH = 0x10,
45 PATHCCH_ENSURE_TRAILING_SLASH = 0x20,
46} PATHCCH_OPTIONS;
47DEFINE_ENUM_FLAG_OPERATORS(PATHCCH_OPTIONS)
48
49#define VOLUME_PREFIX L"\\\\?\\Volume"
50#define VOLUME_PREFIX_LEN (ARRAYSIZE(VOLUME_PREFIX) - 1)
51
52#define PATHCCH_MAX_CCH 0x8000
53
54WINPATHCCHAPI
55HRESULT
56APIENTRY
57PathAllocCanonicalize(
58 _In_ PCWSTR pszPathIn,
59 _In_ /* PATHCCH_OPTIONS */ ULONG dwFlags,
60 _Outptr_ PWSTR* ppszPathOut);
61
62WINPATHCCHAPI
63HRESULT
64APIENTRY
65PathAllocCombine(
66 _In_opt_ PCWSTR pszPathIn,
67 _In_opt_ PCWSTR pszMore,
68 _In_ /* PATHCCH_OPTIONS */ ULONG dwFlags,
69 _Outptr_ PWSTR* ppszPathOut);
70
71WINPATHCCHAPI
72HRESULT
73APIENTRY
74PathCchAddBackslash(
75 _Inout_updates_(cchPath) PWSTR pszPath,
76 _In_ size_t cchPath);
77
78WINPATHCCHAPI
79HRESULT
80APIENTRY
81PathCchAddBackslashEx(
82 _Inout_updates_(cchPath) PWSTR pszPath,
83 _In_ size_t cchPath,
84 _Outptr_opt_result_buffer_(*pcchRemaining) PWSTR* ppszEnd,
85 _Out_opt_ size_t* pcchRemaining);
86
87WINPATHCCHAPI
88HRESULT
89APIENTRY
90PathCchAddExtension(
91 _Inout_updates_(cchPath) PWSTR pszPath,
92 _In_ size_t cchPath,
93 _In_ PCWSTR pszExt);
94
95WINPATHCCHAPI
96HRESULT
97APIENTRY
98PathCchAppend(
99 _Inout_updates_(cchPath) PWSTR pszPath,
100 _In_ size_t cchPath,
101 _In_opt_ PCWSTR pszMore);
102
103WINPATHCCHAPI
104HRESULT
105APIENTRY
106PathCchAppendEx(
107 _Inout_updates_(cchPath) PWSTR pszPath,
108 _In_ size_t cchPath,
109 _In_opt_ PCWSTR pszMore,
110 _In_ /* PATHCCH_OPTIONS */ ULONG dwFlags);
111
112WINPATHCCHAPI
113HRESULT
114APIENTRY
115PathCchCanonicalize(
116 _Out_writes_(cchPathOut) PWSTR pszPathOut,
117 _In_ size_t cchPathOut,
118 _In_ PCWSTR pszPathIn);
119
120WINPATHCCHAPI
121HRESULT
122APIENTRY
123PathCchCanonicalizeEx(
124 _Out_writes_(cchPathOut) PWSTR pszPathOut,
125 _In_ size_t cchPathOut,
126 _In_ PCWSTR pszPathIn,
127 _In_ /* PATHCCH_OPTIONS */ ULONG dwFlags);
128
129WINPATHCCHAPI
130HRESULT
131APIENTRY
132PathCchCombine(
133 _Out_writes_(cchPathOut) PWSTR pszPathOut,
134 _In_ size_t cchPathOut,
135 _In_opt_ PCWSTR pszPathIn,
136 _In_opt_ PCWSTR pszMore);
137
138WINPATHCCHAPI
139HRESULT
140APIENTRY
141PathCchCombineEx(
142 _Out_writes_(cchPathOut) PWSTR pszPathOut,
143 _In_ size_t cchPathOut,
144 _In_opt_ PCWSTR pszPathIn,
145 _In_opt_ PCWSTR pszMore,
146 _In_ /* PATHCCH_OPTIONS */ ULONG dwFlags);
147
148WINPATHCCHAPI
149HRESULT
150APIENTRY
151PathCchFindExtension(
152 _In_reads_(cchPath) PCWSTR pszPath,
153 _In_ size_t cchPath,
154 _Outptr_ PCWSTR* ppszExt);
155
156WINPATHCCHAPI
157BOOL
158APIENTRY
159PathCchIsRoot(
160 _In_opt_ PCWSTR pszPath);
161
162WINPATHCCHAPI
163HRESULT
164APIENTRY
165PathCchRemoveBackslash(
166 _Inout_updates_(cchPath) PWSTR pszPath,
167 _In_ size_t cchPath);
168
169WINPATHCCHAPI
170HRESULT
171APIENTRY
172PathCchRemoveBackslashEx(
173 _Inout_updates_(cchPath) PWSTR pszPath,
174 _In_ size_t cchPath,
175 _Outptr_opt_result_buffer_(*pcchRemaining) PWSTR* ppszEnd,
176 _Out_opt_ size_t* pcchRemaining);
177
178WINPATHCCHAPI
179HRESULT
180APIENTRY
181PathCchRemoveExtension(
182 _Inout_updates_(cchPath) PWSTR pszPath,
183 _In_ size_t cchPath);
184
185WINPATHCCHAPI
186HRESULT
187APIENTRY
188PathCchRemoveFileSpec(
189 _Inout_updates_(cchPath) PWSTR pszPath,
190 _In_ size_t cchPath);
191
192WINPATHCCHAPI
193HRESULT
194APIENTRY
195PathCchRenameExtension(
196 _Inout_updates_(cchPath) PWSTR pszPath,
197 _In_ size_t cchPath,
198 _In_ PCWSTR pszExt);
199
200WINPATHCCHAPI
201HRESULT
202APIENTRY
203PathCchSkipRoot(
204 _In_ PCWSTR pszPath,
205 _Outptr_ PCWSTR* ppszRootEnd);
206
207WINPATHCCHAPI
208HRESULT
209APIENTRY
210PathCchStripPrefix(
211 _Inout_updates_(cchPath) PWSTR pszPath,
212 _In_ size_t cchPath);
213
214WINPATHCCHAPI
215HRESULT
216APIENTRY
217PathCchStripToRoot(
218 _Inout_updates_(cchPath) PWSTR pszPath,
219 _In_ size_t cchPath);
220
221WINPATHCCHAPI
222BOOL
223APIENTRY
224PathIsUNCEx(
225 _In_ PCWSTR pszPath,
226 _Outptr_opt_ PCWSTR* ppszServer);
227
228
229#ifndef PATHCCH_NO_DEPRECATE
230
231#undef PathAddBackslash
232#undef PathAddBackslashA
233#undef PathAddBackslashW
234
235#undef PathAddExtension
236#undef PathAddExtensionA
237#undef PathAddExtensionW
238
239#undef PathAppend
240#undef PathAppendA
241#undef PathAppendW
242
243#undef PathCanonicalize
244#undef PathCanonicalizeA
245#undef PathCanonicalizeW
246
247#undef PathCombine
248#undef PathCombineA
249#undef PathCombineW
250
251#undef PathRenameExtension
252#undef PathRenameExtensionA
253#undef PathRenameExtensionW
254
255
256#ifdef DEPRECATE_SUPPORTED
257
258// #pragma deprecated(PathIsRelativeWorker)
259// #pragma deprecated(StrIsEqualWorker)
260// #pragma deprecated(FindPreviousBackslashWorker)
261// #pragma deprecated(IsHexDigitWorker)
262// #pragma deprecated(StringIsGUIDWorker)
263// #pragma deprecated(PathIsVolumeGUIDWorker)
264// #pragma deprecated(IsValidExtensionWorker)
265
266#pragma deprecated(PathAddBackslash)
267#pragma deprecated(PathAddBackslashA)
268#pragma deprecated(PathAddBackslashW)
269
270#pragma deprecated(PathAddExtension)
271#pragma deprecated(PathAddExtensionA)
272#pragma deprecated(PathAddExtensionW)
273
274#pragma deprecated(PathAppend)
275#pragma deprecated(PathAppendA)
276#pragma deprecated(PathAppendW)
277
278#pragma deprecated(PathCanonicalize)
279#pragma deprecated(PathCanonicalizeA)
280#pragma deprecated(PathCanonicalizeW)
281
282#pragma deprecated(PathCombine)
283#pragma deprecated(PathCombineA)
284#pragma deprecated(PathCombineW)
285
286#pragma deprecated(PathRenameExtension)
287#pragma deprecated(PathRenameExtensionA)
288#pragma deprecated(PathRenameExtensionW)
289
290#else // !DEPRECATE_SUPPORTED
291
292// #define PathIsRelativeWorker PathIsRelativeWorker_is_internal_to_pathcch;
293// #define StrIsEqualWorker StrIsEqualWorker_is_internal_to_pathcch;
294// #define FindPreviousBackslashWorker FindPreviousBackslashWorker_is_internal_to_pathcch;
295// #define IsHexDigitWorker IsHexDigitWorker_is_internal_to_pathcch;
296// #define StringIsGUIDWorker StringIsGUIDWorker_is_internal_to_pathcch;
297// #define PathIsVolumeGUIDWorker PathIsVolumeGUIDWorker_is_internal_to_pathcch;
298// #define IsValidExtensionWorker IsValidExtensionWorker_is_internal_to_pathcch;
299
300#define PathAddBackslash PathAddBackslash_instead_use_PathCchAddBackslash;
301#define PathAddBackslashA PathAddBackslash_instead_use_PathCchAddBackslash;
302#define PathAddBackslashW PathAddBackslash_instead_use_PathCchAddBackslash;
303
304#define PathAddExtension PathAddExtension_instead_use_PathCchAddExtension;
305#define PathAddExtensionA PathAddExtension_instead_use_PathCchAddExtension;
306#define PathAddExtensionW PathAddExtension_instead_use_PathCchAddExtension;
307
308#define PathAppend PathAppend_instead_use_PathCchAppend;
309#define PathAppendA PathAppend_instead_use_PathCchAppend;
310#define PathAppendW PathAppend_instead_use_PathCchAppend;
311
312#define PathCanonicalize PathCanonicalize_instead_use_PathCchCanonicalize;
313#define PathCanonicalizeA PathCanonicalize_instead_use_PathCchCanonicalize;
314#define PathCanonicalizeW PathCanonicalize_instead_use_PathCchCanonicalize;
315
316#define PathCombine PathCombine_instead_use_PathCchCombine;
317#define PathCombineA PathCombine_instead_use_PathCchCombine;
318#define PathCombineW PathCombine_instead_use_PathCchCombine;
319
320#define PathRenameExtension PathRenameExtension_instead_use_PathCchRenameExtension;
321#define PathRenameExtensionA PathRenameExtension_instead_use_PathCchRenameExtension;
322#define PathRenameExtensionW PathRenameExtension_instead_use_PathCchRenameExtension;
323
324#endif // DEPRECATE_SUPPORTED
325
326#endif // PATHCCH_NO_DEPRECATE
327
328#ifdef __cplusplus
329}
330#endif
331
332
333/* C++ non-const overloads */
334#ifdef __cplusplus
335
336__inline HRESULT
337PathCchFindExtension(
338 _In_reads_(cchPath) PWSTR pszPath,
339 _In_ size_t cchPath,
340 _Outptr_ PWSTR* ppszExt)
341{
342 return PathCchFindExtension(const_cast<PCWSTR>(pszPath), cchPath, const_cast<PCWSTR*>(ppszExt));
343}
344
345__inline HRESULT
346PathCchSkipRoot(
347 _In_ PWSTR pszPath,
348 _Outptr_ PWSTR* ppszRootEnd)
349{
350 return PathCchSkipRoot(const_cast<PCWSTR>(pszPath), const_cast<PCWSTR*>(ppszRootEnd));
351}
352
353__inline BOOL
354PathIsUNCEx(
355 _In_ PWSTR pszPath,
356 _Outptr_opt_ PWSTR* ppszServer)
357{
358 return PathIsUNCEx(const_cast<PCWSTR>(pszPath), const_cast<PCWSTR*>(ppszServer));
359}
360
361#endif // __cplusplus