|
GCPathUtilitiesDLL
Version 1.0
Developer’s Guide
Developed By: George E. Chastain
All rights reserved.
Download the Visual C++ Project (self-extracting exe).
Overview
This library provides a class, CGCPathString, which allows a client to manipulate a string as a path or path/file combination. It provides a battery of methods that allow the client to perform many types of operations on paths and filenames.
The library also provides a class, CGCPathEnvironment, which obtains and parses the current value of the System PATH environment variable.
Another class, CGCURL, is provided to manipulate strings that are URL addresses.
Workspace And Projects
Two workspaces and project files are provided. The workspaces are "GCPathUtilitiesDLL.dsw" and "GCPathUtilitiesStatic.dsw". The projects provided are "GCPathUtilitiesDLL.dsp" and "GCPathUtilitiesStatic.dsp". Each of the workspaces provides access to both projects to allow the developer to build either a DLL version of the library or a static version. The GCPathUtilitiesDLL.dsp builds a DLL called GCPathUtilitiesDLL.dll. The GCPathUtilitiesStatic.dsp builds a static library called GCPathUtilities.lib.
The DLL version exports via the Module Definition File (*.DEF). This will allow future additions to the class to be made without the need to relink any previously delivered modules that depend on the DLL. However, the developer must not change the declarations or return values for any method already delivered or all previously-delivered modules will have to be relinked with the GCPathUtilitiesDLL DLL's import library.
Dependencies
Both the GCPathUtilitiesDLL.dll and the GCPathUtilities.lib are dependent on the shlwapi.lib and shlwapi.dll as well as wininet.lib and wininet.dll delivered with the Internet Explorer 5.0 or newer.
Both the dynamic and static versions of the library are dependent on the dynamic version of MFC and the C Run-Time libraries. However, you are free to change this if desired.
Preferred Load Address
Both the release and the debug configurations of the DLL projects specify a default Preferred Load Address of 0x60000000. You may wish to change this if it conflicts with any of your other DLLs.
Class CGCPathString
This class is publicly derived from the MFC CString class so all methods available for the CString class are available to the CGCPathString class. When declaring variables of this type, the developer should declare variables of type GC_PATHNAME_TYPE that, currently, is a typedef to the CGCPathString class type. When building the DLL version of the library, the preprocessor constant "BUILD_DLL" should be defined. When building the static version of the library, the preprocessor constant "BUILD_STATIC" should be defined.
The classes are defined by the header file "GCPathUtilities.h". This header file should be included anywhere you intend to use objects of this class.
Possible Return Status
All methods of the CGCPathString class, with the exception of the constructors, return a status of type GC_PATH_ERROR_TYPE. The possible return status values are:
GC_INVALID_PATH_FILENAME
The value of the object on which the method was invoked does not contain a valid path or is empty.
GC_SUCCESS
Successful operation.
GC_INVALID_PARAMETER
Parameter passed into a method was empty or invalid.
GC_STRING_NOT_FOUND
String specified to be substituted in the path was not found.
GC_ENV_UNDEFINED
An environment variable in the current path is not defined and was not expanded.
GC_GENERAL_ERROR
An unknown error occurred.
METHODS
GC_PATH_ERROR_TYPE GetPathOnly(GC_PATHNAME_TYPE& sPath);
Sets sPath to the path portion of the object. If the object contains no path, then sPath is set to ".". Method returns GC_SUCCESS if successful. It will return GC_INVALID_PATH_FILENAME if the object that this method is being invoked on is empty and sets sPath to "".
GC_PATH_ERROR_TYPE GetFileNameWithExtension(CString& sFileAndExtension)
Returns only the filename spec, with extension in sFileAndExtension. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME the object that this method is being invoked on is empty and sets sFileAndExtension to "".
GC_PATH_ERROR_TYPE GetFileExtensionOnly(CString&
sExtension);
Sets sExtension to the file's extension and returns GC_SUCCESS. Sets sExtension to "" and returns GC_INVALID_PATH_FILENAME if the object that this method is being invoked on is empty or does not contain an extension.
GC_PATH_ERROR_TYPE GetDrive(CString& sDrive);
Sets sDrive to the drive portion of the path and returns GC_SUCCESS. Sets sDrive to "" and returns GC_INVALID_PATH_FILENAME if the object that this method is being invoked on is empty or does not contain a drive specification.
GC_PATH_ERROR_TYPE GetDOSPath(GC_PATHNAME_TYPE& sDOSPath) const;
Sets sDOSPath to the DOS (short) representation of this object and returns GC_SUCCESS. Sets sDOSPath to "" and returns GC_INVALID_PATH_FILENAME if the object this method is being invoked on is empty. Sets sDOSPath to null string and returns GC_INVALID_PATH_FILENAME if the path is either a UNC format or a URL path.
GC_PATH_ERROR_TYPE GetLongPath(GC_PATHNAME_TYPE& sLongPath) const;
Sets sLongPath to the long representation of this object and returns GC_SUCCESS. Sets sLongPath to "" and returns GC_INVALID_PATH_FILENAME if this object is empty. Sets sDOSPath to null string and returns GC_INVALID_PATH_FILENAME if the path does not exist.
IMPORTANT: In order for the method GetLongPath() to successfully convert a DOS short path to a long path, the folder or file being referenced must exist. This is the only way that the short path can be converted to a long path since a folder can have different names on two different systems but the same DOS short path could represent them both. For example, "C:\This is a really long folder name" on machine A could be converted to "C:\This i~1". A folder named "C:\This is another really long folder name" on machine B could also be converted to the DOS name "C:\This i~1". Given this dynamic nature of the DOS path/filename conversion, the only way to convert it to a long path name is if it exists.
GC_PATH_ERROR_TYPE ExpandPath();
Expands a relative path to the fully qualified, absolute path and returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if this object is empty.
As an example, the path "..\GCPathUtilitiesDLL\Debug\GCPathUtilitiesDLL.dll" would be converted to something like "C:\GEC\Visual_C_Projects\GCPathUtilitiesDLL\Debug\GCPathUtilitiesDLL.dll".
Another example, the path ..\GCPATH~1\DEBUG\GCPATH~1.dll would be converted to "C:\GEC\VISUAL_C_PROJECTS\GCPATH~1\DEBUG\GCPATH~1.dll.
Note that no attempt is made to convert the DOS short path portions to a the long path name. If this is desired, you should take the result and call GetLongPath(). However, as noted in the description of GetLongPath(), the path must exist in order to successfully convert the DOS portions to the long names.
GC_PATH_ERROR_TYPE GetDepth(int& iDepth);
Sets iDepth to the number of folders in the path up to and including the last folder in the path and returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME and sets iDepth to 0 if this object is empty.
GC_PATH_ERROR_TYPE SubstituteFolder(const CString sFolderToChange,
const CString sNewFolder);
Allows the client to substitute the part of the path specified by sFolderToChange with the path string specified by sNewFolder. This can only be used to substitute part of a path, not including the final component (path or filename). Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty. Returns GC_INVALID_PARAMETER if either sFolderToChange or sNewFolder are empty. Returns GC_STRING_NOT_FOUND if sFolderToChange is not found in the path.
Client must specify the full folder name for both sFolderToChange and sNewFolder. For example, given the path "C:\FolderA\FolderB\FolderC\Junk.txt", the client could call SubstituteFolder("FolderB","FolderG"). In this case, the path would become "C:\FolderA\FolderG\FolderC\Junk.txt". The client may also add slashes to the strings as in SubstituteFolder("\\FolderB\\", "\\FolderG\\"); The client may also substitute more than one folder in the string at a time as in Substitute("\\FolderB\\FolderC","\\FolderG\\"). In this case the original path would become "C:\FolderA\GolderG\Junk.txt". Returns GC_SUCCESS upon successful substitution.
GC_PATH_ERROR_TYPE SubstituteExtension(const CString sNewExtension);
Allows the client to substitute the extension with the string specified in sNewExtension. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty. Returns GC_INVALID_PARAMETER if sNewExtension is empty. Returns GC_INVALID_PATH_FILENAME if the path does not contain an extension. GC_INVALID_PATH_FILENAME if the path has a slash on the end. Returns GC_SUCCESS upon successful substitution.
GC_PATH_ERROR_TYPE SubstituteFileAndExtension(const CString sNewFileAndExtension);
Allows the client to substitute the final component in the path with the string specified by sNewFileAndExtension. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty. Returns GC_INVALID_PARAMETER if sNewFileAndExtension is empty. Returns GC_INVALID_PATH_FILENAME if the path has a slash on the end. Returns GC_SUCCESS upon successful substitution.
GC_PATH_ERROR_TYPE SubstituteDrive(const CString sNewDrive);
Allows the client to substitute the drive specification with the one specified by sNewDriver. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is invoked is empty or does not contain a drive specified.
GC_PATH_ERROR_TYPE ExpandEnvironmentStrings();
Allows the client to expand all environment variables that may be contained in the path to their current values. Any environment variables not defined are left unconverted. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is invoked is empty. Returns GC_STRING_NOT_FOUND if there are no environment variables in the current path.
GC_PATH_ERROR_TYPE Quote();
If the path contains any spaces, the entire path is enclosed in double quotes. A call to this method has no effect if there are no spaces in the current path. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty.
GC_PATH_ERROR_TYPE UnQuote();
If the path is enclosed in double quotes, the quotes will be removed. A call to this method has no effect if there are no quotes around the current path. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty.
GC_PATH_ERROR_TYPE IsUNC(BOOL& bResult) const;
Sets bResult to TRUE if the current path is in UNC (Universal Naming Convention for server/share path) format and returns GC_SUCCESS. If the current path is not UNC, bResult is set to FALSE and the method returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE GetServer(CString& sServer) const
Sets sServer to the server name if the current path is a UNC path and returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME and sets sServer to empty if the object on which this method is being invoked is empty or if it isn't a UNC path.
GC_PATH_ERROR_TYPE IsSystemFolder(BOOL& bResult) const;
Sets bResult to TRUE if the current path has the System Folder attribute and returns GC_SUCCESS. If the current path is not a System Folder, bResult is set to FALSE and the method returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE ContainsSystemRoot(BOOL& bResult) const;
Sets bResult to TRUE if the current path has contains the System Root path and returns GC_SUCCESS. If the current path does not contain the System Root path, bResult is set to FALSE and the method returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE. Note that this method uses the value of the SystemRoot environment variable when checking the current path. If this variable is undefined, bResult will always be set to FALSE.
GC_PATH_ERROR_TYPE IsURL(BOOL& bResult) const;
Sets bResult to TRUE if the current path is in URL format and returns GC_SUCCESS. If the current path is not URL, bResult is set to FALSE and the method returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE IsRelative(BOOL& bResult) const
Sets bResult to TRUE if the current path is a relative path and returns GC_SUCCESS. Sets bResult to FALSE and returns GC_SUCCESS if the current path is not a relative path. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE AddBackslash()
Adds a backslash to the end of the current path and returns GC_SUCCESS. This method will work regardless of whether or not the current path is surrounded by double quotes. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE RemoveBackslash();
Removes any backslash that may be at the end of the path. This method will work regardless of whether or not the current path is surrounded by double quotes. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE RemoveExtension();
Removes the extension that may be at the end of the path. This method will work regardless of whether or not the current path is surrounded by double quotes. Returns GC_SUCCESS if successful. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE Exists(BOOL& bResult) const;
Sets bResult to TRUE if the current path exists and returns GC_SUCCESS. Sets bResult to FALSE and returns GC_INVALID_PATH_FILENAME if the path does not exist. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE IsDirectory(BOOL& bResult) const
Sets bResult to TRUE and returns GC_SUCCESS if the path points to a valid disk folder. Sets bResult to FALSE and returns GC_SUCCESS if the path does not point to a valid disk folder. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE Canonicalize();
Expands and properly replaces all the instances of .. and . that the path may contain and returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE.
GC_PATH_ERROR_TYPE BreakdownPath(PATHCOMPONENTSTYPE& vComponents);
Returns all the path components in the vector vComponents and returns GC_SUCCESS. Returns GC_INVALID_PATH_FILENAME if the object on which this method is being invoked is empty and sets bResult to FALSE. As an example, if the object had the value "C:\TEMP\temp.dat", then vComponents will have three elements. Element 0 would be "C:", element 1 would be "TEMP" and element 2 would be "temp.dat".
GC_PATH_ERROR_TYPE ValidateQuotes(BOOL& bResult) const;
Sets bResult to TRUE if the string has valid quotation or contains no quotation marks and returns GC_SUCCESS. Sets bResult to FALSE and returns GC_INVALID_PATH_FILENAME if invalid quotation exists or if the object on which this method is being invoked is empty.
explicit CGCPathString(const CString& sPath);
Constructor to convert a CString object to a CGCPathString class object. The constructor is declared explicit so that no unexpected conversions take place and some level of individuality between the CGCPathString class and the CString class will be maintained. They are logically related but distinct entities.
explicit CGCPathString(const char* sPath);
Constructor to convert a char* string to a CGCPathString. It too is declared explicit for the reasons described above.
CGCPathString(const CGCPathString& sPath);
Copy constructor for the class.
CGCPathString operator=(const CGCPathString& val);
Assignment operator to allow a CGCPathString to be assigned to another of the same type.
CGCPathString operator=(const CString& val);
Assignment operator to allow a CString object to be assigned to a CGCPathString object.
Class CGCPathEnvironment
The CGCPathEnvironment class allows a client to obtain the current value of the PATH system environment variable. The class also provides a method to allow the client to obtain each individual path within the PATH environment variable as separate elements in a vector.
void GetEnvPathComponents(PATHCOMPONENTSTYPE& vComponents);
Allows the client to obtain the PATH environment variable value with all the individual paths (the strings separated by ";") assigned to different elements in the vComponents vector. As an example: If the current value of the PATH environment variable is "C:\WINNT;C:\WINNT\SYSTEM32", then the first element of vComponents will be "C:\WINNT" and the second element of the vector will be "C:\WINNT\SYSTEM32".
CGCPathEnvironment();
Default constructor.
CGCPathEnvironment operator=(const CGCPathEnvironment& val);
Assignment operator.
Class CGCURL
Allows a client to extract data from a URL string.
CGCURL();
Default constructor.
explicit CGCURL(const CString& sPath);
Explicit conversion constructor that allows a CGCURL object to be created from a CString object.
explicit CGCURL(const char* sPath);
Explicit conversion constructor that allows a CGCURL object to be created from a char* object.
CGCURL(const CGCURL& sPath);
Copy constructor.
CGCURL operator=(const CGCURL& val);
Assignment operator to assign one CGCURL to another.
CGCURL operator=(const CString& val);
Assignment operator to assign a CString to a CGCURL.
GC_PATH_ERROR_TYPE GetScheme(INTERNET_SCHEME& iScheme) const;
Allows the client to obtain the scheme from the URL. Sets iScheme to the scheme of the URL and return GC_SUCCESS. The iScheme returned may be any one of the following enumerated values:
INTERNET_SCHEME_PARTIAL = -2
INTERNET_SCHEME_UNKNOWN = -1
INTERNET_SCHEME_DEFAULT = 0
INTERNET_SCHEME_FTP
INTERNET_SCHEME_GOPHER
INTERNET_SCHEME_HTTP
INTERNET_SCHEME_HTTPS
INTERNET_SCHEME_FILE
INTERNET_SCHEME_NEWS
INTERNET_SCHEME_MAILTO
INTERNET_SCHEME_SOCKS
INTERNET_SCHEME_JAVASCRIPT
INTERNET_SCHEME_VBSCRIPT
INTERNET_SCHEME_FIRST = INTERNET_SCHEME_FTP
INTERNET_SCHEME_LAST = INTERNET_SCHEME_VBSCRIPT
Sets iScheme to INTERNET_SCHEME_UNKNOWN and returns GC_INVALID_URL if the object on which the method is being invoked is empty.
GC_PATH_ERROR_TYPE GetHostName(CString& Host) const;
Sets Host equal to the Host part of the URL and returns GC_SUCCESS. Sets Host to "" and returns GC_INVALID_URL if the object on which the method is being invoked is empty.
GC_PATH_ERROR_TYPE GetUserName(CString& User) const;
Sets User to the user ID part (if any) of the URL and return GC_SUCCESS. Sets User to "" and returns GC_INVALID_URL if the object on which the method is being invoked is empty.
GC_PATH_ERROR_TYPE GetPassword(CString& Pwd) const;
Sets Pwd to the password part of the URL (if any) and returns GC_SUCCESS. Sets Pwd to "" and returns GC_INVALID_URL if the object on which the method is being invoked is empty.
GC_PATH_ERROR_TYPE GetURLPath(CString& Path) const;
Sets Path to the path part of the URL (if any) and returns GC_SUCCESS. Sets Path to "" and returns GC_INVALID_URL if the object on which the method is being invoked is empty.
GC_PATH_ERROR_TYPE Canonicalize(DWORD ConversionFlags);
Canonicalizes the URL of the object on which the method is being invoked. The ConversionFlags parameter may be any of the following as defined in shlwapi.h:
URL_DONT_SIMPLIFY
Treat '/./' and '/../' in a URL string as literal characters, not as shorthand for navigation. See Remarks for further discussion.
URL_ESCAPE_PERCENT
Convert any occurrence of '%' to its escape sequence.
URL_ESCAPE_SPACES_ONLY
Replace only spaces with escape sequences. This flag takes precedence over URL_ESCAPE_UNSAFE, but does not apply to opaque URLs.
URL_ESCAPE_UNSAFE
Replace unsafe values with their escape sequences. This flag applies to all URLs, including opaque URLs.
URL_PLUGGABLE_PROTOCOL
Combine URLs with client-defined pluggable protocols, according to the W3C specification. This flag does not apply to standard protocols such as ftp, http, gopher, and so on. If this flag is set, UrlCombine will not simplify URLs, so there is no need to also set URL_DONT_SIMPLIFY.
URL_UNESCAPE
Unescape any escape sequences that the URLs contain, with two exceptions. The escape sequences for '?' and '#' will not be unescaped. If one of the URL_ESCAPE_XXX flags is also set, the two URLs will unescaped, then combined, then escaped.
Returns GC_URL_CANONICALIZE_ERROR if an error occurred while trying to canonicalize the URL. Returns GC_INVALID_URL if the object on which this method is being invoked is empty.
NOTICE: Only available when compiled with systems running Windows 98, 95, NT 4.0 or 2000 with Internet Explorer 5.5 or newer installed and Internet Explorer 5.5 headers and libraries and Windows 2000 SDK. See the following link for details:
http://msdn.microsoft.com/downloads/samples/internet/libraries/ie55_lib/
GC_PATH_ERROR_TYPE CGCURL::Compare(CGCURL&
Target,int ComparisonResults) const
Compares two URLs to see if they are equal. It first performs a canonicalization of both URLs. If the two URLs are equal, the API sets ComparisonResults to zero. If the URL of the object on which this method is being invoked is less than the URL in object Target, ComparisonResults is set to a negative value. Otherwise, ComparisonResults is set to a positive value.
Returns GC_INVALID_URL if either the object on which the method is being invoked is empty or Target is empty. Returns GC_URL_CANONICALIZE_ERROR if an error occurred performing canonicalization on either object.
NOTICE: Only available when compiled with systems running Windows 98, 95, NT 4.0 or 2000 with Internet Explorer 5.5 or newer installed and Internet Explorer 5.5 headers and libraries and Windows 2000 SDK. See the following link for details:
http://msdn.microsoft.com/downloads/samples/internet/libraries/ie55_lib/
Thread Safety
By default, the classes provided by the GCPathUtilities Library are thread safe. However, if thread safety is not needed (perhaps for speed), the developer may build the library without thread safety by defining the _GCNOTS preprocessor directive when building the library.
The thread safety code is only built into the DLL version of the library. Thread safety is not needed in the static version of the library. So, even if you do not define _GCNOTS and you build the static version of the library, it will be as if you had defined the _GCNOTS preprocessor directive.
Download the Visual C++ Project
(self-extracting exe). Top |
