// ==================================================================
//
// Path.h
//
// Created: 03.03.2005
//
// Copyright (C) Peter Hauptmann
//
// ------------------------------------------------------------------
//
/// \page pgDisclaimer Copyright & Disclaimer
///
/// Copyright (C) 2004-2005 Peter Hauptmann
/// all rights reserved
/// more info: http://www.codeproject.com/phShellPath.asp
/// Please contact the author with improvements / modifications.
///
/// Redistribution and use in source and binary forms, with or without
/// modification, are permitted under the following conditions:
/// - Redistribution of source must retain the copyright above,
/// and the disclaimer below.
/// - Modifications to the source should be marked clearly, to be
/// distinguishable from the original sources.
///
/// THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
/// ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
/// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
/// ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
/// FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
/// DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
/// OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
/// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
/// LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
/// OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
/// SUCH DAMAGE.
///
#ifndef FILE_PH_PATH_H_200506202_INCLUDED_
#define FILE_PH_PATH_H_200506202_INCLUDED_
#if _MSC_VER > 1000
#pragma once
#endif
#include <comdef.h> // for _bstr_t extractor only, can be removed if you don't need CPath::GetBStr()
#include "shlwapi.h"
#pragma once
/// The nsPath namespace contains the CPath class and global helper functions.
namespace nsPath
{
// ---------------- DECLARATIONS --------------------------------------------
// ----- CString Helpers ---------
void Trim(CString & s);
TCHAR GetFirstChar(CString const & s); ///< returns the first char of the string, or 0 if the string length is 0.
TCHAR GetLastChar(CString const & s); ///< returns the last char of the string, or 0 if the string length is 0.
TCHAR GetDriveLetter(TCHAR ch);
TCHAR GetDriveLetter(LPCTSTR s);
CString QuoteSpaces(CString const & str);
// ==================================================================
// ERootType
// ------------------------------------------------------------------
///
/// Recognized root types for a path.
/// see nsPath::GetRootType "GetRootType" for more.
///
/// \c len refers to the rootLen parameter optionally returned by \c GetRootType.
///
enum ERootType
{
rtNoRoot = 0, ///< no, or unknown root (\c len = 0)
rtDriveRoot = 1, ///< a drive specification with backslash ("C:\", \c len = 3)
rtDriveCur = 2, ///< a drive specification without backslash ("C:", \c len = 2)
// rtPathRoot = 3, ///< a path root, i.e. staring with a single backslash (nyi, \c len = 1)
rtLongPath = 4, ///< a UNC long path specification (e.g. "\\?\C:\", \c len is length of path root + 4), no distinction for "root / current" is made
rtServerOnly = 5, ///< a server only specification (e.g. "\\fileserv" or "\\fileserv\", \c len is the string length)
rtServerShare = 6, ///< server + share specification ("\\server\share", \c len includes the backslash after share if given)
rtProtocol = 7, ///< protocol, ("http://", \c len includes the "://" part)
rtPseudoProtocol = 8, ///< pseudo protocol (no slahes) ("mailto:", \c len includes the colon)
rtServer = 9, ///< server with share following (for GetRootType(_,_,greedy=false)
};
ERootType GetRootType(LPCTSTR path, int * pLen, bool greedy = true);
// ==================================================================
// nsPath::EPathCleanup
// ------------------------------------------------------------------
/// Flags for nsPath::CPath::Cleanup
///
enum EPathCleanup
{
epcTrim = 1, ///< trim outer whitespace
epcUnquote = 2, ///< remove single or double quotes
epcTrimInQuote = 4, ///< trim whitespaces inside quotes
epcCanonicalize = 8, ///< Canonicalize (collapse "\\..\\" and "\\.\\")
epcRemoveXXL = 16, ///< Remove "\\\\?\\" and "\\\\?\\UNC\\" markers
epcSlashToBackslash = 32, ///< replace forward slashes with backslashes
epcMakePretty = 64, ///< Windows' idea of a pretty path
epcRemoveArgs = 128, ///< calls PathRemoveArgs (before trimming/unquoting)
epcRemoveIconLocation = 256, ///< Remove Icon location from the path
epcExpandEnvStrings = 512, ///< Expand environment strings
epc_Default = epcTrim |
epcUnquote |
epcTrimInQuote |
epcCanonicalize |
epcRemoveXXL |
epcExpandEnvStrings, ///< default for CTors and Assignment operators
};
// ==================================================================
// nsPath::EPathPacking
// ------------------------------------------------------------------
///
/// Flags for nsPath::CPath::GetStr
/// \note
/// eppAutoQuote was ignored in Version 1.2 and before.
/// It is fixed since V.1.3 (August 2005), /// but was removed from
/// epp_Default for backward compatibility
///
enum EPathPacking
{
eppAutoQuote = 1, ///< Quote the path if it contains spaces
eppAutoXXL = 2, ///< If path length is > MAX_PATH, use "\\\\?\\" syntax
eppBackslashToSlash = 4, ///< turn backslashes into forward slashes
epp_Default = eppAutoXXL,
};
// ==================================================================
// nsPath::CPath
// ------------------------------------------------------------------
///
///
///
class CPath
{
protected:
CString m_path;
void CAssign(CString const & src);
public:
//@{ \name Construction
CPath() {}
CPath(LPCSTR path); ///< Assigns \c path. CPath::Clean(epc_Default) is called for cleanup
CPath(LPCWSTR path); ///< Assigns \c path. CPath::Clean(epc_Default) is called for cleanup
CPath(CString const & path); ///< Assigns \c path CPath::Clean(epc_Default) is called for cleanup
CPath(CPath const & path); ///< Assigns \c path to the path. Does \b not modify the assigned path!
CPath(CString const & path, DWORD cleanup); ///< Assigns \c path, using custom cleanup options (see CPath::Clean)
//@}
//@{ \name Assignment
CPath & operator=(LPCSTR rhs); ///< Assigns \c path, and calls CPath::Clean(epc_Default)
CPath & operator=(LPCWSTR rhs); ///< Assigns \c path, and calls CPath::Clean(epc_Default)
CPath & operator=(CString const & rhs); ///< Assigns \c path, and calls CPath::Clean(epc_Default)
CPath & operator=(CPath const & rhs); ///< Assigns \c path Does \b not call CPath::Clean!
CPath & Assign(CString const & str, DWORD cleanup = epc_Default);
//@}
//@{ \name Miscellaneous Query
operator LPCTSTR () const { return m_path.operator LPCTSTR(); }
int GetLength() const { return m_path.GetLength(); } ///< returns the length of the path, in characters
//@}
//@{ \name Path concatenation
CPath & operator &=(LPCTSTR rhs);
CPath & Append(LPCTSTR appendix);
CPath & AddBackslash();
CPath & RemoveBackslash();
//@}
//@{ \name Splitting into Path Segments
CString ShellGetRoot() const;
CPath GetPath(bool includeRoot = true) const;
CString GetName() const;
CString GetTitle() const;
CString GetExtension() const;
ERootType GetRootType(int * len = 0, bool greedy = true) const;
CString GetRoot(ERootType * rt = NULL, bool greedy = true) const;
CString SplitRoot(ERootType * rt = NULL);
int GetDriveNumber();
TCHAR GetDriveLetter();
//@}
//@{ \name Add / Modify / Remove parts
CPath & AddExtension(LPCTSTR extension, int len = -1);
CPath & RemoveExtension();
CPath & RenameExtension(LPCTSTR newExt);
CPath & RemoveFileSpec();
//@}
//@{ \name Cleanup
CPath & Trim();
CPath & Unquote();
CPath & Canonicalize();
CPath & ShrinkXXLPath();
CPath & MakePretty();
CPath & Clean(DWORD cleanup = epc_Default);
//@}
//@{ \name Extractors (with special "packing")
CString GetStr(DWORD packing = epp_Default) const;
_bstr_t GetBStr(DWORD packing = epp_Default) const;
//@}
//@{ \name Static checking (not accessing file system, see also GetRootType)
bool IsValid() const;
bool IsDot() const;
bool IsDotDot() const;
bool IsDotty() const; // IsDot || IsDotDot
bool MatchSpec(LPCTSTR spec);
bool IsContentType(LPCTSTR contentType) { return 0 != ::PathIsContentType(m_path, contentType); } ///< compare content type registered for this file, see also MSDN: PathIsContentType
bool IsFileSpec() { return 0 != ::PathIsFileSpec(m_path); } ///< true if path does not contain backslash, see MSDN: PathIsFileSpec
bool IsPrefix(LPCTSTR prefix) { return 0 != ::PathIsPrefix(m_path, prefix); } ///< checks if the path starts with a prefix like "C:\\", see MSDN: PathIsPrefix
bool IsRelative() { return 0 != ::PathIsRelative(m_path); } ///< returns true if the path is relative, see MSDN: PathIsRelative
bool IsRoot() { return 0 != ::PathIsRoot(m_path); } ///< returns true if path is a directory root, see MSDN: PathIsRoot
bool IsSameRoot(LPCTSTR other) { return 0 != ::PathIsSameRoot(m_path, other); } ///< returns true if the path has the same root as \c otherPath, see MSDN: IsSameRoot
bool IsUNC() { return 0 != ::PathIsUNC(m_path); } ///< returns true if the path is a UNC specification, see MSDN: PathIsUNC
bool IsUNCServer() { return 0 != ::PathIsUNCServer(m_path); } ///< returns true if the path is a UNC server specification, see MSDN: PathIsUNCServer
bool IsUNCServerShare() { return 0 != ::PathIsUNCServerShare(m_path); } ///< returns true if the path is a UNC server + share specification, see MSDN: PathIsUNCServerShare
bool IsURL() { return 0 != ::PathIsURL(m_path); } ///< returns true if the path is an URL, see MSDN: PathIsURL
// bool IsHTMLFile() { return 0 != ::PathIsHTMLFile(m_path); } ///< (missing?) true if content type registered for this file is HTML, see MSDN: PathIsHTMLFile
// bool IsLFNFileSpec() { return 0 != ::PathISLFNFileSpec(m_path); } ///< (missing?) true if file is not a 8.3 file, see MSDN: PathIsLFNFileSpec
// bool IsNetworkPath() { return 0 != ::PathIsNetworkPath(m_path); } ///< (missing?) returns true if the path is on a network, see MSDN: PathIsNetworkPath
//@}
//@{ \name Relative Paths
CPath GetCommonPrefix(LPCTSTR secondPath);
CPath RelativePathTo(LPCTSTR pathTo, bool srcIsDir = true);
bool MakeRelative(CPath const & basePath);
bool MakeAbsolute(CPath const & basePath);
//@}
//@{ \name Dialog control operations
CString GetCompactStr(HDC dc, UINT dx, DWORD eppFlags = 0);
CString GetCompactStr(UINT cchMax, DWORD eppFlags = 0, DWORD flags = 0);
void SetDlgItem(HWND dlg, UINT dlgCtrlID, DWORD eppFlags = 0);
//@}
//@{ \name File System / Environment-Dependent operations
CPath & SearchAndQualify();
CPath & FindOnPath(LPCTSTR * additionalDirs = 0);
bool Exists() const;
bool IsDirectory() const;
bool IsSystemFolder(DWORD attrib = FILE_ATTRIBUTE_SYSTEM) const;
CPath & MakeSystemFolder(bool make = true);
DWORD GetAttributes();
bool GetAttributes(WIN32_FILE_ATTRIBUTE_DATA & fad);
CPath & MakeFullPath();
CPath & ExpandEnvStrings();
bool EnvUnexpandRoot(LPCTSTR envVar);
bool EnvUnexpandDefaultRoots();
long ToRegistry(HKEY baseKey, LPCTSTR subkey, LPCTSTR name, bool replaceEnv = true);
//@}
// TODO: Shell 5.0 support
// V5: CPath & UnexpandEnvStrings();
// V5: LPCTSTR FindSuffixArray(LPCTSTR suffixes, int numSuffixes);
// V5: void PathUndecorate();
// V5: CPath PathCreateFromURL(LPCTSTR path, DWORD dwReserved = 0);
// V5: bool IsDirectoryEmpty() const;
// might be useful for later extensions: PathGetCharType
};
// creation functions:
CPath SplitArgs(CString const & path_args, CString * args = NULL, DWORD cleanup = epc_Default);
CPath SplitIconLocation(CString const & path_icon, int * pIcon = NULL, DWORD cleanup = epc_Default);
CPath BuildRoot(int driveNumber);
CPath GetModuleFileName(HMODULE module = NULL);
CPath GetCurrentDirectory();
CPath FromRegistry(HKEY baseKey, LPCTSTR subkey, LPCTSTR name);
CString ReplaceInvalid(CString const & str, TCHAR replaceChar = '_');
// concatenation
inline CPath operator & (CPath const & lhs, LPCTSTR rhs) { CPath ret = lhs; ret &= rhs; return ret; }
// ---------------- INLIME IMPLEMENTATIONS ----------------------------------
// ==============================================
// GetFirstChar
// ----------------------------------------------
/// \return [TCHAR]: the first char of the string, or 0 if the string length is 0.
/// \note The implementation takes care that the string is not copied when there are no spaces.
inline TCHAR GetFirstChar(CString const & s)
{
if (s.GetLength() == 0)
return 0;
else
return s[0];
}
// ==============================================
// GetLastChar
// ----------------------------------------------
/// \return [TCHAR]: the last character in the string, or 0 if the string length is 0.
/// \par Note
/// \b MBCS: if the string ends with a Multibyte character, this
/// function returns the lead byte of the multibyte sequence.
inline TCHAR GetLastChar(CString const & s)
{
LPCTSTR pstr = s;
LPCTSTR pLastChar = _tcsdec(pstr, pstr + s.GetLength());
if (pLastChar == NULL)
return 0;
else
return *pLastChar;
}
} // namespace nsPath
#endif // FILE_PH_PATH_H_200506202_INCLUDED_
Submit an article or tip