Paths and Filenames

This section details the functions and structures used for manipulating file paths and filenames in the Windows operating system. Understanding how to correctly construct, parse, and manipulate paths is crucial for robust file operations.

Core Concepts

Windows uses a hierarchical file system structure. Paths are strings that identify the location of a file or directory within this structure. Filenames refer to the actual name of the file or directory.

Path Delimiters

The primary path delimiter in Windows is the backslash (\). However, many APIs also accept the forward slash (/) for compatibility and convenience.

Drive Letters

Drives are typically identified by a drive letter followed by a colon (e.g., C:). Network shares are represented using UNC (Universal Naming Convention) paths, starting with two backslashes (e.g., \\ServerName\ShareName).

Key Functions

Manipulating Paths

• PathCombine: Combines two path components into a single path.
• PathGetExtension: Retrieves the file extension from a path.
• PathGetFileName: Retrieves the filename from a path.
• PathIsRelative: Determines if a path is relative.
• PathCanonicalize: Creates an absolute, canonical path from a given path.

Working with Filenames

• GetLongPathName: Retrieves the long path name for a specified path.
• GetShortPathName: Retrieves the short (8.3) path name for a specified path.

Important Structures

WIN32_FIND_DATA

This structure is used by functions like FindFirstFile and FindNextFile to retrieve information about files and directories, including their names.

Best Practices

• Always use API functions for path manipulation to ensure correctness and avoid issues with different path formats or special characters.
• Be mindful of path length limitations, especially when dealing with older systems or specific file systems. Use functions like GetLongPathName when necessary.
• Handle potential errors gracefully by checking return values of API functions.
• Consider using the Windows API functions for path parsing rather than manual string manipulation to correctly handle edge cases.

---

PathCombine

Combines two path components into a single path. This function is safer than manual string concatenation because it handles path delimiters correctly.

    LPTSTR PathCombine(
      LPTSTR  lpszDest,
      LPCTSTR lpszDir,
      LPCTSTR lpszFile
    );
        

Parameters:

• lpszDest: A pointer to a buffer that receives the combined path.
• lpszDir: The directory path.
• lpszFile: The filename or subdirectory path.

Return Value: A pointer to the combined path string if successful, or NULL otherwise.

PathGetExtension

Retrieves the file extension from a path string.

    LPTSTR PathGetExtension(
      LPCTSTR pszPath
    );
        

Parameters:

• pszPath: The path string.

Return Value: A pointer to the extension string (including the period) or an empty string if no extension is found.

PathGetFileName

Retrieves the filename and extension from a path string.

    LPTSTR PathGetFileName(
      LPCTSTR pszPath
    );
        

Parameters:

• pszPath: The path string.

Return Value: A pointer to the filename string. If the path ends with a backslash, it returns a pointer to the last component before the backslash.

PathIsRelative

Determines if a path string is relative.

    BOOL PathIsRelative(
      LPCTSTR pszPath
    );
        

Parameters:

• pszPath: The path string to check.

Return Value: TRUE if the path is relative, FALSE otherwise.

PathCanonicalize

Creates an absolute, canonical path from a given path. This function resolves relative path components (like "." and "..") and simplifies the path.

    BOOL PathCanonicalize(
      LPTSTR lpszCanonicalPath,
      LPCTSTR lpszPath
    );
        

Parameters:

• lpszCanonicalPath: A pointer to a buffer that receives the canonical path.
• lpszPath: The path string to canonicalize.

Return Value: TRUE if successful, FALSE otherwise.

GetLongPathName

Retrieves the long path name for the specified path. Long path names can exceed the 260-character limit of the traditional MAX_PATH.

    DWORD GetLongPathName(
      LPCTSTR lpszShortPath,
      LPTSTR  lpszLongPath,
      DWORD   cchBuffer
    );
        

Parameters:

• lpszShortPath: The short path string.
• lpszLongPath: A pointer to a buffer that receives the long path.
• cchBuffer: The size of the lpszLongPath buffer in characters.

Return Value: The length of the string copied to lpszLongPath, in characters, not including the terminating null character. If the buffer is too small, it returns the required buffer size.

GetShortPathName

Retrieves the short (8.3) path name for the specified path.

    DWORD GetShortPathName(
      LPCTSTR lpszLongPath,
      LPTSTR  lpszShortPath,
      DWORD   cchBuffer
    );
        

Parameters:

• lpszLongPath: The long path string.
• lpszShortPath: A pointer to a buffer that receives the short path.
• cchBuffer: The size of the lpszShortPath buffer in characters.

Return Value: The length of the string copied to lpszShortPath, in characters, not including the terminating null character. If the buffer is too small, it returns the required buffer size.