PathSearchAndQualify function
Applies to: desktop apps only
Determines if a given path is correctly formatted and fully qualified.
Syntax
BOOL PathSearchAndQualify( __in LPCTSTR pcszPath, __out LPTSTR pszFullyQualifiedPath, __in UINT cchFullyQualifiedPath );
Parameters
- pcszPath [in]
-
Type: LPCTSTR
A pointer to a null-terminated string of maximum length MAX_PATH that contains the path to search.
- pszFullyQualifiedPath [out]
-
Type: LPTSTR
A pointer to a null-terminated string of length MAX_PATH that contains the path to be referenced.
- cchFullyQualifiedPath [in]
-
Type: UINT
The size of the buffer pointed to by pszFullyQualifiedPath, in characters.
Return value
Type: BOOL
Returns TRUE if the path is qualified, or FALSE otherwise.
Requirements
|
Minimum supported client | Windows 2000 Professional, Windows XP |
|---|---|
|
Minimum supported server | Windows 2000 Server |
|
Header |
|
|
Library |
|
|
DLL |
|
|
Unicode and ANSI names | PathSearchAndQualifyW (Unicode) and PathSearchAndQualifyA (ANSI) |
Send comments about this topic to Microsoft
Build date: 3/7/2012
PathSearchAndQualify is used to canonicalize a file path. See the following examples (all backslashes are literal):
"C:\foo\." -> "C:\foo"
"C:\foo\baz\.." -> "C:\foo"
"C:\foo\\\baz" -> "C:\foo\baz"
"\\server\aa\..\bb" -> "\\server\aa\bb"
"notepad.exe" -> "C:\Windows\System32\notepad.exe"
"%SystemRoot%\System32\notepad.exe" -> "C:\Windows\System32\notepad.exe"
Environment variables (%FOO%) are expanded. If pcszPath contains a single component it is searched first in the current folder, then in all locations in %PATH%. If the file/folder is not found the function succeeds and returns a path relative to the current directory. It does not append a missing suffix (e.g., if the current directory is "C:\foo", the input "notepad" is not expanded to "C:\Windows\System32\notepad.exe" but rather to "C:\foo\notepad".)
Known Issues
- It does not consistently strip trailing blackslashes from non-folders, nor does it append backslashes to folders.
- In the ANSI version the argument cchFullyQualifiedPath must always be MAX_PATH (260). Otherwise a path length longer than cchFullyQualifiedPath will corrupt the return buffer (pszFullyQualifiedPath) and possibly overrun the stack/heap.
The issues listed above have been observed on XP.
Contrary to documentation, this function does not determine whether a path is correctly formatted. In particular, it allows paths that have a colon (:) in the filename. There does not appear to be any Windows API that will validate a path entered by the user; this is left as an an ad hoc exercise for each application.
[An embedded colon is valid in a filename; it indicates a stream. Example: ECHO "This is my stream" > MyFile:MyStream
-Gideon7]
- 4/3/2008
- Loren Meck
- 4/6/2008
- Gideon7
