| 1 | #pragma once |
| 2 | // Copyright (c) .NET Foundation and contributors. All rights reserved. Licensed under the Microsoft Reciprocal License. See LICENSE.TXT file in the project root for full license information. |
| 3 | |
| 4 | |
| 5 | #ifdef __cplusplus |
| 6 | extern "C" { |
| 7 | #endif |
| 8 | |
| 9 | typedef enum _PATH_CANONICALIZE |
| 10 | { |
| 11 | // Always prefix fully qualified paths with the extended path prefix (\\?\). |
| 12 | PATH_CANONICALIZE_APPEND_EXTENDED_PATH_PREFIX = 0x0001, |
| 13 | // Always terminate the path with \. |
| 14 | PATH_CANONICALIZE_BACKSLASH_TERMINATE = 0x0002, |
| 15 | // Don't collapse . or .. in the \\server\share portion of a UNC path. |
| 16 | PATH_CANONICALIZE_KEEP_UNC_ROOT = 0x0004, |
| 17 | } PATH_CANONICALIZE; |
| 18 | |
| 19 | typedef enum _PATH_EXPAND |
| 20 | { |
| 21 | PATH_EXPAND_ENVIRONMENT = 0x0001, |
| 22 | PATH_EXPAND_FULLPATH = 0x0002, |
| 23 | } PATH_EXPAND; |
| 24 | |
| 25 | typedef enum _PATH_PREFIX |
| 26 | { |
| 27 | // Add prefix even if the path is not longer than MAX_PATH. |
| 28 | PATH_PREFIX_SHORT_PATHS = 0x0001, |
| 29 | // Error with E_INVALIDARG if the path is not fully qualified. |
| 30 | PATH_PREFIX_EXPECT_FULLY_QUALIFIED = 0x0002, |
| 31 | } PATH_PREFIX; |
| 32 | |
| 33 | |
| 34 | /******************************************************************* |
| 35 | PathFile - returns a pointer to the file part of the path. |
| 36 | ********************************************************************/ |
| 37 | DAPI_(LPWSTR) PathFile( |
| 38 | __in_z LPCWSTR wzPath |
| 39 | ); |
| 40 | |
| 41 | /******************************************************************* |
| 42 | PathExtension - returns a pointer to the extension part of the path |
| 43 | (including the dot). |
| 44 | ********************************************************************/ |
| 45 | DAPI_(LPCWSTR) PathExtension( |
| 46 | __in_z LPCWSTR wzPath |
| 47 | ); |
| 48 | |
| 49 | /******************************************************************* |
| 50 | PathGetDirectory - extracts the directory from a path including the directory separator. |
| 51 | Calling the function again with the previous result returns the same result. |
| 52 | Returns S_FALSE if the path only contains a file name. |
| 53 | For example, C:\a\b -> C:\a\ -> C:\a\ |
| 54 | ********************************************************************/ |
| 55 | DAPI_(HRESULT) PathGetDirectory( |
| 56 | __in_z LPCWSTR wzPath, |
| 57 | __out_z LPWSTR *psczDirectory |
| 58 | ); |
| 59 | |
| 60 | /******************************************************************* |
| 61 | PathGetParentPath - extracts the parent directory from a path |
| 62 | ignoring a trailing slash so that when called repeatedly, |
| 63 | it eventually returns the root portion of the path. |
| 64 | *psczDirectory is NULL if the path only contains a file name or |
| 65 | the path only contains the root. |
| 66 | *pcchRoot is the length of the root part of the path. |
| 67 | For example, C:\a\b -> C:\a\ -> C:\ -> NULL |
| 68 | ********************************************************************/ |
| 69 | DAPI_(HRESULT) PathGetParentPath( |
| 70 | __in_z LPCWSTR wzPath, |
| 71 | __out_z LPWSTR *psczDirectory, |
| 72 | __out_opt SIZE_T* pcchRoot |
| 73 | ); |
| 74 | |
| 75 | /******************************************************************* |
| 76 | PathExpand - gets the full path to a file resolving environment |
| 77 | variables along the way. |
| 78 | ********************************************************************/ |
| 79 | DAPI_(HRESULT) PathExpand( |
| 80 | __out LPWSTR *psczFullPath, |
| 81 | __in_z LPCWSTR wzRelativePath, |
| 82 | __in DWORD dwResolveFlags |
| 83 | ); |
| 84 | |
| 85 | /******************************************************************* |
| 86 | PathGetFullPathName - wrapper around GetFullPathNameW. |
| 87 | *******************************************************************/ |
| 88 | DAPI_(HRESULT) PathGetFullPathName( |
| 89 | __in_z LPCWSTR wzPath, |
| 90 | __deref_out_z LPWSTR* psczFullPath, |
| 91 | __inout_z_opt LPCWSTR* pwzFileName, |
| 92 | __out_opt SIZE_T* pcch |
| 93 | ); |
| 94 | |
| 95 | /******************************************************************* |
| 96 | PathPrefix - prefixes a path with \\?\ or \\?\UNC if it doesn't |
| 97 | already have an extended prefix, is longer than MAX_PATH, |
| 98 | and is fully qualified. |
| 99 | ********************************************************************/ |
| 100 | DAPI_(HRESULT) PathPrefix( |
| 101 | __inout_z LPWSTR *psczFullPath, |
| 102 | __in SIZE_T cchFullPath, |
| 103 | __in DWORD dwPrefixFlags |
| 104 | ); |
| 105 | |
| 106 | /******************************************************************* |
| 107 | PathFixedNormalizeSlashes - replaces all / with \ and |
| 108 | removes redundant consecutive slashes. |
| 109 | ********************************************************************/ |
| 110 | DAPI_(HRESULT) PathFixedNormalizeSlashes( |
| 111 | __inout_z LPWSTR wzPath |
| 112 | ); |
| 113 | |
| 114 | /******************************************************************* |
| 115 | PathFixedReplaceForwardSlashes - replaces all / with \ |
| 116 | ********************************************************************/ |
| 117 | DAPI_(void) PathFixedReplaceForwardSlashes( |
| 118 | __inout_z LPWSTR wzPath |
| 119 | ); |
| 120 | |
| 121 | /******************************************************************* |
| 122 | PathFixedBackslashTerminate - appends a \ if path does not have it |
| 123 | already, but fails if the buffer is |
| 124 | insufficient. |
| 125 | ********************************************************************/ |
| 126 | DAPI_(HRESULT) PathFixedBackslashTerminate( |
| 127 | __inout_ecount_z(cchPath) LPWSTR wzPath, |
| 128 | __in SIZE_T cchPath |
| 129 | ); |
| 130 | |
| 131 | /******************************************************************* |
| 132 | PathBackslashTerminate - appends a \ if path does not have it |
| 133 | already. |
| 134 | ********************************************************************/ |
| 135 | DAPI_(HRESULT) PathBackslashTerminate( |
| 136 | __inout_z LPWSTR* psczPath |
| 137 | ); |
| 138 | |
| 139 | /******************************************************************* |
| 140 | PathForCurrentProcess - gets the full path to the currently executing |
| 141 | process or (optionally) a module inside the process. |
| 142 | ********************************************************************/ |
| 143 | DAPI_(HRESULT) PathForCurrentProcess( |
| 144 | __inout LPWSTR *psczFullPath, |
| 145 | __in_opt HMODULE hModule |
| 146 | ); |
| 147 | |
| 148 | /******************************************************************* |
| 149 | PathRelativeToModule - gets the name of a file in the same |
| 150 | directory as the current process or (optionally) a module inside |
| 151 | the process |
| 152 | ********************************************************************/ |
| 153 | DAPI_(HRESULT) PathRelativeToModule( |
| 154 | __inout LPWSTR *psczFullPath, |
| 155 | __in_opt LPCWSTR wzFileName, |
| 156 | __in_opt HMODULE hModule |
| 157 | ); |
| 158 | |
| 159 | /******************************************************************* |
| 160 | PathCreateTempFile |
| 161 | |
| 162 | Note: if wzDirectory is null, ::GetTempPath2() will be used instead. |
| 163 | if wzFileNameTemplate is null, GetTempFileName() will be used instead. |
| 164 | *******************************************************************/ |
| 165 | DAPI_(HRESULT) PathCreateTempFile( |
| 166 | __in_opt LPCWSTR wzDirectory, |
| 167 | __in_opt __format_string LPCWSTR wzFileNameTemplate, |
| 168 | __in DWORD dwUniqueCount, |
| 169 | __in_z LPCWSTR wzPrefix, |
| 170 | __in DWORD dwFileAttributes, |
| 171 | __out_opt LPWSTR* psczTempFile, |
| 172 | __out_opt HANDLE* phTempFile |
| 173 | ); |
| 174 | |
| 175 | /******************************************************************* |
| 176 | PathGetTempFileName - wrapper around ::GetTempFileName. |
| 177 | If the wzPathName is too long, it will use its own algorithm. |
| 178 | *******************************************************************/ |
| 179 | DAPI_(HRESULT) PathGetTempFileName( |
| 180 | __in LPCWSTR wzPathName, |
| 181 | __in LPCWSTR wzPrefixString, |
| 182 | __in UINT uUnique, |
| 183 | __out LPWSTR* psczTempFileName |
| 184 | ); |
| 185 | |
| 186 | /******************************************************************* |
| 187 | PathCreateTimeBasedTempFile - creates an empty temp file based on current |
| 188 | system time |
| 189 | ********************************************************************/ |
| 190 | DAPI_(HRESULT) PathCreateTimeBasedTempFile( |
| 191 | __in_z_opt LPCWSTR wzDirectory, |
| 192 | __in_z LPCWSTR wzPrefix, |
| 193 | __in_z_opt LPCWSTR wzPostfix, |
| 194 | __in_z LPCWSTR wzExtension, |
| 195 | __deref_opt_out_z LPWSTR* psczTempFile, |
| 196 | __out_opt HANDLE* phTempFile |
| 197 | ); |
| 198 | |
| 199 | /******************************************************************* |
| 200 | PathCreateTempDirectory |
| 201 | |
| 202 | Note: if wzDirectory is null, ::GetTempPath2() will be used instead. |
| 203 | *******************************************************************/ |
| 204 | DAPI_(HRESULT) PathCreateTempDirectory( |
| 205 | __in_opt LPCWSTR wzDirectory, |
| 206 | __in __format_string LPCWSTR wzDirectoryNameTemplate, |
| 207 | __in DWORD dwUniqueCount, |
| 208 | __out LPWSTR* psczTempDirectory |
| 209 | ); |
| 210 | |
| 211 | /******************************************************************* |
| 212 | PathGetTempPath - returns the path to the temp folder |
| 213 | that is backslash terminated. |
| 214 | *******************************************************************/ |
| 215 | DAPI_(HRESULT) PathGetTempPath( |
| 216 | __out_z LPWSTR* psczTempPath, |
| 217 | __out_opt SIZE_T* pcch |
| 218 | ); |
| 219 | |
| 220 | /******************************************************************* |
| 221 | PathGetSystemDirectory - returns the path to the system folder |
| 222 | that is backslash terminated. |
| 223 | *******************************************************************/ |
| 224 | DAPI_(HRESULT) PathGetSystemDirectory( |
| 225 | __out_z LPWSTR* psczSystemPath |
| 226 | ); |
| 227 | |
| 228 | /******************************************************************* |
| 229 | PathGetSystemWow64Directory - returns the path to the system WoW 64 folder |
| 230 | that is backslash terminated. |
| 231 | *******************************************************************/ |
| 232 | DAPI_(HRESULT) PathGetSystemWow64Directory( |
| 233 | __out_z LPWSTR* psczSystemPath |
| 234 | ); |
| 235 | |
| 236 | /******************************************************************* |
| 237 | PathSystemWindowsSubdirectory - returns the path to the Windows folder |
| 238 | or a subdirectory of that folder that is backslash terminated. |
| 239 | *******************************************************************/ |
| 240 | DAPI_(HRESULT) PathSystemWindowsSubdirectory( |
| 241 | __in_z_opt LPCWSTR wzSubdirectory, |
| 242 | __out_z LPWSTR* psczFullPath |
| 243 | ); |
| 244 | |
| 245 | /******************************************************************* |
| 246 | PathGetSystemTempPaths - returns the paths to system temp folders |
| 247 | that are backslash terminated with higher preference first. |
| 248 | *******************************************************************/ |
| 249 | DAPI_(HRESULT) PathGetSystemTempPaths( |
| 250 | __inout_z LPWSTR** prgsczSystemTempPaths, |
| 251 | __inout DWORD* pcSystemTempPaths |
| 252 | ); |
| 253 | |
| 254 | /******************************************************************* |
| 255 | PathGetVolumePathName - wrapper for ::GetVolumePathNameW. |
| 256 | *******************************************************************/ |
| 257 | DAPI_(HRESULT) PathGetVolumePathName( |
| 258 | __in_z LPCWSTR wzFileName, |
| 259 | __out_z LPWSTR* psczVolumePathName |
| 260 | ); |
| 261 | |
| 262 | /******************************************************************* |
| 263 | PathSkipPastRoot - returns a pointer to the first character after |
| 264 | the root portion of the path or NULL if the path has no root. |
| 265 | For example, the pointer will point to the "a" in "after": |
| 266 | C:\after, C:after, \after, \\server\share\after, |
| 267 | \\?\C:\afterroot, \\?\UNC\server\share\after |
| 268 | *******************************************************************/ |
| 269 | DAPI_(LPCWSTR) PathSkipPastRoot( |
| 270 | __in_z LPCWSTR wzPath, |
| 271 | __out_opt BOOL* pfHasExtendedPrefix, |
| 272 | __out_opt BOOL* pfFullyQualified, |
| 273 | __out_opt BOOL* pfUNC |
| 274 | ); |
| 275 | |
| 276 | /******************************************************************* |
| 277 | PathIsFullyQualified - returns true if the path is fully qualified; false otherwise. |
| 278 | Note that some rooted paths like C:dir are not fully qualified. |
| 279 | For example, these are all fully qualified: C:\dir, C:/dir, \\server\share, \\?\C:\dir. |
| 280 | For example, these are not fully qualified: C:dir, C:, \dir, dir, dir\subdir. |
| 281 | *******************************************************************/ |
| 282 | DAPI_(BOOL) PathIsFullyQualified( |
| 283 | __in_z LPCWSTR wzPath |
| 284 | ); |
| 285 | |
| 286 | /******************************************************************* |
| 287 | PathIsRooted - returns true if the path is rooted; false otherwise. |
| 288 | Note that some rooted paths like C:dir are not fully qualified. |
| 289 | For example, these are all rooted: C:\dir, C:/dir, C:dir, C:, \dir, \\server\share, \\?\C:\dir. |
| 290 | For example, these are not rooted: dir, dir\subdir. |
| 291 | *******************************************************************/ |
| 292 | DAPI_(BOOL) PathIsRooted( |
| 293 | __in_z LPCWSTR wzPath |
| 294 | ); |
| 295 | |
| 296 | /******************************************************************* |
| 297 | PathConcat - like .NET's Path.Combine, lets you build up a path |
| 298 | one piece -- file or directory -- at a time. |
| 299 | *******************************************************************/ |
| 300 | DAPI_(HRESULT) PathConcat( |
| 301 | __in_opt LPCWSTR wzPath1, |
| 302 | __in_opt LPCWSTR wzPath2, |
| 303 | __deref_out_z LPWSTR* psczCombined |
| 304 | ); |
| 305 | |
| 306 | /******************************************************************* |
| 307 | PathConcatCch - like .NET's Path.Combine, lets you build up a path |
| 308 | one piece -- file or directory -- at a time. |
| 309 | *******************************************************************/ |
| 310 | DAPI_(HRESULT) PathConcatCch( |
| 311 | __in_opt LPCWSTR wzPath1, |
| 312 | __in SIZE_T cchPath1, |
| 313 | __in_opt LPCWSTR wzPath2, |
| 314 | __in SIZE_T cchPath2, |
| 315 | __deref_out_z LPWSTR* psczCombined |
| 316 | ); |
| 317 | |
| 318 | /******************************************************************* |
| 319 | PathConcatRelativeToBase - canonicalizes a relative path before |
| 320 | concatenating it to the base path to ensure the resulting path |
| 321 | is inside the base path. |
| 322 | *******************************************************************/ |
| 323 | DAPI_(HRESULT) PathConcatRelativeToBase( |
| 324 | __in LPCWSTR wzBase, |
| 325 | __in_opt LPCWSTR wzRelative, |
| 326 | __deref_out_z LPWSTR* psczCombined |
| 327 | ); |
| 328 | |
| 329 | /******************************************************************* |
| 330 | PathConcatRelativeToFullyQualifiedBase - ensures the base path is |
| 331 | fully qualified and then calls PathConcatRelativeToBase. |
| 332 | *******************************************************************/ |
| 333 | DAPI_(HRESULT) PathConcatRelativeToFullyQualifiedBase( |
| 334 | __in LPCWSTR wzBase, |
| 335 | __in_opt LPCWSTR wzRelative, |
| 336 | __deref_out_z LPWSTR* psczCombined |
| 337 | ); |
| 338 | |
| 339 | /******************************************************************* |
| 340 | PathCompareCanonicalized - canonicalizes the two paths using PathCanonicalizeForComparison |
| 341 | which does not resolve relative paths into fully qualified paths. |
| 342 | The strings are then compared using ::CompareStringW(). |
| 343 | *******************************************************************/ |
| 344 | DAPI_(HRESULT) PathCompareCanonicalized( |
| 345 | __in_z LPCWSTR wzPath1, |
| 346 | __in_z LPCWSTR wzPath2, |
| 347 | __out BOOL* pfEqual |
| 348 | ); |
| 349 | |
| 350 | /******************************************************************* |
| 351 | PathCompress - sets the compression state on an existing file or |
| 352 | directory. A no-op on file systems that don't |
| 353 | support compression. |
| 354 | *******************************************************************/ |
| 355 | DAPI_(HRESULT) PathCompress( |
| 356 | __in_z LPCWSTR wzPath |
| 357 | ); |
| 358 | |
| 359 | /******************************************************************* |
| 360 | PathGetHierarchyArray - allocates an array containing, |
| 361 | in order, every parent directory of the specified path, |
| 362 | ending with the actual input path |
| 363 | This function also works with registry subkeys |
| 364 | *******************************************************************/ |
| 365 | DAPI_(HRESULT) PathGetHierarchyArray( |
| 366 | __in_z LPCWSTR wzPath, |
| 367 | __deref_inout_ecount_opt(*pcPathArray) LPWSTR **prgsczPathArray, |
| 368 | __inout LPUINT pcPathArray |
| 369 | ); |
| 370 | |
| 371 | /******************************************************************** |
| 372 | Path2FunctionAllowFallback - allow functions only available in newer versions of Windows. |
| 373 | Typically used for unit testing. |
| 374 | |
| 375 | *********************************************************************/ |
| 376 | void DAPI Path2FunctionAllowFallback(); |
| 377 | |
| 378 | /******************************************************************** |
| 379 | Path2FunctionForceFallback - ignore functions only available in newer versions of Windows. |
| 380 | Typically used for unit testing. |
| 381 | |
| 382 | *********************************************************************/ |
| 383 | void DAPI Path2FunctionForceFallback(); |
| 384 | |
| 385 | /******************************************************************* |
| 386 | PathCanonicalizePath - wrapper around PathCanonicalizeW. |
| 387 | *******************************************************************/ |
| 388 | DAPI_(HRESULT) PathCanonicalizePath( |
| 389 | __in_z LPCWSTR wzPath, |
| 390 | __deref_out_z LPWSTR* psczCanonicalized |
| 391 | ); |
| 392 | |
| 393 | /******************************************************************* |
| 394 | PathAllocCanonicalizePath - wrapper around PathAllocCanonicalize. |
| 395 | *******************************************************************/ |
| 396 | DAPI_(HRESULT) PathAllocCanonicalizePath( |
| 397 | __in_z LPCWSTR wzPath, |
| 398 | __in DWORD dwFlags, |
| 399 | __deref_out_z LPWSTR* psczCanonicalized |
| 400 | ); |
| 401 | |
| 402 | /******************************************************************* |
| 403 | PathCanonicalizeForComparison - canonicalizes the path based on the given flags. |
| 404 | . and .. directories are collapsed. |
| 405 | All / are replaced with \. |
| 406 | All redundant consecutive slashes are replaced with a single \. |
| 407 | *******************************************************************/ |
| 408 | DAPI_(HRESULT) PathCanonicalizeForComparison( |
| 409 | __in_z LPCWSTR wzPath, |
| 410 | __in DWORD dwCanonicalizeFlags, |
| 411 | __deref_out_z LPWSTR* psczCanonicalized |
| 412 | ); |
| 413 | |
| 414 | /******************************************************************* |
| 415 | PathDirectoryContainsPath - checks if wzPath is located inside wzDirectory. |
| 416 | wzDirectory must be a fully qualified path. |
| 417 | *******************************************************************/ |
| 418 | DAPI_(HRESULT) PathDirectoryContainsPath( |
| 419 | __in_z LPCWSTR wzDirectory, |
| 420 | __in_z LPCWSTR wzPath |
| 421 | ); |
| 422 | |
| 423 | #ifdef __cplusplus |
| 424 | } |
| 425 | #endif |